M-Hwcosim MATLAB Class - 2024.1 English

Vitis Model Composer User Guide (UG1483)

Document ID
UG1483
Release Date
2024-05-30
Version
2024.1 English

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, alternative shorthand is provided for certain operations.

Table 1. Operation Syntax
Actions Syntax
Constructor h = Hwcosim(project)
Destructor release(h)
Open hardware open(h)
Close hardware close(h)
Write data write(h, 'portName', inData);
Read data outData = read(h, 'portName');
Run run(h);
Port information portinfo(h);
Set property set(h, 'propertyName', propertyValue);
Get property propertyValue = get(h, 'propertyName');

Constructor

Syntax

h = Hwcosim(project);

Description

Creates an Hwcosim instance. Note that 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 should point to the hwc file that describes the hardware co-simulation.

Creating the Hwcosim object will list all input and output ports. The example below shows the output of a call to the Hwcosim constructor, displaying 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 will first close 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, and converts names into all lower-case, replaces white space with underscores, and adds unique suffixes to avoid namespace collisions. To find out what the legalized input and output port names are, run the helper command portinfo(h), or 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 will be 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 will be 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 the hardware co-simulation object is configured to run in single-step mode, the run command is used to advance the clock. run(h) will advance the clock by one cycle. run(h,n) will advance the clock by n cycles.

The run command is also used to turn on (and off) free-running clock mode: run(h, inf) will start the free-running clock and run(h, 0) will stop it.

A read of an output port will need to be preceded either by a 'dummy' run command or by a write, to force a synchronization of the read cache with the hardware.

Port Information

Syntax

portinfo(h);

Description

This method will return a MATLAB struct array with fields inports and outports, which 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 are simulink_name, which provides the fully hierarchical Simulink name including spaces and line breaks, rate, which contains the signal's rate period with respect to the DUT clock, type, which holds the Model Composer data type information, and, if burst mode is enabled, fifo_depth, indicating 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

The get property 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 are used to 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. The release functions for each of the objects should be used if possible because the xlHwcosim call release the resources for all instances of a particular type of object.

Example

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