diff options
Diffstat (limited to 'doc/getting.rst')
| -rw-r--r-- | doc/getting.rst | 490 |
1 files changed, 490 insertions, 0 deletions
diff --git a/doc/getting.rst b/doc/getting.rst new file mode 100644 index 000000000..4abab4530 --- /dev/null +++ b/doc/getting.rst @@ -0,0 +1,490 @@ +.. _PACKAGES: + +Getting | Installing +#################### + +Package managers +**************** + +Package managers of many popular distributions provide pre-built packages of GHDL. This is the case for `apt` +(Debian/Ubuntu), `dnf` (Fedora), `pacman` (Arch Linux, MSYS2) or `brew` (macOS). Since GHDL supports three different backends +and two library sets (*regular* or *GPL-compatible*), at least six packages with different features might be available in +each package manager. + +As a rule of thumb, mcode backend is the fastest for analysis and synthesis. It also allows setting the base simulation time +for speeding up execution. Therefore, it is the recommended pick if available on your platform (x86/amd64, on Windows x86 +only). On other platforms, or for using specific features for co-simulation or code coverage, LLVM or GCC need to be used. +See further differences between backends in :ref:`BUILD`. + +.. _RELEASE:packages: + +Nightly packages +**************** + +Assets from nightly GHDL builds are available at `github.com/ghdl/ghdl/releases/nightly <https://github.com/ghdl/ghdl/releases/nightly>`__. +These are mostly meant to be used in Continuous Integration (CI) workflows. Precisely, `setup-ghdl-ci <https://github.com/ghdl/setup-ghdl-ci>`__ +allows to easily setup nightly assets in GitHub Actions workflows. + +However, users on Windows (MSYS2) or Ubuntu might want to download the tarballs/zipfiles and extract/install them locally. + +.. _GETTING:PrecompVendor: + +Precompile Vendor Primitives +**************************** + +Vendors like Lattice, Intel (Altera) and Xilinx have their own simulation libraries, +especially for FPGA primitives, soft and hard macros. These libraries cannot +be shipped with GHDL, but GHDL offers prepared compile scripts to pre-compile +these vendor libraries, if the vendor tool is present in the environment. There +are also popular simulation and verification libraries like OSVVM [#f1]_ or +UVVM [#f2]_, which can be pre-compiled, too. + +The compilation scripts are writen in the shell languages: *PowerShell* for +*Windows™* and *Bash* for *GNU/Linux*, *MacOS* and *MSYS2*/*MinGW*. The +compile scripts can colorize the GHDL warning and error lines with the help +of ``grc/grcat`` [#f4]_. + +.. HINT:: + Vendor precompile scripts for OSVVM and UVVM are tested periodically in `ghdl/extended-tests <https://github.com/ghdl/extended-tests>`__. + +Supported Vendors Libraries +=========================== + +* Lattice (3.6 or later): + + * ``ec`` + * ``ecp``, ``ecp2``, ``ecp3``, ``ecp5u`` + * ``lptm``, ``lptm2`` + * ``machxo``, ``machxo2``, ``machxo3l``, ``machxo3d`` + * ``sc``, ``scm`` + * ``xp``, ``xp2`` + * ... + +* Intel (Altera) Quartus (13.0 or later): + + * ``lpm``, ``sgate`` + * ``altera``, ``altera_mf``, ``altera_lnsim`` + * ``arriaii``, ``arriaii_pcie_hip``, ``arriaiigz`` + * ``arriav``, ``arriavgz``, ``arriavgz_pcie_hip`` + * ``cycloneiv``, ``cycloneiv_pcie_hip``, ``cycloneive`` + * ``cyclonev`` + * ``max``, ``maxii``, ``maxv`` + * ``stratixiv``, ``stratixiv_pcie_hip`` + * ``stratixv``, ``stratixv_pcie_hip`` + * ``fiftyfivenm``, ``twentynm`` + * ... + +* Xilinx ISE (14.0 or later): + + * ``unisim`` (incl. ``secureip``) + * ``unimacro`` + * ``simprim`` (incl. ``secureip``) + * ``xilinxcorelib`` + +* Xilinx Vivado (2014.1 or later): + + * ``unisim`` (incl. ``secureip``) + * ``unimacro`` + +Supported Simulation and Verification Libraries +=============================================== + +* OSVVM [#f1]_ (for VHDL-2008) +* UVVM [#f2]_ (for VHDL-2008) + + +--------------------------------------------------------------------- + +Script Configuration +==================== + +The vendor library compile scripts need to know where the used / latest vendor +tool chain is installed. Therefore, the scripts implement a default installation +directory search as well as environment variable checks. If a vendor tool cannot +be detected or the script chooses the wrong vendor library source directory, +then it's possible to provide the path via ``--source`` (Bash) or ``-Source`` +(PoSh). + +The generated output is stored relative to the current working directory. The +scripts create a sub-directory for each vendor. The default output directory can +be overwritten by the parameter ``--output`` (Bash) or ``-Output`` (PoSh). + +To compile all source files with GHDL, the simulator executable is searched in +``PATH``. The found default GHDL executable can be overwritten by setting the +environment variable ``GHDL`` or by passing the parameter ``--ghdl`` (Bash) or +``-GHDL`` (PoSh) to the scripts. + +If the vendor library compilation is used very often, it's recommend to configure +these parameters in ``config.sh`` (Bash) or ``config.psm1`` (PoSh), so the command +line can be shortened to the essential parts. + +--------------------------------------------------------------------- + +Compiling in Bash +================= + +The provided Bash scripts support these environments: + +* Linux +* MacOS +* MSYS2 / MinGW +* WSL (Windows Subsystem for Linux) + + +Follow these steps: + +* **Step 0 - Configure the scripts (optional)** + + See the next section for how to configure ``config.sh``. + +* **Step 1 - Browse to your simulation working directory** + + .. code-block:: Bash + + $ cd <MySimulationFolder> + + +* **Step 2 - Start the compilation script(s)** + + Choose one or multiple of the following scripts to run the pre-compilation + process. + + .. code-block:: Bash + + $ /usr/local/lib/ghdl/vendors/compile-altera.sh --all + $ /usr/local/lib/ghdl/vendors/compile-intel.sh --all + $ /usr/local/lib/ghdl/vendors/compile-lattice.sh --all + $ /usr/local/lib/ghdl/vendors/compile-osvvm.sh --all + $ /usr/local/lib/ghdl/vendors/compile-uvvm.sh --all + $ /usr/local/lib/ghdl/vendors/compile-xilinx-ise.sh --all + $ /usr/local/lib/ghdl/vendors/compile-xilinx-vivado.sh --all + + + In most cases GHDL is installed into ``/usr/local/``. The scripts are + installed into the ``lib\ghdl\vendors`` directory. + +* **Step 3 - Viewing the result** + + This creates vendor directories in your current working directory and + compiles the vendor files into them. + + + .. code-block:: Bash + + $ ls -ahl + ... + drwxr-xr-x 2 <user> <group> 56K Mar 09 17:41 altera + drwxr-xr-x 2 <user> <group> 56K Mar 09 17:42 intel + drwxr-xr-x 2 <user> <group> 56K Mar 09 17:42 lattice + drwxr-xr-x 2 <user> <group> 56K Mar 09 17:48 osvvm + drwxr-xr-x 2 <user> <group> 56K Mar 09 17:58 uvvm + drwxr-xr-x 2 <user> <group> 56K Mar 09 17:58 xilinx-ise + drwxr-xr-x 2 <user> <group> 56K Mar 09 17:48 xilinx-vivado + + + +--------------------------------------------------------------------- + +Compiling in PowerShell +======================= + +The provided PowerShell scripts support these environments: + +* Windows™ 10 (PowerShell 5 and PowerShell 6) + + +Follow these steps: + +* **Step 0 - Configure the scripts (optional)** + + See the next section for how to configure ``config.psm1``. + +* **Step 1 - Browse to your simulation working directory** + + .. code-block:: PowerShell + + PS> cd <MySimulationFolder> + +* **Step 2 - Start the compilation script(s)** + + Choose one or multiple of the following scripts to run the pre-compilation + process. + + .. code-block:: PowerShell + + PS> <GHDL>\lib\ghdl\vendors\compile-altera.ps1 -All + PS> <GHDL>\lib\ghdl\vendors\compile-intel.ps1 -All + PS> <GHDL>\lib\ghdl\vendors\compile-lattice.ps1 -All + PS> <GHDL>\lib\ghdl\vendors\compile-osvvm.ps1 -All + PS> <GHDL>\lib\ghdl\vendors\compile-uvvm.ps1 -All + PS> <GHDL>\lib\ghdl\vendors\compile-xilinx-ise.ps1 -All + PS> <GHDL>\lib\ghdl\vendors\compile-xilinx-vivado.ps1 -All + + .. # In most cases GHDL is installed into ``/usr/local/``. + + The scripts are installed into the ``lib\ghdl\vendors`` directory. + +* **Step 3 - Viewing the result** + + This creates vendor directories in your current working directory and + compiles the vendor files into them. + + .. code-block:: + + PS> dir + Directory: D:\temp\ghdl + + Mode LastWriteTime Length Name + ---- ------------- ------ ---- + d---- 09.03.2018 19:33 <DIR> altera + d---- 09.03.2018 19:38 <DIR> intel + d---- 09.03.2018 19:38 <DIR> lattice + d---- 09.03.2018 19:38 <DIR> osvvm + d---- 09.03.2018 19:45 <DIR> uvvm + d---- 09.03.2018 19:06 <DIR> xilinx-ise + d---- 09.03.2018 19:40 <DIR> xilinx-vivado + + +--------------------------------------------------------------------- + +Configuration Files +=================== + +For Bash: `config.sh` +--------------------- + +Please open the ``config.sh`` file and set the dictionary entries for the +installed vendor tools to your tool's installation directories. Use an empty +string ``""`` for not installed tools. + +``config.sh``: + +.. code-block:: Bash + + declare -A InstallationDirectory + InstallationDirectory[AlteraQuartus]="/opt/Altera/16.0" + InstallationDirectory[IntelQuartus]="/opt/intelFPGA/20.1" + InstallationDirectory[LatticeDiamond]="/opt/Diamond/3.10_x64" + InstallationDirectory[OSVVM]="/home/<user>/git/GitHub/OSVVM" + InstallationDirectory[UVVM]="/home/<user>/git/GitHub/UVVM" + InstallationDirectory[XilinxISE]="/opt/Xilinx/14.7" + InstallationDirectory[XilinxVivado]="/opt/Xilinx/Vivado/2020.2" + + +For PowerShell: `config.psm1` +----------------------------- + +Please open the ``config.psm1`` file and set the dictionary entries for the +installed vendor tools to your tool's installation +folder. Use an empty string ``""`` for not installed tools. + +``config.psm1``: + +.. code-block:: PowerShell + + $InstallationDirectory = @{ + "AlteraQuartus" = "C:\Altera\16.0"; + "IntelQuartus" = "C:\Altera\20.1"; + "LatticeDiamond" = "C:\Lattice\Diamond\3.10_x64"; + "XilinxISE" = "C:\Xilinx\14.7\ISE_DS"; + "XilinxVivado" = "C:\Xilinx\Vivado\2020.2"; + "OSVVM" = "C:\git\GitHub\OSVVM"; + "UVVM" = "C:\git\GitHub\UVVM" + } + + +Additional Script Parameters +============================ + +Each script supports partial compilations e.g. of shared packages and +individual parts. In addition, the amount of printout to the console can be +controlled. Some scripts may offer vendor specific options. + + +For Bash Scripts: +----------------- + +* Common parameters to most scripts: + + .. code-block:: none + + --help, -h Print the embedded help page(s). + --clean, -c Cleanup directory before analyzing. + --no-warnings, -n Don't show warnings. Report errors only. + --skip-existing, -s Skip already compiled files (an *.o file exists). + --skip-largefiles, -S Don't compile large entities like DSP and PCIe primitives. + --halt-on-error, -H Stop compiling if an error occurred. + +* ``compile-altera.sh`` + + Selectable libraries: + + .. code-block:: none + + --all, -a Compile all libraries, including common libraries, packages and device libraries. + --altera Compile base libraries like 'altera' and 'altera_mf' + --max Compile device libraries for Max CPLDs + --arria Compile device libraries for Arria FPGAs + --cyclone Compile device libraries for Cyclone FPGAs + --stratix Compile device libraries for Stratix FPGAs + + Compile options: + + .. code-block:: none + + --vhdl93 Compile selected libraries with VHDL-93 (default). + --vhdl2008 Compile selected libraries with VHDL-2008. + +* ``compile-xilinx-ise.sh`` + + Selectable libraries: + + .. code-block:: none + + --all, -a Compile all libraries, including common libraries, packages and device libraries. + --unisim Compile the unisim primitives + --unimacro Compile the unimacro macros + --simprim Compile the simprim primitives + --corelib Compile the xilinxcorelib macros + --secureip Compile the secureip primitives + + Compile options: + + .. code-block:: none + + --vhdl93 Compile selected libraries with VHDL-93 (default). + --vhdl2008 Compile selected libraries with VHDL-2008. + +* ``compile-xilinx-vivado.sh`` + + Selectable libraries: + + .. code-block:: none + + --all, -a Compile all libraries, including common libraries, packages and device libraries. + --unisim Compile the unisim primitives + --unimacro Compile the unimacro macros + --secureip Compile the secureip primitives + + Compile options: + + .. code-block:: none + + --vhdl93 Compile selected libraries with VHDL-93 (default). + --vhdl2008 Compile selected libraries with VHDL-2008. + +* ``compile-osvvm.sh`` + + Selectable libraries: + + .. code-block:: none + + --all, -a Compile all. + --osvvm Compile the OSVVM library. + +* ``compile-uvvm.sh`` + + Selectable libraries: + + .. code-block:: none + + --all, -a Compile all. + --uvvm Compile the UVVM libraries. + + +For PowerShell Scripts: +----------------------- + +* Common parameters to all scripts: + + .. code-block:: none + + -Help Print the embedded help page(s). + -Clean Cleanup directory before analyzing. + -SuppressWarnings Don't show warnings. Report errors only. + +* ``compile-altera.ps1`` + + Selectable libraries: + + .. code-block:: none + + -All Compile all libraries, including common libraries, packages and device libraries. + -Altera Compile base libraries like 'altera' and 'altera_mf' + -Max Compile device libraries for Max CPLDs + -Arria Compile device libraries for Arria FPGAs + -Cyclone Compile device libraries for Cyclone FPGAs + -Stratix Compile device libraries for Stratix FPGAs + + Compile options: + + .. code-block:: none + + -VHDL93 Compile selected libraries with VHDL-93 (default). + -VHDL2008 Compile selected libraries with VHDL-2008. + +* ``compile-xilinx-ise.ps1`` + + Selectable libraries: + + .. code-block:: none + + -All Compile all libraries, including common libraries, packages and device libraries. + -Unisim Compile the unisim primitives + -Unimacro Compile the unimacro macros + -Simprim Compile the simprim primitives + -CoreLib Compile the xilinxcorelib macros + -Secureip Compile the secureip primitives + + Compile options: + + .. code-block:: none + + -VHDL93 Compile selected libraries with VHDL-93 (default). + -VHDL2008 Compile selected libraries with VHDL-2008. + +* ``compile-xilinx-vivado.ps1`` + + Selectable libraries: + + .. code-block:: none + + -All Compile all libraries, including common libraries, packages and device libraries. + -Unisim Compile the unisim primitives + -Unimacro Compile the unimacro macros + -Secureip Compile the secureip primitives + + Compile options: + + .. code-block:: none + + -VHDL93 Compile selected libraries with VHDL-93 (default). + -VHDL2008 Compile selected libraries with VHDL-2008. + +* ``compile-osvvm.ps1`` + + Selectable libraries: + + .. code-block:: none + + -All Compile all. + -OSVVM Compile the OSVVM library. + +* ``compile-uvvm.ps1`` + + Selectable libraries: + + .. code-block:: none + + -All Compile all. + -UVVM Compile the UVVM libraries. + +-------------------------------------------------------------------------------- + +.. container:: footnotes + + .. rubric:: Footnotes + + .. [#f1] OSVVM http://github.com/OSVVM/OSVVM + .. [#f2] UVVM https://github.com/UVVM/UVVM_All + .. [#f4] Generic Colourizer http://kassiopeia.juls.savba.sk/~garabik/software/grc.html |