ocpihdl

Description

The ocpihdl 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.

Usage

$ ocpihdl
Usage is: ocpihdl <command> [<options>...] [<command args>...]
  Major commands/modes:
    search [-i <interface>]      # search for OpenCPI HDL devices, limit ethernet to <interface>
    emulate [-i <interface>]     # emulate an HDL device on ethernet, on first or specified interface
    ethers                       # list available ethernet interfaces
    probe <hdl-dev>              # see if a specific HDL device is available
    get [<instance> [<property]] # get info from bitstream
    set <instance> <property> <value>
                                 # set property value for worker instance
    control <instance> <operation>
                                 # perform reset, unreset, or control operation
    status <instance>            # show status of worker/instance
    testdma                      # test for DMA memory setup
    admin <hdl-dev>              # dump admin information (reading only) for <hdl-device>
    wadmin <hdl-dev> <offset> <value>
                                 # write admin word <value> for <hdl-device> at <offset>
    radmin <hdl-dev> <offset>    # read admin word for <hdl-device> at <offset>
    settime <hdl-dev>            # set the GPS time of the device to system time
    deltatime <hdl-dev>          # measure round trip and difference between host and device
    dump <hdl-dev>               # dump all state/status of <platform> including all workers
    reset <hdl-dev>              # reset platform
    flash <hdl-dev>              # flash load platform
    bram <infile> <outfile>      # create a BRAM file from input (XML) file
    unbram <infile> <outfile>    # recreate the original file from a BRAM file
    uuid -p <platform> -c <part> <outputfilename>
    wclear <hdl-dev> <worker>    # clear worker status errors
    wdump <hdl-dev> <worker>     # dump worker's control plane registers
    wop <hdl-dev> <worker> <op>  # perform control operation on worker
          ops are: initialize, start, stop, release, after, before
    wread <hdl-dev> <worker> <offset>[/size]
                                 # perform config space read of size bytes (default 4) at offset
    wreset <hdl-dev> <worker>    # assert reset for worker
    wunreset <hdl-dev> <worker>  # deassert (enable) worker
    wwctl <hdl-dev> <worker> <val>
                                 # write worker control register
    wwpage <hdl-dev> <worker> <val>
                                 # write worker window register
    wwrite <hdl-dev> <worker> <offset>[/size] <value>                                 # perform config space write of size bytes (default 4) at offset
                                 # generate UUID verilog file
    load  <hdl-dev> <file>       # load bitstream from file
    unload  <hdl-dev>            # revert device to unloaded state: no bitstream
    getxml <hdl-dev> <file>      # Extract the xml metadata from the device into the file
    simulate                     # run simulator inside created sim: device
  Options: (values are either directly after the letter or in the next argument)
    -l <level>                   # set log levels
    -i <interface>               # set ethernet interface to use
    -d <hdl-device>              # identify a specific hdl device to use
    -p <hdl-platform>            # specify a particular hdl platform (e.g. ml605)
    -c <hdl-part>                # specify a particular part/chip (e.g. xc6vlx240t
    -s <spin-clocks>             # clocks to credit/run the sim between control messages
    -t <sleep-usecs>             # delay time letting sim run between credits
    -T <sim-time>                # total simulation time before terminating
    -D                           # turn off simulation dumping
    -e <sim-executable>          # simulator executable "bitstream" file
    -A                           # make the simulator publically available on the LAN
    -v                           # be verbose
    -P                           # produce parsable output from admin/worker read
    -x                           # print numeric values in hex rather than decimal
  <worker> can be multiple workers such as 1,2,3,4,5.  No ranges.
  <hdl-dev> examples: 3                            # PCI device 3 (i.e. 0000:03:00.0)
                      0000:04:00.0                 # PCI device 0000:04:00.0
                      PCI:0001:05:04.2             # fully specified PCI device
                      a0:00:b0:34:55:67            # ethernet MAC address on first up+connected interface
                      eth0/a0:00:b0:34:55:67       # ethernet address on a specific interface
                      Ether:eth1/a0:00:b0:34:55:67 # fully specified Ethernet-based device

Environment Variables

The following environment variables affect the ocpihdl tool:

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

Examples

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
```