From 2bea592952b8a9f9860bb646ddf72d26eac4ad29 Mon Sep 17 00:00:00 2001 From: umarcor <38422348+umarcor@users.noreply.github.com> Date: Fri, 10 Apr 2020 07:48:47 +0200 Subject: update doc (synth, overview, generics, etc.) (#1205) * doc: extend info about setting generics through the CLI * doc: rename 'Command Reference' to 'Additional Command Reference' * doc: use '``' instead of ':samp:' * doc: update info about synthesis * doc: add references to sources in internals/Overview * doc: add diagram to internals/Overview --- doc/internals/Frontend.rst | 8 +++++++- doc/internals/Overview.rst | 19 +++++++++++++------ doc/internals/img/internals.png | Bin 0 -> 80333 bytes 3 files changed, 20 insertions(+), 7 deletions(-) create mode 100644 doc/internals/img/internals.png (limited to 'doc/internals') diff --git a/doc/internals/Frontend.rst b/doc/internals/Frontend.rst index 6d5e1da5c..fd5abd4e6 100644 --- a/doc/internals/Frontend.rst +++ b/doc/internals/Frontend.rst @@ -3,7 +3,13 @@ Front-end ######### -Input files (or source files) are read by `files_map.ad[sb]`. Only regular files can be read, because they are read entirely before being scanned. This simplifies the scanner, but this also allows to have a unique index for each character in any file. Therefore the source location is a simple 32-bit integer whose type is `Location_Type`. From the location, `files_map` can deduce the source file (type is `Source_File_Entry`) and then the offset in the source file. There is a line table for each source file in order to speed-up the conversion from file offset to line number and column number. +Input files (or source files) are read by `files_map.ad[sb]`. Only regular files can be +read, because they are read entirely before being scanned. This simplifies the scanner, +but this also allows to have a unique index for each character in any file. +Therefore the source location is a simple 32-bit integer whose type is `Location_Type`. +From the location, `files_map` can deduce the source file (type is `Source_File_Entry`) +and then the offset in the source file. There is a line table for each source file in +order to speed-up the conversion from file offset to line number and column number. The scanner (file :file:`vhdl-scanner.ad[sb]`) reads the source files and creates token from them. The tokens are defined in file :file:`vhdl-tokens.ads`. Tokens are scanned diff --git a/doc/internals/Overview.rst b/doc/internals/Overview.rst index 3be8772b4..fd29f5832 100644 --- a/doc/internals/Overview.rst +++ b/doc/internals/Overview.rst @@ -3,16 +3,23 @@ Overview ######## -`GHDL` is architectured like a traditionnal compiler. It has: +.. image:: img/internals.png + :width: 350px + :align: center -* a driver (sources in :file:`src/ghdldrv`) to call the programs (compiler, assembler, linker) if needed. +`GHDL` is architectured like a traditionnal compiler. It has: -* a library (sources in :file:`src/grt`) to help execution at run-time. +* a driver (sources in :ghdlsrc:`src/ghdldrv `) to call the programs (compiler, assembler, linker) if needed. -* a front-end (sources in :file:`src/vhdl`) to parse and analyse VHDL. +* a runtime library named GRT (sources in :ghdlsrc:`src/grt `) to help execution at run-time. This ensures that execution is cycle-accurate. -* a back-end (in fact many, sources are in :file:`src/ortho`) to generate code. +* a front-end (sources in :ghdlsrc:`src/vhdl `) to parse and analyse VHDL. See :ref:`INT:Frontend` and :ref:`INT:AST`. -The architecture is modular. For example, it is possible to use the front-end in the `libghdl` library for the language server or to do synthesis (sources in :file:`src/synth`) instead of code generation. +* multiple back-ends to generate either code or netlists. + + * Three for :ref:`simulation ` (sources are in :ghdlsrc:`src/ortho `): mcode, LLVM and GCC. See :ref:`BUILD`. + * Two for :ref:`synthesis ` (sources in :ghdlsrc:`src/synth `): :ref:`--synth ` and :ref:`Synth:plugin`. + +The architecture is modular. For example, the front-end in the ``libghdl`` library is used for the language server. The main work is performed by the front-end, which is documented in the next chapter. diff --git a/doc/internals/img/internals.png b/doc/internals/img/internals.png new file mode 100644 index 000000000..cc6714287 Binary files /dev/null and b/doc/internals/img/internals.png differ -- cgit v1.2.3