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