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.
h = Hwcosim(project);
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
Releases the resources used by the Hwcosim object h. If a link to hardware is still open, release will first close the hardware.
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.
Closes the connection between the host PC and the FPGA. The argument, h, is a handle to an Hwcosim object.
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
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.
outData = h('portName');
outData = h('portName', 25); %burst
outData = read(h, 'portName');
outData = read(h, 'portName', 25);
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
outData will be assigned a scalar or a 1xn array. If an array, the
data is the result of a burst data transfer.
run(h, inf); %start free-running
run(h, 0); %stop free-running clock
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
run(h, inf) will start the free-running
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.
This method will return a MATLAB struct array with fields
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 (
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
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(h, 'propertyName', propertyValue);
The set method sets or changes any of the contents of the internal
properties table of the Hwcosim instance
h. It is
h already exists before calling this
set(h, 'doubleProperty', pi);
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
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.
bool_val = get(h,
int_val = get(h,
double = get(h,
str_val = get(h,
M-Hwcosim Utility Functions
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.
xlHwcosim('release') %release all instances
of Hwcosim objects.