Tutorial: DSim Cloud Walkthrough
Introduction
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 DSim Cloud CLI (mdc).
Covered topics
DSim Cloud Portal
DSim Cloud includes a web application, DSim Cloud Portal. Today, this is where you'll have easy access to interactive workspace management, billing, DSim Cloud CLI (mdc) install commands, information about support, and access to important knowledge base articles.
Future releases will bring usage monitoring features, as well as features for running regressions and viewing results.
Access DSim Cloud Portal using the credentials you already use to authenticate with mdc.
Walkthrough
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, we provide a carry_lookahead_adder example in SystemVerilog.
Please prepare this example by following these steps:
-
Download carry_lookahead_adder-main.zip.
-
Create an empty folder in a location you want to work in, and name it carry_lookahead_adder.
-
Extract the zip file into this folder.
Logging into DSim Cloud
Before you can start this tutorial or any other activity with 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 carry_lookahead_adder 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 carry_lookahead_adder folder>
Now run the command to initialize this directory as a DSim Cloud workspace - this will take several minutes:
mdc initialize
For more information on mdc initialize, see DSim Cloud CLI 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:
mdc status
For more information on mdc status, see DSim Cloud CLI status command.
Tracking your workspaces
You can track your workspaces through the DSim Cloud Portal by clicking the Workspaces icon on the left menu. The Workspaces menu will allow you to view all your non-destroyed workspaces and their current status. Refresh the webpage to update.
For more information on tracking workspaces, see the Tracking Workspaces section of Understanding Workspaces.
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:
mdc list
Now navigate to an internal directory:
cd SystemVerilog
and execute list again:
mdc list
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 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 SystemVerilog simulation directory inside the example origin directory.
cd sim
Enter the following DSim Cloud command in your terminal, and observe the simulation output being piped back to your terminal:
mdc dsim -a '-F filelist.txt +acc+b -waves waves.mxd'
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:
-F filelist.txt reads options relative to the manifest file filelist.txt, ie. the files to compile
+acc+b generates support for waveform dump at compile-time
-waves waves.mxd enables waveform dump to the file waves.mxd at run-time
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:
mdc 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 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.mxd that was generated by the simulation:
mdc view wave waves.mxd
This will open the waves.mxd file with the Metrics Waveform Viewer. After adding signals and viewing the waveforms, close it. You may have to press <Enter> in your terminal to return to your mdc prompt.
Pausing and resuming remote compute
In the current Interactive Simulation mode, DSim Cloud is billed based on active workspace time. In the future Regression Simulation mode, it is billed 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:
mdc status
Additionally, you can confirm that executing commands does not work:
mdc list
For more information on mdc workspace pause, see DSim Cloud CLI 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:
mdc status
And you can confirm that commands can again be executed:
mdc list
For more information on mdc workspace resume, see DSim Cloud CLI 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 workspace destroy command.
Alternatively, you can destroy your workspace through the Workspaces menu of the DSim Cloud Portal by clicking the Destroy button next to the workspace.
For more information on destroying workspaces through the web portal, see the Destroying Workspaces section of Understanding Workspaces.
Getting help
The DSim Cloud CLI offers an inline help, which can be accessed by using the --help switch:
mdc --help
Or for a specific command, mdc <command>--help .
Eg. the workspace command:
mdc workspace --help
A full set of articles and tutorials is available on our support website, where you can also reach us for reporting issues or providing feedback by emailing us at support@metrics.ca.
Alternatively, click on the Support menu (question mark icon) of the DSim Cloud Portal to get help.
Next Steps
To get a better understanding of how to use DSim Cloud for mixed language simulations, 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 designs with FPGA vendor IP.
Links
Here are some helpful links you may want to explore: