M-Hwcosim MATLAB Class - 2025.2 English - UG1483

The Hwcosim MATLAB class provides a higher level abstraction of the hardware co-simulation engine. Each instantiated Hwcosim object represents a hardware co-simulation instance. It encapsulates the properties, such as the unique identifier, associated with the instance. Most of the instruction invocations take the Hwcosim object as an input argument. For further convenience, you can use alternative shorthand for certain operations.

Constructor

Syntax

h = Hwcosim(project);

Description

Creates an Hwcosim instance. An instance is a reference to the hardware co-simulation project and does not signify an explicit link to hardware. Creating a Hwcosim object informs the Hwcosim engine where to locate the FPGA bitstream, it does not download the bitstream into the FPGA. The bitstream is only downloaded to the hardware after an open command is issued.

The project argument needs to point to the hwc file that describes the hardware co-simulation.

Creating the Hwcosim object lists all input and output ports. The following example below the output of a call to the Hwcosim constructor. It displays the ID of the object and a list of all the input and output gateways/ports.

>> h = Hwcosim(p)
Model Composer HDL Hardware Co-simulation Object
  id: 30247
  inports:
      gateway_in
      gateway_in2
  outports:
      gateway_out

Destructor

Syntax

release(h);

Description

Releases the resources used by the Hwcosim object h. If a link to hardware is still open, release first closes the hardware.

Open Hardware

Syntax

open(h); 

Description

Opens the connection between the host PC and the FPGA. Before this function can be called, the hardware co-simulation interface must be configured. The argument, h, is a handle to an Hwcosim object.

Close Hardware

Syntax

close(h); 

Description

Closes the connection between the host PC and the FPGA. The argument, h, is a handle to an Hwcosim object.

Write Data

Syntax

h('portName') = inData; %If inData is array, results in burst write.
h('portName') = [1 2 3 4];
write(h, 'portName', inData);
write(h, 'portName', [1 2 3 4]); %burst mode

Description

Ports are referenced by their legalized names. Name legalization is a requirement for VHDL and Verilog synthesis. It converts names into all lower-case, replaces white space with underscores, and adds unique suffixes to avoid namespace collisions. To view the legalized input and output port names, run the helper command portinfo(h). Alternatively, see the output of Hwcosim at the time of instance creation.

inData is the data to be written to the port. Normal single writes are performed if inData is a scalar value. If burst mode is enabled and inData is a 1xn array, it is interpreted as a timeseries and written to the port via burst data transfer.

Read Data

Syntax

outData = h('portName');
outData = h('portName', 25); %burst mode
outData = read(h, 'portName');
outData = read(h, 'portName', 25); %burst

Description

Ports are referenced by their legalized names (see previous class above).

If burst mode is enabled, and depending on whether the read command has 3 or 4 parameters (2 or 3 parameters in the case of a subscript reference h('portName', ...)), outData is assigned a scalar or a 1xn array. If an array, the data is the result of a burst data transfer.

Run

Syntax

run(h);
run(h, n);
run(h, inf); %start free-running clock
run(h, 0); %stop free-running clock 

Description

When you configure the hardware co-simulation object to run in single-step mode, the run command advances the clock. run(h) advances the clock by one cycle. run(h,n) advances the clock by n cycles.

The run command also turns on (and off) free-running clock mode: run(h, inf) starts the free-running clock and run(h, 0) stops it.

A read of an output port needs to be preceded either by a 'dummy' run command or by a write. This forces a synchronization of the read cache with the hardware.

Port Information

Syntax

portinfo(h);

Description

This method returns a MATLAB struct array with fields inports and outports. These themselves are struct arrays holding all input and output ports, respectively, again represented as struct arrays. The fieldnames of the individual port structs are the legalized portnames themselves, so you might obtain a cell array of input port names suitable for Hwcosim write commands by issuing these commands:

a = portinfo(h);
inports = fieldnames(a.inports);

You can issue a similar series of commands for output ports (outports).

Additional information contained in the port structs:

simulink_name

Provides the fully hierarchical Simulink name including spaces and line breaks.

rate

Contains the signal's rate period with respect to the DUT clock.

type

Holds the Model Composer data type information.

fifo_depth

(If burst mode is enabled), indicates the maximum size of data bursts that can be sent to Hardware in a batch.

Set Property

Syntax

set(h, 'propertyName', propertyValue);

Description

The set method sets or changes any of the contents of the internal properties table of the Hwcosim instance h. It is required that h already exists before calling this method.

Examples

set(h, 'booleanProperty', logical(0));

set(h, 'integerProperty', int32(12345));

set(h, 'doubleProperty', pi);

set(h, 'stringProperty', 'Rosebud!');

Get Property

Syntax

This method returns the value of any of the contents of the internal properties table in the Hwcosim instance h, referenced by the propertyName key. It is required that h already exists before calling this method. If the propertyName key does not exist in h, the method throws an exception and prints an error message.

Examples

bool_val = get(h, 'booleanProperty');

int_val = get(h, 'integerProperty');

double = get(h, 'doubleProperty');

str_val = get(h, 'stringProperty');

M-Hwcosim Utility Functions

xlHwcosim

Syntax

xlHwcosim('release');

Description

When M-Hwcosim objects are created, global system resources register each of these objects. These objects are typically freed when a release command is called on the object. xlHwcosim provides an easy way to release all resources used by M-Hwcosim in the event of an unexpected error. If possible use the release functions for each of the objects because the xlHwcosim call releases the resources for all instances of a particular type of object.

Example

xlHwcosim('release') %release all instances of Hwcosim objects.