ocpihdl — command-line tool for performing OpenCPI HDL development tasks
The ocpihdl(1) command-line tool is used to perform a variety of OpenCPI HDL
development tasks, including:
An HDL device in this case refers to an instance of an HDL platform (FPGA or FPGA simulator) in an OpenCPI system (and not to a device attached to an FPGA inside the platform) that hosts an HDL container for execution. HDL devices have unique names within an OpenCPI system. Each name starts with a prefix that indicates how OpenCPI discovers and controls the device. See the chapter "HDL Device Naming" in the OpenCPI HDL Development Guide for a description of these prefixes and HDL device naming syntax. Also see the OpenCPI HDL Development Guide for detailed information on the OpenCPI HDL development process, including how to develop HDL workers, HDL primitives, HDl assemblies and bitstreams to support the execution of OpenCPI applications on FPGAs.
The verbs for general operations supported by ocpihdl are:
admin
bram
deltatime
emulate
ethers
getxml
load
probe
radmin
reset
rmeta
search
settime
unbram
wadmin
The verbs for higher-level operations (operations that rely on
embedded metadata) on individual HDL workers
supported by ocpihdl are:
control
get
set
status
The verbs for lower-level operations (operations that do not
use embedded metadata) on individual workers
supported by ocpihdl are:
wclear
wdump
wop
wread
wreset
wwctl
wwpage
wwrite
See OPERATIONS for a description of each ocpihdl verb,
its options and arguments.
The options described below can be used with many ocpihdl operations.
An option’s effect on an individual ocpihdl operation is described
in that operation’s description in OPERATIONS.
-d <hdl-device>
-i <network-interface>
en0, eth0.
-l <log-level>
opencpi(1) for a description of possible values.
Using this option overrides the level set in the OCPI_LOG_LEVEL
environment variable.
-P
ocpihdl operations that read registers.
-p <hdl-platform>
ml605, alst4, zed, e31x. See the
OpenCPI User Guide for a list of supported HDL platforms and their identifiers.
-x
The sections below describe each ocpihdl operation and its associated options
and arguments. These operations include:
ocpihdl admin -d <hdl-device>
-d option. Device admin space contains the
information for the device and loaded bitstream as a whole.
ocpihdl bram <xml-file> <bram-file>
ocpihdl deltatime -d <hdl-device>
ocpihdl [-i {<network-interface> | udp}] emulate
-i option to
specify the network interface on which the emulated device
should appear. If this option is not specified, the first
available (up and connected) network interface is used.
Use the udp keyword in the -i option to
emulate an OpenCPI HDL device attached
to the IP subnet of the host computer implementing discovery
and control via UDP.
ocpihdl ethers
-i option (the first listed that is up and connected)
and the identity chosen for the system (based on the
first network interface with an address and a MAC address).
ocpihdl getxml {-d <hdl-device> | <hdl-device>} <output-file>
-d option or the <hdl-device> argument
and write it to the specified file.
ocpihdl load <bitstream-file> {-d <hdl-device> | <hdl-device>}
-d option or as an argument.
ocpihdl probe {-d <hdl-device> | <hdl-device>}
-d option or as an argument
and see if it responds. This operation should work regardless of
whether or not the HDL device is running an application.
ocpihdl radmin [-P] -d <hdl-device> [0x]<offset>[/<size>]
-d option. Prepend 0x to
<offset> to indicate hexadecimal format; if this notation is not used,
the format is decimal. Append the /<size>
notation to <offset> to specify the size of the access in bytes;
for example, /2, /4, or /8. If this notation is not used, the access is
a 32-bit access. Use the -P option to return just the value
in hexadecimal format. If this option is not used, the operation
returns a message with the offset and the value.
ocpihdl reset -d <hdl-device>
-d option without
affecting the control path to the device.
For example, on a PCI-Express-based HDL device, an ocpihdl reset operation
does not damage or reconfigure the PCI-Express interface.
ocpihdl rmeta [-P] -d <hdl-device> [0x]<offset>[/<size>]
-d option.
Prepend 0x to <offset> to indicate hexadecimal format; if this notation
is not used, the format is decimal.
Append the /<size> notation to <offset> to
specify the size of the access in bytes;
for example, /2, /4, or /8. If this notation is not used, the access is
a 32-bit access. Use the -P option to return just the value
in hexadecimal format. If this option is not used, the operation
returns a message with the offset and the value.
ocpihdl [-i <network-interface>] search
-i option to limit the Ethernet search to the
specified network interface.
ocpihdl settime -d <hdl-device>
-d option
from the current system time. Use the ocpihdl admin operation
on the target HDL device to get the current time.
ocpihdl unbram <bram-file> <xml-file>
ocpihdl bram)
into an artifact description XML file.
Specify the file name of the configuration BRAM file
in <bram-file> and the name of the artifact description file
to be output in <xml-file>.
ocpihdl wadmin -d <hdl-device> [0x]<offset>[/<size>] <value>
0x to <offset> to indicate hexadecimal format.
Append the /<size> notation to <offset> to
specify the size of the access in bytes;
for example, /4 or /8. If this notation is not used, the access is
a 32-bit access.
ocpihdl get [-v | -x] [<worker-instance-name> | <worker-instance-index>] [<property-name>]
ocpihdl operation like ocpihdl get.
When an HDL worker instance is specified,
the name of a property can be supplied as an argument to display the value of that property.
The operation recognizes the data types of properties and displays the values accordingly.
Use the -v option to specify all property values; if this option is not used, the operation
displays summary information. Use the -x option to display all numeric values in hexadecimal format;
if this option is not used, the values are displayed in decimal format.
ocpihdl control {<worker-instance-name> | <worker-instance-index>} <control-operation>
ocpihdl operation like ocpihdl get. Possible
identifiers for control operations are
the lifecycle operations identifiers initialize, start, stop and release and the identifiers
reset and unreset. For more information on OpenCPI worker lifecycle control operations, see the chapter
"Authoring Models" in the OpenCPI Component Development Guide.
ocpihdl set [-x] {<worker-instance-name> | <worker-instance-index>} <property-name> <value>
ocpihdl status {<worker-instance-name> | <worker-instance-index>}
wdump operation.
ocpihdl wclear -d <hdl-device> <worker-instance-index>[,…]
ocpihdl get operation can be used to return
HDL worker instance indexes.
ocpihdl wdump -d <hdl-device> <worker-instance-index>[,…]
ocpihdl wop -d <hdl-device> <worker-instance-index>[,…] <control-operation>
Execute a control operation for the HDL worker(s) specified by the instance index(es) on the specified HDL device, directly accessing the hardware that makes the control operation request of the worker. Possible control operations are:
after - inform the worker that a batch of property reads has completed
before - inform the worker that a batch of property settings will occur
initialize - request that a worker initialize itself after an ocpihdl wunset operation
release - return the worker to the pre-initialized state
start - put the worker into an operational state after stop or initialize
stop - suspend operation of the worker
test - run the worker’s built-in test
The start control operation is the only operation implemented for all workers. Other operations
have unpredictable or erroneous results when requested for workers that don’t implement them.
ocpihdl wread -d <hdl-device> <worker-instance-index>[,…] [0x]<offset>[/<size>][<number-of-accesses>]
0x to <offset> to indicate hexadecimal format.
Append the /<size> notation to <offset> to specify the size of the access in bytes;
possible sizes are 1, 2, 4 and 8. If this optional notation is not used, the default size is 4.
Use the <number-of-accesses> argument to specify the number of accesses to make; if this argument is
not used, the default is 1. See the ocpihdl wwpage operation for workers whose
property space is larger than 1 MByte (2^20).
ocpihdl wreset -d <hdl-device> <worker-instance-index>[,…]
ocpihdl wunreset operation is used.
ocpihdl wunreset -d <hdl-device> <worker-instance-index>[,…]
ocpihdl wwctl -d <hdl-device> <worker-instance-index>[,…] [<value>]
ocpihdl wwpage -d <hdl-device> <worker-instance-index>[,…] [0x]<value>
ocpihdl wread and ocpihdl wwrite operations are issued. The offset in
those operations supplies bits (19:0) of the effective address. An HDL worker’s property
space can be a full-32 bit space (4 GBytes). Use this operation
to access more than the first 1MByte (2^20 bytes).
ocpihdl wwrite -d <hdl-device> <worker-instance-index>[,…] [0x]<offset>[/<size>] <value
0x to <offset> to indicate hexadecimal format.
Append the /<size> notation to <offset> to specify the size of the access in bytes;
possible sizes are 1, 2, 4 and 8. If this optional notation is not used, the default size is 4.
Use the ocpihdl wwpage operation before using ocpihdl wwrite to access more
than the first 1MByte (2^20 bytes) for HDL workers with large property spaces.
The following environment variables affect the ocpihdl tool:
-d <device> option.
Convert the artifact description XML file named myad.xml to
a configuration BRAM file named mybram.bin:
ocpihdl bram myad.xml mybram.bin
Emulate the HDL device attached to the IP subnet of the host computer that implements discovery and control via UDP:
ocpihdl -i udp emulate
Perform a two-byte read of offset 12 on the HDL device named pci:5:
ocpihdl -d pci:5 radmin 12/2
Convert the configuration BRAM file named mybram.bin to
an artifact description XML file named myad.xml:
ocpihdl unbram mybram.bin myad.xml
Write an 8-byte value at offset 0x20 with the value 12345
on the HDL device named pci:5:
ocpihdl wadmin -d pci:5 0x20/8 12345
Display the value of the property named prop1 of the worker instance
named instX in hexadecimal format:
ocpihdl get -x instX prop1
Set the value of a property named prop1 that is an array of three shorts:
ocpihdl set instX prop1 "-1,0x12,o177"
Put the HDL worker instance named instX into a reset condition (assert reset):
ocpihdl control instX reset
Clear the error and attention status for HDL worker instance 5 on the
HDL device named PCI:5:
ocpihdl wclear -d PCI:5 5
Read three single bytes at offset 6 from HDL worker instance 11 on HDL device 5:
ocpihdl read -d 5 11 6/1 3
Read location 0x12345678 in HDL worker instance 7 with a full 4GByte property space on the
HDL device named pci:5:
ocpihdl wwpage -d pci:5 7 0x123 ocpihdl wread -d pci:5 7 0x45678
Write location 0x20 in HDL worker instance 6 on the HDL device named pci:5
with the 64-bit value 0x123456789abc:
ocpihdl wwrite -d pci:5 6 0x20 0x123456789abc