Tutorial

Every time the Save & Create C/C++ Source option is pressed, the following files will be created (and if they exist, they will be overwritten):

• The Visual Studio project files set to build a DLL containing the device definition:
  • project name.vcxproj
  • project name.vcxproj.filters
• The header file defining the interface to the SIMPLIS simulator:
  • smx_dll.h
• The header file and main source file for the device definition:
  • project name.h
  • project name.c

The first time the Save & Create C/C++ Source option is pressed, the following files will be created:

• The source files for each of the four core functions that the DLL-defined digital device must implement:
  • project name_setup.c
  • project name_set_initial_condition.c
  • project name_action.c
  • project name_teardown.c

As noted earlier, the code generation feature will create seperate source files for each of the four required functions: setup, set_initial_condition, action and teardown. For the example here, you will add code to perform the following tasks:

• setup

  • assign default pointers: Call a pre-defined routine to populate a struct that contains pointers to the input and output buses as well as the values of the parameters passed in by the user.

  • allocate managed user storage: The example will use an 8bit unsigned integer to hold the current value of the counter. By using managed user storage, the code will always have access to the correct, most recent value assigned to it, even if the simulator has to roll back.

• set_initial_condition

  • assign initial condition of the output: In the cases where a device has only one output bus and there is an unsigned integer parameter called IC, a pre-defined routine can be called to copy that user value to the output.

  • assign initial value to the managed user storage: The user's IC parameter should also be assigned to the managed user storage so that when the device first wakes up, it knows its correct starting value.

Now make the remaining modifications to fully enable the device:

• action

  • look for a positive edge on the CLK pin: For this example, the counter is assumed to trigger on a positive edge of the CLK pin.

  • convert the INCREMENT bus: Call the built-in "read_bus" function to convert the inputs of the pins of the INCREMENT bus to an 8bit unsigned integer.

  • determine new counter value: Add the INCREMENT value to the stored output and assign it to the managed storage value.

  • write new value to OUT bus: Call the built-in "write_bus" function with a fixed output delay of 1ns.

• teardown

  • No customization required as you aren't allocating any memory outside of the provided managed and unmanaged storage options.

In order to do debug your DLL-defined Digital Device, the following are recommended:

• the "Debug" version of the DLL should have a debug breakpoint set in the function you wish to debug
• the symbol for the DLL-defined Digital Device should point its DLL_PATH_DEBUG property to the "Debug" version of the DLL
• the STARTUP_DEBUG_DELAY property should be set to a non-zero value

There's any number of ways to set a breakpoint, but for simplicity here, the

DebugBreak()

function is used. In the below example, a breakpoint is added to the action function. There are a few important things to note:

• wrapping the block in the

  #ifdef _DEBUG

  ensures that the code is not present in the "Release" version of the DLL. Using the

  DebugBreak()

  function in a "Release" DLL can have unwanted side effects for the user and should be avoided.
• wrapping the call in the

  if( IsDebuggerPresent() )

  block ensures that the code only breaks when the debugger is attached.

Because the call to

DebugBreak()

is wrapped in the

if( IsDebuggerPresent() )

block, just setting the path to the "Debug" DLL is not sufficient to cause the breakpoint to be tripped, the debugger needs to be attached. While it is possible to attach the debugger mid-simulation, it would make it difficult to debug the setup and set_initial_condition functions. To address this, it is required to specify non-zero value for the STARTUP_DEBUG_DELAY property in order to get. This value is an integer representing the number of seconds that SIMPLIS will pause before launching the first setup function for any DLL-defined Digital Devices present in the circuit. When If multiple devices specify different values, the largest value will be used.