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. 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)
System Generator 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, in order 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 may 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 System Generator 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!');
For a practical application of the set property method in the context of Point-to-Point Ethernet Hardware Co-Simulation, see Selecting the Adapter for Point-to-Point Ethernet Hardware Co-Simulation with M-Hwcosim
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.