Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Describe the usage of XSim. #230

Merged
merged 3 commits into from
Nov 14, 2023
Merged

Describe the usage of XSim. #230

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7a5fada
add explaination on all-in-one offline installer.
Readon Nov 9, 2023
372f404
add description on XSim.
Readon Nov 10, 2023
87499ee
fix license description of XSim.
Readon Nov 14, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions source/SpinalHDL/Getting Started/Install and setup.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
.. _Install:

Install and setup
=================

Check warning on line 4 in source/SpinalHDL/Getting Started/Install and setup.rst

View workflow job for this annotation

GitHub Actions / test 

Duplicate explicit target name: "it".

Check warning on line 4 in source/SpinalHDL/Getting Started/Install and setup.rst

View workflow job for this annotation

GitHub Actions / build 

Duplicate explicit target name: "it".

Spinal is a Scala library (a programming language using the Java VM) so it
requires setting up a Scala environment; there are many ways to do so.
Expand Down Expand Up @@ -145,6 +145,15 @@
This is sufficient for generating hardware. For simulation continue with either choice below.
In case you want to build the tools yourself have a look at the legacy simulation tool :ref:`installation instructions <sim backend install>`.

.. note::
An All-in-One solution is available to install and run SpinalHDL with Verilator simulation and formal verification via SymbiYosys.
Download `it <https://github.com/Readon/msys2-installer/releases>`_ and install the environment anywhere on your disk.
Start the build environment by clicking on the MSYS2-MINGW64 icon in the Start menu and use the MSYS2 default console.
An alternative is to use the Windows Terminal or a Tabby-like application and use the startup command ``%MSYS2_ROOT%\msys2_shell.cmd -defterm -here -no-start -mingw64``, where the ``%MSYS2_ROOT%`` is the location of the msys2 installation.
It is worth noting that if you want to use it offline, you should carefully select the libraries that the project depends on, otherwise you will need to download the packages manually.
See the README for the repos for more details.


MSYS2 verilator for simulation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Expand Down
20 changes: 20 additions & 0 deletions source/SpinalHDL/Simulation/simulator_specifics.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,26 @@ How SpinalHDL simulates the hardware with Synopsys VCS backend

Before using VCS as the simulation backend, make sure that you have checked your system environment as :ref:`VCS environment<vcs_env>`.

How SpinalHDL simulates the hardware with Xilinx XSim backend
==============================================================

1. SpinalHDL generates a Verilog/VHDL (depended on your choice) hardware model of the DUT.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SpinalHDL generates industry standard HDL sources for XSim such as Verilog or VHDL (dependent on your elaboration choice) for the hardware model of the DUT.

2. The HDL model is loaded in the simulator.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

via hand wavey magic ? LOL

Can more be said about this part, I think out of all of the steps this is the one the reader is looking for as much support as possible to resolve.

What does this step mean ? it is loaded via GUI (Vivado) or command-line (how to get correct environment setup, if you installed Vivado as per Xilinx instructions) ? How do you use your msys2 support package(s) ? These are 3 ways I can think a reader might want to understand.

For example what does a SpinalSim config look like for XSim ? what important extra flags might be useful to know, do you have to do anything special to ensure the Xilinx primitive catalog models are available to the simulation ? is the LD_LIBRARY_PATH setup a concern at runtime ?

3. The communication between the simulation and the JVM is established through shared memory. The commands are issued to the simulator using XSI.

**Advantages:**

* Support Xilinx built-in primitives and cores.

**Limitations:**

* Xilinx XSim is a **commercial** tool installed with Vivado. It is closed source and subject to licensing terms to use. You have to own the licenses to **legally** use it.
* Vivado versions prior to 2019.1 do not work properly.

Before using XSim as the simulation backend, make sure that you have done following steps.
1. Define VIVADO_HOME environment variable to specify where your vivado located. ex `export VIVADO_HOME=/d/Xilinx/Vivado/2022.1` (under MSYS2).
2. Make sure two vivado path is inside the PATH. For Windows MSYS2 user, run shell command like `export PATH=$PATH:$VIVADO_HOME/bin:$VIVADO_HOME/lib/win64.o`. For Linux user just source the Vivado's settings64.sh file located at `VIVADO_HOME`.

Copy link
Contributor

@dlmiles dlmiles Nov 10, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is more like the meat into what the reader is looking for :) More of this :)

Is it possible to provide a code snippet of a minimal SpinalSim testbench which can be used as an installation and setup check ? It helps the reader to know if they run this program and they have everything setup, it should work. Then in the future with feedback we can address any common error messages seen in the setup and how to fix. Getting the environment working is probably why the reader is looking at the documentation here.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this page is a good place to write this details. May be this location is better.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is the specific detail needed to make XSim work that would be captured here.
I don't think that is best put in the generic simulation information, but maybe a separate page per simulator is a better format.
Readers using XSim want to copy-and-paste something and know it should work as-is. A kind of installation and setup check, something they can then communicate about if there is an error/issue they can not resolve.

Copy link
Collaborator Author

@Readon Readon Nov 13, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So that would be more work on this. I just keep the consistency with other parts.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is the specific detail needed to make XSim work that would be captured here. I don't think that is best put in the generic simulation information, but maybe a separate page per simulator is a better format. Readers using XSim want to copy-and-paste something and know it should work as-is. A kind of installation and setup check, something they can then communicate about if there is an error/issue they can not resolve.

You're right, a simulation tutorial for each simulation engine would be a good choice.

Performance
===========

Expand Down