Name

ocpidev-device — manage an OpenCPI HDL device worker.

Synopsis

ocpidev [<options>] <verb> hdl device <name>

DESCRIPTION

The hdl device noun represents an OpenCPI HDL device worker, which is a special type of HDL application worker designed to support specific external hardware attached to an HDL platform or card, such as an ADC, flash memory or I/O device.

While an application worker is a component implementation that requires only abstracted data interfaces, an HDL device worker is an HDL component implementation written to the HDL authoring model that directly controls and attaches to a physical device. An HDL device worker generally implements the device manufacturer’s data sheet, providing access and visibility to the device’s native registers and capabilities. HDL device workers allow OpenCPI to use the devices attached to an HDL platform and are developed as part of enabling an HDL platform for OpenCPI. The OpenCPI Platform Development Guide provides details on how to develop an HDL device worker.

An HDL device worker can be supported by:

  • A device proxy worker, which is an RCC worker written in C++ that is specifically paired with the HDL device worker to provide a higher- level and more generic interface to the HDL device worker’s low-level one. The purpose of a device proxy worker is to make a device look more like others in its class, providing more user- and software-friendly access and visibility to the device’s capabilities. The OpenCPI RCC Development Guide describes how to develop a proxy worker.
  • A device emulator worker, which is a specialized HDL device worker that emulates a device for test purposes. A device emulator worker provides the mirror image of the HDL device worker’s external signals so that it can can emulate the device in simulation. The OpenCPI Platform Development Guide describes how to develop an HDL device emulator worker.
  • A subdevice worker, which is a specialized HDL device worker that enables multiple HDL device workers to share some underlying hardware, like shared resets, shared SPI or I2C buses. They also allow device workers to stay portable when low-level modules differ by HDL platform or card. The OpenCPI Platform Development Guide describes how to develop an HDL subdevice worker.

These support workers can be HDL platform-independent or HDL platform-specific.

An HDL device worker (and its support workers) are OpenCPI workers and are thus described by an OpenCPI Worker Description (OWD). For an HDL device worker:

  • The component specification (OCS) that the worker implements usually represents a specific type of device but can be an OpenCPI-defined "device class" component spec (for example, clock_gen-spec) and must be the OpenCPI-defined emulator-spec if the OWD describes an HDL device emulator worker. The OpenCPI-defined OCSes are located in the top-level specs/ directory of the core project.
  • The language used for the source code is VHDL.
  • Signal connections with the hardware attached to the pins of the HDL platform (FPGA) are defined for the HDL device worker in addition to any port and property definitions. Signal connections defined in HDL subdevice worker OWDs are to pins that are shared between the HDL device workers that the HDL subdevice worker supports. Signal connections are not defined in emulator device worker OWDs because an HDL emulator device automatically inherits the signal connections from the device worker it emulates.

An HDL subdevice worker OWD also specifies the device worker(s) that the HDL subdevice worker supports and how it connects to each supported HDL device worker.

The OpenCPI Platform Development Guide provides more information about the XML structure of HDL device worker, subdevice worker and emulator worker OWDs, while the OpenCPI HDL Development Guide provides information about the XML structure of an HDL worker OWD.

In a project, an HDL device worker resides in its own directory <name>.hdl and can be located in the following places depending on its intended use:

  • In the platform-generic HDL device library at hdl/devices/. This library contains HDL device workers that can be used on different HDL platforms and cards. It can also contain RCC-based HDL device proxy workers, HDL subdevice workers and HDL device emulator workers for one or more HDL device workers in the library.
  • In a platform-specific HDL device library at platforms/<hdl-platform>/devices/. This library contains HDL device workers, proxies, subdevices and emulators that function only on that platform.
  • In the directory hdl/cards/. This subdirectory contains HDL device workers, proxies, subdevices and emulators that are specific to or can only be used on cards, rather than those that are generally useful on different platforms and cards.

Verbs that can operate on an HDL device worker are:

build
Compile the HDL device worker source code, creating files and directories as required.
clean
Remove all generated and compiled files for the HDL device worker.
create
Create the named HDL device worker, creating files and directories as required.
delete
Remove all directories and files associated with the named HDL device worker.

Note that the utilization verb can be used with the worker noun to display an HDL device worker’s FPGA usage statistics. See ocpidev-worker(1) for more information.

Within the HDL device worker’s directory are the OWD (named <name>.xml) and its primary source code file (named <name>.vhd. The ocpidev create operation produces initial versions of these files that can then be edited as necessary to produce the HDL device worker implementation.

The ocpidev build operation for an HDL device worker creates additional files in the worker’s directory, such as architecture-independent source code and XML files, in a directory named gen and architecture-specific object and binary files for the compilation target being built, in a directory named target-<hdl-platform>; for example, target-zed or target-xsim. These are the files that the ocpidev clean operation removes.

Note that an asset’s name is implied by the directory you’re in when you issue the ocpidev command. For HDL device workers, this means that you can perform operations (verbs) on the HDL device worker without having to specify its name when you issue the ocpidev command from inside the HDL device worker directory.

OPTIONS

In the descriptions below, a plus sign (+) after the option indicates that it can be specified more than once on the command line.

Keywords for platforms supported by OpenCPI that can be specified in the <platform> argument to an option can be found in the tables of supported platforms in the OpenCPI User Guide.

Keywords for architectures supported by OpenCPI that can be specified in the <target> argument to an option include isim, modelsim, xsim, stratix4, stratix5, virtex5, virtex6, zynq, zynq_is, spartan3adsp.

Options That Apply to All Operations (Verbs) on HDL Device Workers

--hdl-library=<hdl-library>, -h <hdl-library>
Specify the HDL library under the hdl/ directory of the project in which to operate on the HDL device worker. Valid values are only one of: devices, cards, adapters.
-d <directory>
Specify the directory in which the command should be run. Analogous to the -C option in the POSIX make command.
-v, --verbose
Describe what is happening in command execution in more detail.

Options When Creating HDL Device Workers

--exclude-platform=<platform>, -Q <platform>+
Do not build the HDL device worker for the specified platform. See also the description of the ExcludePlatforms= OWD attribute in the OpenCPI Component Development Guide.
--only-platform=<platform>, -G <platform>+
Only build the HDL device worker for the specified platform. See also the description of the OnlyPlatforms OWD attribute in the OpenCPI Component Development Guide.
-A <directory>+
Specify a directory to search for XML include files.
-C <core>+
Specify an HDL primitive core on which the HDL device worker depends and with which it should be built.
-E <hdl-device>
Specify that the HDL device worker being created is an emulator worker for the specified HDL device worker.
-I <directory>+
Specify a directory to search for include files (C, C++, Verilog).
-O <file>+
Specify a source code file to compile when building the HDL device worker that is not included by default; that is, in addition to the <name>.vhd file.
-P <hdl-platform>
Specify that the worker being created is a platform-specific HDL device worker or device proxy to be created in the devices/ library for the specified HDL platform in the project.
-S <component-spec>
Specify the component specification (OCS) that the HDL device worker implements.
-T <target>+
Only build the HDL device worker for the specified architecture. See also the description of the OnlyTargets OWD attribute in the OpenCPI Component Development Guide.
-U <hdl-device>+
Specify that the HDL device worker being created is an HDL subdevice worker that supports the specified HDL device worker.
-Y <primitive-library>+
Specify an HDL primitive library on which the HDL device worker depends.
-Z <target>+
Do not build the HDL device worker for the specified architecture. See also the description of the ExcludeTargets OWD attribute in the OpenCPI Component Development Guide.
-k
Keep files and directories created after an HDL device worker creation fails. Normally, all such files and directories are removed on any failure.
-y <component-library>+
Specify a component library to search for workers, devices and/or specs referenced by the HDL device worker being created.

Options When Deleting HDL Device Workers

-f
Force deletion: do not ask for confirmation when deleting a worker. Normally, you are asked to confirm a deletion.

Options When Building HDL Device Workers

--hdl-target=<target>+
Build the HDL device worker for the specified HDL architecture.
--hdl-platform=<hdl-platform>+
Build the HDL device worker for the specified HDL platform.

EXAMPLES

  1. At the top level of the project, create a platform-specific HDL device worker named mydevworker that implements the mydevcomp OCS and runs on the HDL platform myplatform. (The OCS does not need to be specified on the command line if the HDL device worker has the same name as the component spec.) The HDL device worker directory mydevworker.hdl is created in the HDL library /hdl/platforms/myplatform/devices/: 

    ocpidev create hdl device mydevworker.hdl -S mydevcomp-spec -P myplatform

  2. At the top level of the project, create a platform-independent HDL device worker named mydevcomp that implements the mydevcomp OCS. The HDL device worker directory mydevcomp.hdl is created in the HDL library hdl/devices/: 

    ocpidev create hdl device mydevcomp.hdl --hdl-library=devices

  3. Inside the project’s hdl/devices/ directory, create a platform-independent HDL emulator device worker named myemulator to support the HDL device worker mydevice: 

    ocpidev create hdl device myemulator.hdl -E mydevice -S emulator-spec

  4. Inside the project’s hdl/devices/ directory, create a platform-independent HDL subdevice worker named mysubdevice to support the HDL device worker mydevice: 

    ocpidev create hdl device myemulator.hdl -U mydevice

  5. Inside the HDL device worker’s directory, compile its source code: 

    ocpidev build hdl device

  6. Inside the hdl/devices/ directory in the project, compile the source code for the HDL device worker named mydevice for the zed and xsim platforms: 

    ocpidev build device mydevice.hdl --hdl-platform=zed --hdl-platform=xsim

  7. Inside the directory for the HDL device worker named mydevice for the myplatform platform (hdl/platforms/myplatform/devices/mydevice.hdl/), compile the device worker’s source code for for the Zynq HDL architecture: 

    ocpidev build hdl device mydevice.hdl --hdl-target=zynq

  8. Inside the HDL device worker’s directory, remove the compiled source code for the HDL device worker named mydevice: 

    ocpidev clean hdl device

BUGS

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

RESOURCES

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

SEE ALSO

ocpidev(1) ocpidev-application(1) ocpidev-assembly(1) ocpidev-card(1) ocpidev-build(1) ocpidev-clean(1) ocpidev-component(1) ocpidev-create(1) ocpidev-delete(1) ocpidev-library(1) ocpidev-platform(1) ocpidev-primitive(1) ocpidev-project(1) ocpidev-slot(1) ocpidev-worker(1)

COPYING

Copyright (C) 2020 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.