Functions

For every call to one of a device's functions:

• setup
• set_initial_condition
• action
• teardown

...two arguments will be passed in for use in the customized routines. The first argment is the device definition, which provides pointers to the input and output buses, managed/unmanaged user storage and the end user configurable parameters. The second is the simulation context, detailing the current simulation time, the reason the device is active, and whether or not edge events and scheduling wake requests is currently enabled. It also provides access to the functions that can be called during the simulation run.

All of the functions available to the DLL-defined Digital Device are accessed through the funcs member of the simulation context struct passed as an argument to each of the device's function calls. For a simple call to the fatal_error function, the following example implementation shows how to access the function using the default argument names from the header file.

context_p->funcs->fatal_error(device_p, "Fatal error has occurred.");

The functions available to be called during simulation fit into the following categories:

• Data Member Access
• Manipulation of Buses/Pins
• Housekeeping/Misc

The following functions are intended to allow the device to access buses, pins, and parameters or the device as instantiated on the schematic.

• get_bus_by_name( const p_smx_dll_device device, const char* bus_name, SMX_DLL_DIRECTION direction, p_smx_dll_bus* result )

  provided the device pointer as passed into the calling function, the name of the bus to be retrieved and the bus direction (either SMX_DLL_DIRECTION_INPUT or SMX_DLL_DIRECTION_OUTPUT), the pointer to a bus pointer result will be populated with the address of the requested bus. If the bus is found, the function will return SMX_DLL_NO_ERROR, otherwise, the result should not be treated as valid.

• get_bus_width( const p_smx_dll_bus bus_p, SMX_DLL_UINT32 *p_width )

  provided a pointer to the bus in question, the value at the address of the integer pointer result will be set to the bus width. On success, the function will return SMX_DLL_NO_ERROR, otherwise, the result should not be treated as valid.

• get_pin_by_name( const p_smx_dll_device device, const char* pin_name, SMX_DLL_DIRECTION direction, p_smx_dll_pin* result )

  provided the device pointer as passed into the calling function, the name of the pin to be retrieved and the pin direction (either SMX_DLL_DIRECTION_INPUT or SMX_DLL_DIRECTION_OUTPUT), the pointer to a pin pointer result will be populated with the address of the requested pin. If the pin is found, the function will return SMX_DLL_NO_ERROR, otherwise, the result should not be treated as valid.

• get_pin_by_bus_and_index( const p_smx_dll_device device, const char* bus_name, SMX_DLL_UINT32 pin_index, SMX_DLL_DIRECTION direction, p_smx_dll_pin* result )

  provided the device pointer as passed into the calling function, the name of the bus containing the pin to be retrieved, the index of the pin in the bus, the bus direction (either SMX_DLL_DIRECTION_INPUT or SMX_DLL_DIRECTION_OUTPUT), the pointer to a pin pointer result will be populated with the address of the requested pin. If the pin is found, the function will return SMX_DLL_NO_ERROR, otherwise, the result should not be treated as valid.

• get_pin_by_index_from_bus( const p_smx_dll_bus bus_p, SMX_DLL_UINT32 pin_index, p_smx_dll_pin *result )

  provided a pointer to the bus in question and the index of the pin in the bus, the pointer to a pin pointer result will be populated with the address of the requested pin. If the pin is found, the function will return SMX_DLL_NO_ERROR, otherwise, the result should not be treated as valid.

• get_parameter_by_name( const p_smx_dll_device device, const char* parameter_name, p_smx_dll_parameter* result )

  provided the device pointer as passed into the calling function and the name of the parameter to be retrieved, the pointer to a parameter pointer result will be populated with the address of the requested parameter. If the parameter is found, the function will return SMX_DLL_NO_ERROR, otherwise, the result should not be treated as valid.

The following functions are intended to allow the device to read and write from/to buses and pins.

• get_pin_logic( p_smx_dll_pin pin_p, SMX_DLL_UBYTE8* result )
  provided a pointer to the pin in question, the pointer to an unsigned byte result will be populated with the logic value of the pin. On success, the function will return SMX_DLL_NO_ERROR and the assigned value will be one of:

  • SMX_DLL_LOGIC_0
  • SMX_DLL_LOGIC_1
  • SMX_DLL_LOGIC_X

  If the function does not return SMX_DLL_NO_ERROR, the result should not be treated as valid.
• set_pin_logic( p_smx_dll_pin pin_p, SMX_DLL_UBYTE8 logic, SMX_DLL_DOUBLE delay )
  sets the logic value of the output pin identified by the pointer to the specified value after the provided delay. Logic value should be one of:

  • SMX_DLL_LOGIC_0
  • SMX_DLL_LOGIC_1
  • SMX_DLL_LOGIC_X

  On success, the function will return SMX_DLL_NO_ERROR, otherwise, the output change should not be expected to occur.
• set_all_pins_in_bus_to_logic_X( const p_smx_dll_bus bus_p, SMX_DLL_DOUBLE delay )

  sets the logic value of all of the output pins in the specified bus to logic level SMX_DLL_LOGIC_X after the provided delay. On success, the function will return SMX_DLL_NO_ERROR, otherwise, the output change should not be expected to occur.

• read_bus(p_smx_dll_bus bus_p, p_smx_dll_bus_conversion conversion_p)

  reads the value of the bus according to the specification defined by the bus conversion. On success, returns SMX_DLL_NO_ERROR, otherwise, the result should not be treated as valid. The read value will be assigned to the appropriate member of the bus conversion union.

• write_bus(p_smx_dll_bus bus_p, p_smx_dll_bus_conversion conversion_p, SMX_DLL_DOUBLE delay)

  based on the conversion type and the encoding type of the bus conversion, the appropriate value from the union will be written to the output bus after the provided delay. On success, the function will return SMX_DLL_NO_ERROR, otherwise, the output change should not be expected to occur.

• is_pin_logic_0(p_smx_dll_pin pin_p, SMX_DLL_ERROR* error_p)

  Returns SMX_DLL_TRUE if the pin is low. Returns SMX_DLL_FALSE if the pin is high, unknown (X), or if an error occurs. If a non-NULL error pointer is provided, any error value will be assigned, with SMX_DLL_NO_ERROR being the value assigned on success.

• is_pin_logic_1(p_smx_dll_pin pin_p, SMX_DLL_ERROR* error_p)

  Returns SMX_DLL_TRUE if the pin is high. Returns SMX_DLL_FALSE if the pin is low, unknown (X), or if an error occurs. If a non-NULL error pointer is provided, any error value will be assigned, with SMX_DLL_NO_ERROR being the value assigned on success.

• is_pin_logic_X(p_smx_dll_pin pin_p, SMX_DLL_ERROR* error_p)

  Returns SMX_DLL_TRUE if the pin is at an unknown logic level (X). Returns SMX_DLL_FALSE if the pin is high, low, or if an error occurs. If a non-NULL error pointer is provided, any error value will be assigned, with SMX_DLL_NO_ERROR being the value assigned on success.

• is_edge_event(p_smx_dll_pin pin_p, SMX_DLL_ERROR* error_p)

  Returns SMX_DLL_TRUE if an edge event (SMX_DLL_LOGIC_0 to SMX_DLL_LOGIC_1 or SMX_DLL_LOGIC_1 to SMX_DLL_LOGIC_0) has been detected on the associated pin. Returns SMX_DLL_FALSE if no edge event was detected or if an error occurs. If a non-NULL error pointer is provided, any error value will be assigned, with SMX_DLL_NO_ERROR being the value assigned on success.

• is_positive_edge(p_smx_dll_pin pin_p, SMX_DLL_ERROR* error_p)

  Returns SMX_DLL_TRUE if a positive edge event (SMX_DLL_LOGIC_0 to SMX_DLL_LOGIC_1) has been detected on the associated pin. Returns SMX_DLL_FALSE if no positive edge event was detected or if an error occurs. If a non-NULL error pointer is provided, any error value will be assigned, with SMX_DLL_NO_ERROR being the value assigned on success.

• is_negative_edge(p_smx_dll_pin pin_p, SMX_DLL_ERROR* error_p)

  Returns SMX_DLL_TRUE if a negative edge event (SMX_DLL_LOGIC_1 to SMX_DLL_LOGIC_0) has been detected on the associated pin. Returns SMX_DLL_FALSE if no negative edge event was detected or if an error occurs. If a non-NULL error pointer is provided, any error value will be assigned, with SMX_DLL_NO_ERROR being the value assigned on success.

The following functions are intended to allow the device to access buses, pins, and parameters or the device as instantiated on the schematic.

• fatal_error(p_smx_dll_device device_p, char* error_message)

  Causes the SIMPLIS simulation to abort and displays the provided error message to the user. This function directly calls the process termination mechanism and should not be expected to return a value.

• instantiate_user_storage( p_smx_dll_device device, size_t total_size )

  When called during the setup routine, allocates and assigns a block of memory (of the size requested) to the device's user_storage member. This function should only be called once per device, and only data that changes during simulation will benefit from being placed in managed user storage.

• set_scheduled_wake(p_smx_dll_device device_p, SMX_DLL_DOUBLE delay, SMX_DLL_UINT64* identifier )

  Requests that the device be awoken after the provided relative delay time. When awoken, the type of the wake reason will be set to SMX_DLL_WAKE_TYPE_WAKE_REQUESTED. If the identifier is not a NULL pointer and the dereferenced value is non-zero, the provided identifier will be provided with the wake reason. If the identifier is not a NULL pointer and the dereferenced value is zero, the value will be set to a unique identifier that will be provided with the wake reason.