From 4c1118d130c5b2dd8aef5ef486138db002dcfda7 Mon Sep 17 00:00:00 2001 From: 1138-4EB <1138-4EB@users.noreply.github.com> Date: Sun, 19 Feb 2017 08:12:30 +0100 Subject: Removed numbers from folder names. --- doc/intro/Contributing.rst | 77 ++++++++++++++++++++++++++++++++++++++++++++++ doc/intro/Copyrights.rst | 55 +++++++++++++++++++++++++++++++++ doc/intro/WhatIsGHDL.rst | 29 +++++++++++++++++ doc/intro/WhatIsVHDL.rst | 35 +++++++++++++++++++++ 4 files changed, 196 insertions(+) create mode 100644 doc/intro/Contributing.rst create mode 100644 doc/intro/Copyrights.rst create mode 100644 doc/intro/WhatIsGHDL.rst create mode 100644 doc/intro/WhatIsVHDL.rst (limited to 'doc/intro') diff --git a/doc/intro/Contributing.rst b/doc/intro/Contributing.rst new file mode 100644 index 000000000..8a0ba30bc --- /dev/null +++ b/doc/intro/Contributing.rst @@ -0,0 +1,77 @@ +.. _INTRO:Contributing: + +Contributing +############ + +Despite all the testing and already reported `issues `_, you can find bugs +or propose enhancements. + + .. _reporting_bugs: + +Asking for enhancements +============== + +Reporting bugs +============== + +In order to improve GHDL, we welcome bugs report and suggestions for +any aspect of GHDL. Please create an issue on +https://github.com/tgingold/ghdl/issues + +If the compiler crashes, this is a bug. Reliable tools never crash. + +If your compiled VHDL executable crashes, this may be a bug at +runtime or the code produced may be wrong. However, since VHDL +has a notion of pointers, an erroneous VHDL program (using invalid +pointers for example) may crash. + +If the compiler emits an error message for a perfectly valid input or +does not emit an error message for an invalid input, this may be a bug. +Please send the input file and what you expected. If you know the LRM +well enough, please specify the paragraph which has not been well +implemented. If you don't know the LRM, maybe your bug report will be +rejected simply because there is no bug. In the latter case, it may be +difficult to discuss the issue; and comparisons with other VHDL tools +is not a very strong argument. + +If a compiler message is not clear enough for you, please tell me. The +error messages can be improved, but I have not enough experience with +them. + +If you send a `VHDL` file producing a bug, it is a good idea to try +to make it as short as possible. It is also a good idea to make it +looking like a test: write a comment which explains whether the file +should compile, and if yes, whether or not it should run successfully. +In the latter case, an assert statement should finish the test; the +severity level note indicates success, while a severity level failure +indicates failure. + +For bug reports, please include enough information for the maintainers to +reproduce the problem. This includes: + +* the version of `GHDL` (you can get it with :samp:`ghdl --version`). +* the operating system +* whether you have built `GHDL` from sources or used the binary + distribution. +* the content of the input files +* a description of the problem and samples of any erroneous input +* anything else that you think would be helpful. + +Documentation +============== + +If you have found a mistake in the manual, please send a comment. If +you have not understood some parts of this manual, please tell me. +English is not my mother tongue, so this manual may not be well-written. +Again, rewriting part of it is a good way to improve it. + +--- + +@TODO: + +- Reporting bugs + - [1138: Issues, search first] + - Minimum-(non)-Working-Example (MWE) +- Pull Requests (PRs) + - [1138: check chapter 2 -> building -> GHDL -> directory structure] + - [1138: beware that some commit messages can `automatically close `_ PRs] \ No newline at end of file diff --git a/doc/intro/Copyrights.rst b/doc/intro/Copyrights.rst new file mode 100644 index 000000000..06cc7e4a9 --- /dev/null +++ b/doc/intro/Copyrights.rst @@ -0,0 +1,55 @@ +.. _INTRO:Copyrights: + +Copyrights | License +############ + +The GHDL front-end, the :samp:`std.textio` package and the runtime +library (:samp:`grt`) are copyrighted Tristan Gingold, come with **absolutely +no warranty**, and are distributed under the conditions of the General +Public License. + +The :samp:`ieee.numeric_bit` and :samp:`ieee.numeric_std` packages are +copyrighted by the IEEE. The source files may be distributed without +change, except as permitted by the standard. + +This source file may not be +sold or distributed for profit. See the source file and the IEEE 1076.3 +standard for more information. + +The :samp:`ieee.std_logic_1164`, :samp:`ieee.Math_Real` and +:samp:`ieee.Math_Complex` packages are copyrighted by the IEEE. See +source files for more information. + +The :samp:`ieee.VITAL_Primitives`, :samp:`ieee.VITAL_Timing` and +:samp:`ieee.VITAL_Memory` packages are copyrighted by IEEE. See source +file and the IEEE 1076.4 standards for more information. + +The packages :samp:`std_logic_arith`, +:samp:`std_logic_signed`, :samp:`std_logic_unsigned` and +:samp:`std_logic_textio` contained in the :samp:`synopsys` directory are +copyrighted by Synopsys, Inc. The source files may be used and +distributed without restriction provided that the copyright statements +are not removed from the files and that any derivative work contains the +copyright notice. See the source files for more information. + +The package :samp:`std_logic_arith` contained in the :samp:`mentor` +directory is copyrighted by Mentor Graphics. The source files may be +distributed in whole without restriction provided that the copyright +statement is not removed from the file and that any derivative work +contains this copyright notice. See the source files for more information. + +As a consequence of the runtime copyright, you may not be allowed to +distribute an executable produced by `GHDL` without the VHDL +sources. To my mind, this is not a real restriction, since there is no +points in distributing VHDL executable. Please, send a comment +(:ref:`Reporting_bugs`) if you don't like this policy. + +---------------- + +.. TODO: topic + + https://www.gnu.org/licenses/old-licenses/gpl-2.0.html + + Available in the following formats: plain text, Texinfo, LaTeX, standalone HTML, Docbook, Markdown, ODF, RT + + See `#280 `_ \ No newline at end of file diff --git a/doc/intro/WhatIsGHDL.rst b/doc/intro/WhatIsGHDL.rst new file mode 100644 index 000000000..449ef5d01 --- /dev/null +++ b/doc/intro/WhatIsGHDL.rst @@ -0,0 +1,29 @@ +.. include:: + +.. _INTRO:GHDL: + +What is `GHDL`? +############### + +`GHDL` is a shorthand for G Hardware Design Language. Currently, `G` has no +meaning. + +`GHDL` is a `VHDL` compiler that can execute (nearly) any `VHDL` program. `GHDL` +is *not* a synthesis tool: you cannot create a netlist with `GHDL`. + +Unlike some other simulators, `GHDL` is a compiler: it directly translates a +`VHDL` file to machine code, using the `GCC` or `LLVM` back-end and without +using an intermediary language such as `C` or `C++`. Therefore, the compiled +code should be faster and the analysis time should be shorter than with a +compiler using an intermediary language. + +The Windows\ |trade| version of `GHDL` is not based on `GCC` but on an internal +code generator. + +The current version of `GHDL` does not contain any graphical viewer: you cannot +see signal waves. You can still check with a test bench. The current version can +produce a `VCD` file which can be viewed with a wave viewer, as well as `ghw` +files to be viewed by `gtkwave`. + +`GHDL` aims at implementing `VHDL` as defined by IEEE 1076. It supports most of +the 1987 standard and most features added by the 1993 standard. diff --git a/doc/intro/WhatIsVHDL.rst b/doc/intro/WhatIsVHDL.rst new file mode 100644 index 000000000..b70b3a723 --- /dev/null +++ b/doc/intro/WhatIsVHDL.rst @@ -0,0 +1,35 @@ +.. _INTRO:VHDL: + +What is `VHDL`? +############### + +`VHDL` is an acronym for Very High Speed Integrated Circuit Hardware Description +Language which is a programming language used to describe a logic circuit by +function, data flow behavior, or structure. + +`VHDL` *is* a programming language: although `VHDL` was not designed for writing +general purpose programs, you can write any algorithm with the `VHDL` language. +If you are able to write programs, you will find in `VHDL` features similar to +those found in procedural languages such as `C`, `Python`, or `Ada`. `VHDL` +derives most of its syntax and semantics from `Ada`. Knowing `Ada` is an +advantage for learning `VHDL` (it is an advantage in general as well). + +However, `VHDL` was not designed as a general purpose language but as an `HDL` +(hardware description language). As the name implies, `VHDL` aims at modeling or +documenting electronics systems. Due to the nature of hardware components which +are always running, `VHDL` is a highly concurrent language, built upon an +event-based timing model. + +Like a program written in any other language, a `VHDL` program can be executed. +Since `VHDL` is used to model designs, the term :dfn:`simulation` is often used +instead of `execution`, with the same meaning. + +Like a program written in another hardware description language, a `VHDL` +program can be transformed with a :dfn:`synthesis tool` into a netlist, that is, +a detailed gate-level implementation. + +---------------- + +.. TODO: topic + + @1138 very very briefly explain that there are four major verions: 87, 93, 02 and 08 \ No newline at end of file -- cgit v1.2.3