DSim Cloud allows you to access simulation as a service. This tutorial will take about 30 minutes, after which you will be able to use DSim Cloud and run DSim simulations remotely. Ensure you are using a supported terminal shell to run the CLI.
- Downloading example design
- Initializing a DSim Cloud workspace
- Executing commands remotely
- Running simulations remotely with DSim
- Downloading remote compute artifacts
- Pausing and resuming remote compute
- Destroying the workspace
- Getting help
This tutorial will walk you through all the steps needed to use DSim Cloud successfully in about 30 minutes. We provide a simple and well-tested example to make this straightforward. Once done, you will know everything you need to work on your designs.
Downloading example design
For this walkthrough, use the Gowin_I2C_Master_RefDesign example from the GOWIN I2C Reference Design.
Please prepare this example by following these steps:
- Download Gowin_I2C_Master_refDesign from the GOWIN website.
- Create an empty folder in a location you want to work in, and name it Gowin_I2C_Master_RefDesign.
- Extract the zip file into this folder.
Logging into DSim Cloud
Before you can continue with using DSim Cloud, you need to login in first if you haven't already. This is done by opening your terminal and running the following command:
mdc auth login
This will open up your default browser window. Enter the email address and password you signed up with.
For more information on logging in, please read this article.
Initializing a DSim Cloud workspace
A workspace is a directory that is configured to be used with DSim Cloud. The contents of this directory will be synced to the DSim Cloud cloud and be available for remote work. For more information on DSim Cloud workspaces, see Understanding Workspaces.
For this walkthrough, we will use the Gowin_I2C_Master_RefDesign directory you prepared in the previous step. This folder will be used as the origin directory of a DSim Cloud workspace.
Initializing the example folder
In your terminal, navigate to the example directory:
cd <path to Gowin_I2C_Master_RefDesign folder>
Now run the command to initialize this directory as a DSim Cloud workspace - this will take several minutes:
For more information on mdc initialize, see DSim Cloud CLI Tool initialize command.
Checking the status of your new workspace
You should now have an active workspace. You can verify this by running the status command in the terminal from within this directory, which will show the status of the workspace:
For more information on mdc status, see DSim Cloud CLI Tool status command.
Executing commands remotely
DSim Cloud syncs the origin directory to the cloud, transparently keeping an identical remote copy available for command execution and for holding any resulting files. This identical copy is called the remote work directory, and the remote compute always mounts it in the path /remote/work.
The directory in which commands are executed remotely is the synced equivalent of the current working directory from which DSim Cloud is executed. So, if you navigate to <origin_directory/some/path> and execute a command, it will be executed in <remote_work_directory/some/path>.
To try this, execute the list command (list files and folders in working directory) and observe how it reflects the contents of the remote directory:
Now navigate to an internal directory:
and execute list again:
You will see how the contents of the remote directory reflect the contents of the current path in the origin directory.
For more information on mdc list, see DSim Cloud CLI Tool list command.
Running simulations remotely with DSim
DSim is available for you to use in the remote compute. DSim commands are executed in DSim Cloud using the following syntax:
mdc <DSim command> -a '<DSim command options>'
For more information on how to use DSim commands, see DSim simulator commands.
To see that DSim is working, execute a DSim help command in your terminal while in your initialized workspace directory:
mdc dsim -a '-help'
We are now ready to run a test with the example design. In your terminal, navigate to the mdc directory:
Enter the following DSim Cloud command in your terminal, and observe the simulation output being piped back to your terminal:
mdc dsim -a '-top work.i2c_tb -F filelist.txt +acc+b -waves waves.vcd -wave-scope-specs wave.list'
Since the example is purely Verilog, the 3 stages of simulation can be executed in 1 step with the
dsim command taking the following arguments:
-top work.i2c_tb specifies the top-level module as i2c_tb in the default library work
+acc+b generates support for waveform dump at compile-time
-F filelist.txt reads options relative to the manifest file filelist.txt, ie. the files to compile
-waves waves.vcd enables waveform dump to the file waves.vcd at run-time
-wave-scope-specs wave.list specifies the file wave.list as indicating the detailed scopes (signals) to dump
See DSim Common Options for details about other arguments.
For more information on DSim, see DSim User Manual.
Downloading remote compute artifacts
Files created while executing commands on the remote compute are called artifacts. They are kept for you in the remote work directory and can be accessed by further commands. They can also be downloaded if you need a local copy.
To see the contents of your remote directory, execute list:
To download a file, use the download command. To try this, download the created log file:
mdc download dsim.log
Note: the downloaded file is prefixed with _downloaded_, so the downloaded dsim.log becomes _downloaded_dsim.log - this pattern is filtered from being re-synced to the remote compute.
For more information on mdc download, see DSim Cloud CLI Tool download command.
Viewing the waveform file
DSim Cloud CLI comes with GTKWave, an open source wave viewer. This allows you to view a waveform file that is generated after a simulation is complete.
To see the waveform file waves.vcd that was generated by the simulation:
mdc view wave waves.vcd
After a few minutes, this will open the waves.vcd file with GTKWave.
Pausing and resuming remote compute
DSim Cloud is billed based on simulation command time. You can start or resume the service when you want to be able to execute commands, and you can pause when you are done working.
Pausing the Workspace
To pause the remote compute, execute the following in the terminal from any directory within the origin directory of a workspace:
mdc workspace pause
The workspace compute is now paused. You can confirm this is the case by checking status:
Additionally, you can confirm that executing commands does not work:
For more information on mdc workspace pause, see DSim Cloud CLI Tool workspace pause command.
Resuming the Workspace
To regain the ability to execute commands, resume the workspace:
mdc workspace resume
This command will take some time (several minutes), after which the remote compute will again be available for this workspace.
Confirm this using the status command:
And you can confirm that commands can again be executed:
For more information on mdc workspace resume, see DSim Cloud CLI Tool workspace resume command.
Destroying the workspace
At this point you have successfully completed the walkthrough and performed the basic steps for work with the DSim Cloud. You can continue experimenting with the example, pause it if you are done, and resume if you want to continue experimenting.
If you are done and no longer intend to use it, you can perform the last step of this walkthrough and destroy the workspace:
mdc workspace destroy
Destroying the workspace only removes the files on the remote side - no local files will be touched. Consequently, it is possible to reinitialize the workspace again and continue work. If reinitialized, all the files will be uploaded, and you will start again except you will have a clean workspace - i.e. without any artifacts.
For more information on mdc workspace destroy, see DSim Cloud CLI Tool workspace destroy command.
The DSim Cloud CLI offers inline help, which can be accessed by using the --help switch:
Or for a specific command, mdc command --help.
Eg. the workspace command:
mdc workspace --help
To get a better understanding of how to use DSim Cloud for mixed language simulations, download carry_lookahead_adder-main.zip and open readme.txt under the /sim folder of the appropriate language (SystemVerilog/VHDL/VHDL_SystemVerilog).
Now is a good time to try DSim Cloud on one of your own designs. It would be best to create a workspace for that design and experiment with DSim Cloud and DSim until you run a successful compilation and simulation on it.
You can also check out How To: Simulate a Design with GOWIN IP.
Here are some helpful links you may want to explore: