Name

ocpihdl — command-line tool for performing OpenCPI HDL development tasks

Synopsis

ocpihdl [<options>] <verb> [<options] [<arguments>]

DESCRIPTION

The ocpihdl(1) command-line tool is used to perform a variety of OpenCPI HDL development tasks, including:

  • Searching for and listing available HDL devices (via PCI, Ethernet, UDP, simulators, etc.)
  • Testing the existence and availability of a specific HDL device
  • Reading and writing specific registers in an HDL device
  • Loading bitstreams on an HDL device
  • Extracting the XML metadata from a running HDL device

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.

For convenience, options can occur anywhere in the ocpihdl command. The general usage concept is: perform the <verb> operation on the <noun> asset type whose name is <name>. When invoked without verbs and options, ocpihdl displays help information.

VERBS

The verbs for general operations supported by ocpihdl are:

admin
Display an HDL device’s administrative information.
bram
Create a configuration Block Random Access Memory (BRAM) file from an artifact description XML file.
deltatime
Perform a time synchronization test on an HDL device.
emulate
Emulate a network-based (UDP or Ethernet) HDL device (admin space only).
ethers
List the available (up and connected) network interfaces.
getxml
Retrieve XML metadata from a running HDL device.
load
Load a bitstream onto an HDL device.
probe
Test the existence and availability of an HDL device.
radmin
Read a specific address in an HDL device’s admin space.
reset
Perform a soft reset on an HDL device.
rmeta
Read from addresses in the metadata space of an HDL device.
search
Search for and list all available (discovered and responding) HDL devices.
settime
Set an HDL device’s GPS time to the system time.
unbram
Create an artifact description XML file from a configuration BRAM file.
wadmin
Write specific addresses in an HDL device’s admin space.

The verbs for higher-level operations (operations that rely on embedded metadata) on individual HDL workers supported by ocpihdl are:

control
Change the control state of an HDL worker instance.
get
Get instance property information for a single HDL worker or all HDL workers.
set
Set a property value in an HDL worker instance.
status
Display the status of an HDL worker instance.

The verbs for lower-level operations (operations that do not use embedded metadata) on individual workers supported by ocpihdl are:

wclear
Clear the error registers of an HDL worker instance or a range of HDL worker instances.
wdump
Display the control and status registers for an HDL worker instance or a range of HDL worker instances.
wop
Perform a control operation on an HDL worker instance or a range of HDL worker instances.
wread
Read a value from the configuration property space of an HDL worker instance or a range of HDL worker instances.
wreset
Assert reset for an HDL worker instance or a range of HDL worker instances.
wwctl
Write the control register for an HDL worker instance or a range of HDL worker instances.
wwpage
Write the window/page register for an HDL worker instance or a range of HDL worker instances to reach full 32-bit space.
wwrite
Write a single value into the configuration property space of an HDL worker instance or a range of HDL worker instances.

See OPERATIONS for a description of each ocpihdl verb, its options and arguments.

NOUNS

None.

OPTIONS

In addition to the general-purpose options common to all OpenCPI tools (see opencpi(1)), 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.

-P
Produce parseable output for ocpihdl operations that read registers.
-d <hdl-device>
Specify the name of an HDL device on which to operate. The OCPI_HDL_DEVICE environment variable can be used to set a default value for this option.
-i <network-interface>
Specify the name of the network interface on which to operate. Examples: en0, eth0.
-p <hdl-platform>
Specify the identifier of the HDL platform on which to operate. Examples: e31x, plutosdr, zed. See the OpenCPI User Guide for a list of supported HDL platforms and their identifiers.
-x
Display numeric values in hexadecimal format. If this option is not used, numeric values are displayed in decimal format.

OPERATIONS

The sections below describe each ocpihdl operation and its associated options and arguments. These operations include:

  • General operations that do not operate on individual HDL workers.
  • Operations on individual HDL workers. One set of HDL worker verbs relies on embedded metadata and is thus more user-friendly, while another more "primitive" set does not rely on embedded metadata.

General Non-HDL Worker Operations

ocpihdl admin -d <hdl-device>
Dump all of the information and state in the admin space for the HDL device specified in the -d option. Device admin space contains the information for the device and loaded bitstream as a whole.
ocpihdl bram <xml-file> <bram-file>
Convert an "artifact description XML" file into a "configuration BRAM" file to be processed (during HDL assembly build) into a read-only BRAM inside the FPGA bitstream. Specify the name of the artifact description file in <xml-file> and the file name for the generated configuration BRAM file in <bram-file>.
ocpihdl deltatime -d <hdl-device>
Measure and correct the time-skew between the system time-of-day and the specified HDL device time-of-day.
ocpihdl [-i {<network-interface> | udp}] emulate
Emulate an Ethernet- or UDP-based HDL device and respond to discovery and admin space accesses. Use the -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
List the available Ethernet network interfaces on a system and their status (whether or not they are up and connected), the default network interface used for for verbs that take the -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>
Retrieve and uncompress the XML metadata stored in the running HDL device specified with the -d option or the <hdl-device> argument and write it to the specified file.
ocpihdl load <bitstream-file> {-d <hdl-device> | <hdl-device>}
Load the specified bitstream onto the HDL device specified with the -d option or as an argument.
ocpihdl probe {-d <hdl-device> | <hdl-device>}
Contact the HDL device specified with the -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>]
Read an individual word of data from the specified offset in the admin space of the HDL device specified in the -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>
Reset the HDL device specified in the -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>]
Read an individual word of data from the specified offset in the configuration BRAM space of the HDL device specified in the -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
Search for all reachable HDL devices using all the supported control paths (PCI, Ethernet, simulator) and list the results. Use the -i option to limit the Ethernet search to the specified network interface.
ocpihdl settime -d <hdl-device>
Set the time on the HDL device specified in the -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>
Convert a configuration BRAM file (see 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>
Write a 4-byte/32-bit or 8-byte/64-bit value at the specified offset in the admin space of the specified device. Prepend 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.

HDL Worker Operations That Use Embedded Metadata

ocpihdl get [-v | -x] [<worker-instance-name> | <worker-instance-index>] [<property-name>]
Display information for all HDL workers or the HDL worker instance specified by its name in the HDL assembly or its index as returned from a previous 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>
Perform the specified control operation on the HDL worker instance specified by its name in the HDL assembly or its index as returned from a previous 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>
Set the specified property of the specified HDL worker instance name or index to the specified value. When specifying the value, use the same syntax as is used to specify a property’s initial or default value in a component specification (OCS), worker description (OWD) or HDL assembly description (OHAD). For information on property value syntax, see the chapter "Property Values Syntax and Ranges" in the OpenCPI Component Development Guide.
ocpihdl status {<worker-instance-name> | <worker-instance-index>}
Display the status of the specified HDL worker instance name or index. Status displayed includes the worker control state and the display output of the wdump operation.

HDL Worker Operations That Do Not Use Embedded Metadata

ocpihdl wclear -d <hdl-device> <worker-instance-index>[,…]
Clear the error and attention bits in the status register in the control plane infrastructure for the HDL worker(s) specified by the instance index(es) on the specified HDL device. The ocpihdl get operation can be used to return HDL worker instance indexes.
ocpihdl wdump -d <hdl-device> <worker-instance-index>[,…]
Display the current status of the control and status registers in the control plane infrastructure for the HDL worker(s) specified by the instance index(es) on the specified HDL device.
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>]
Read a value from the specified offset into the property space of the HDL worker(s) specified by the instance index(es) on the specified HDL device. Prepend 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>[,…]
Assert the control reset signal into the specified HDL worker(s) on the specified HDL device. This signal remains asserted until the ocpihdl wunreset operation is used.
ocpihdl wunreset -d <hdl-device> <worker-instance-index>[,…]
Deassert the control reset signal into the specified HDL worker(s) on the specified HDL device. After executing this operation, the "wop initialize" operation (or the "wop start" operation for HDL workers that do not implement an initialize control operation) can be issued.
ocpihdl wwctl -d <hdl-device> <worker-instance-index>[,…] [<value>]
Write the specified value to the control register in the control plane infrastructure for the specified HDL worker(s) on the specified HDL device. The <value> argument is a 32-bit value. The bit definitions are described in the OpenCPI Platform Development Guide.
ocpihdl wwpage -d <hdl-device> <worker-instance-index>[,…] [0x]<value>
Set the "window" register in the control plane infrastructure for the HDL worker(s) specified by the instance index(es) on the specified HDL device to the specified value, which sets the high order 12 address bits (31:20) of the effective address when the 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
Write the specified value to the specified offset into the property space of the HDL worker(s) specified by the instance index(es) on the specified HDL device. Prepend 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.

ENVIRONMENT VARIABLES

The following environment variables affect the ocpihdl tool:

OCPI_DEFAULT_HDL_DEVICE
Sets a default value for the -d <device> option.

EXAMPLES

  1. Convert the artifact description XML file named myad.xml to a configuration BRAM file named mybram.bin: 

    ocpihdl bram myad.xml mybram.bin

  2. Emulate the HDL device attached to the IP subnet of the host computer that implements discovery and control via UDP: 

    ocpihdl -i udp emulate

  3. Perform a two-byte read of offset 12 on the HDL device named pci:5: 

    ocpihdl -d pci:5 radmin 12/2

  4. Convert the configuration BRAM file named mybram.bin to an artifact description XML file named myad.xml: 

    ocpihdl unbram mybram.bin myad.xml

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

  6. Display the value of the property named prop1 of the worker instance named instX in hexadecimal format: 

    ocpihdl get -x instX prop1

  7. Set the value of a property named prop1 that is an array of three shorts: 

    ocpihdl set instX prop1 "-1,0x12,o177"

  8. Put the HDL worker instance named instX into a reset condition (assert reset): 

    ocpihdl control instX reset

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

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

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

BUGS

See https://www.opencpi.org/report-defects

RESOURCES

See the main web site: https://www.opencpi.org

See the OpenCPI HDL Development Guide: https://opencpi.gitlab.io/releases/latest/docs/OpenCPI_HDL_Development_Guide.pdf

See the OpenCPI User Guide: https://opencpi.gitlab.io/releases/latest/docs/OpenCPI_User_Guide.pdf

SEE ALSO

ocpidev(1) ocpidev-application(1) ocpidev-assembly(1) ocpidev-platform(1) ocpidev-primitive(1) ocpidev-worker(1) ocpirun(1) ocpixml(1)

COPYING

Copyright (C) 2023 OpenCPI www.opencpi.org. OpenCPI is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.