Tutorial: DSim Cloud Walkthrough for GOWIN Customers

Contents

1. Introduction
2. Downloading example design
3. Logging into DSim Cloud
4. Starting a DSim Cloud Interactive workspace
5. Executing commands remotely
6. Running simulations remotely with DSim
7. Downloading remote workspace artifacts
8. Viewing the waveform file
9. Pausing and resuming remote workspace
10. Destroying the remote workspace
11. Getting help
12. Next Steps

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).

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, use the Gowin_I2C_Master_RefDesign example design. If you haven't already done so,

1. Download Gowin_I2C_Master_refDesign from the GOWIN website.

2. Extract the zip file into a folder with read/write access named Gowin_I2C_Master_RefDesign.

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.

Starting a DSim Cloud Interactive workspace

A local workspace is a directory that is configured to be used with DSim Cloud. The contents of this directory will be synced to the remote directory and be available for remote work. For more information on DSim Cloud Interactive 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 local workspace directory of a DSim Cloud Interactive workspace.

Initializing the example folder

In your terminal, navigate to the example directory:

 

cd <path to gowin_i2c_master_refdesign  folder>

 

Now run these commands to start a DSim Cloud Interactive workspace in this directory - this will take several minutes:

 

mdc initialize --local-only
mdc workspace start

 

For more information see DSim Cloud CLI initialize command and DSim Cloud CLI workspace start command.

Checking the status of your new remote workspace

You should now have an active remote workspace. You can verify this by running the status command in the terminal from within this directory, which will show the status of the remote workspace:

 

mdc status

 

For more information on mdc status, see DSim Cloud CLI status command.

Tracking your DSim Cloud Interactive workspaces

You can track your DSim Cloud Interactive workspaces through the DSim Cloud Portal by clicking the Cloud Interactive icon on the left menu. The Cloud Interactive menu will allow you to view all your non-destroyed remote workspaces and their current status. Refresh the webpage to update.

For more information on tracking DSim CLoud Interactive workspaces, see DSim Cloud Interactive Workspaces - Viewing Workspaces.

Executing commands remotely

DSim Cloud syncs the local workspace 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 workspace always mounts it at 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 <local_workspace_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 simulation

 

and execute list again:

 

mdc list

 

You will see how the contents of the remote directory reflect the contents of the current working directory in the local workspace.

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 workspace. 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 local workspace directory:

 

mdc dsim -a '-help'

 

We are now ready to run a test with the example design. In your terminal, navigate to the metrics directory:

 

cd metrics

 

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.mxd -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.mxd enables waveform dump to the file waves.mxd 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 workspace artifacts

Files created while executing commands in the remote workspace 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 workspace.

For more information on mdc download, see DSim Cloud CLI download command.

Viewing the waveform file

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 workspace

In the current Interactive Simulation mode, DSim Cloud is billed based on the time your remote workspace is Active. 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 Remote Workspace

To pause the remote workspace, execute the following in the terminal from any directory within the local workspace directory:

 

mdc workspace pause

 

The remote workspace 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 Remote Workspace

To regain the ability to execute commands, resume the remote workspace:

 

mdc workspace start

 

This command will take some time (several minutes), while compute resources are allocated to this remote 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 start, see DSim Cloud CLI workspace start command.

Destroying the remote 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 remote workspace:

 

mdc workspace destroy

 

Destroying the remote workspace only removes the files on the remote side - no local files will be touched. Consequently, a new remote workspace can be started in the same local workspace directory to continue work. Any new remote workspace now will again be a clone of your local workspace again - i.e. without any artifacts from previous remote workspaces.

For more information on mdc workspace destroy, see DSim Cloud CLI workspace destroy command.

Alternatively, you can destroy your remote workspace through the Cloud Interactive menu of the DSim Cloud Portal by clicking the Destroy button next to it.

For more information on destroying DSim Cloud Interactive workspaces through the web portal, see DSim Cloud Interactive Workspaces - Destroying 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.

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, 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 DSim Cloud Interactive 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.

Links

Here are some helpful links you may want to explore:

• User Guide: DSim Cloud CLI

  
  

• DSim Cloud File Synchronization

  
  

• DSim Cloud Troubleshooting Guide

  
  

• DSim User Manual

  
  

• Tutorial: Regressions