Name

ocpidev-card — manage an OpenCPI HDL card.

Synopsis

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

DESCRIPTION

The hdl card noun represents an OpenCPI HDL card, which defines a hardware component that contains devices and plugs into a slot on an HDL platform. Devices are either directly attached to the pins on an HDL platform or attached to cards that plug into compatible slots on the platform. Devices on a card are considered to be part of the card, which can be plugged into a certain type of slot on any platform, rather than part of the platform itself.

An HDL card is described by an HDL card definition, which is an XML file that describes the slot type of the card, the HDL devices (controlled by HDL device workers) that are present on the card, and how they are wired to the slot. There is no HDL code associated with an HDL card. For more information about the HDL card definition’s XML structure and how it relates to HDL platforms, slots and HDL device workers, see the OpenCPI Platform Development Guide.

In a project, an HDL card is named <name>.xml and resides in one of the following locations depending on its intended use:

  • In the subdirectory hdl/cards/specs/ when the HDL card is platform-independent
  • In the subdirectory hdl/platforms/<platform>/devices/specs/ when the HDL card is platform-specific

An OpenCPI HDL card asset document can also be created for an HDL card to facilitate documenting the HDL card during the overall development process. In a project, an HDL card asset document resides in the same directory and has the same name as the HDL card’s definition but with the suffix .rst instead of .xml. Unless suppressed by options, building asset that contains the HDL card (e.g., project, library) builds viewable HTML output of HDL card asset document, and cleaning the asset containing the HDL card removes the generated HTML. The section "Documenting OpenCPI Assets" in the OpenCPI Documentation Writer Guide provides more information about this feature and describes how to create an OpenCPI HDL card asset document.

Verbs that can operate on an HDL card are:

create
Create the named HDL card according to the specified options, creating directories and files as required.
delete
Remove all files associated with the named HDL card.

The create operation creates an initial HDL card definition XML file that can be edited as necessary to define the card.

OPTIONS

In addition to the options common to all OpenCPI tools (see opencpi(1)), the options described below can be specified for operations on HDL cards. In the following descriptions, a plus sign (+) after the option indicates that it can be specified more than once on the command line.

Options When Creating HDL Cards

-P <hdl-platform>, --platform=<hdl-platform>
Specify that the HDL card being created is a platform-specific HDL card to be created in the devices/specs/ subdirectory in the specified HDL platform in the project.
-k, --keep
Keep files and directories created after an HDL card creation fails. Normally, all such files and directories are removed on any failure.

Options When Deleting HDL Cards

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

EXAMPLES

  1. At the top level of the project, create an HDL card with the name mycard. The HDL card definition named mycard.xml will be placed in the subdirectory hdl/cards/specs/: 

    ocpidev create hdl card mycard

  2. At the top level of the project, create an HDL card with the name mycard for the platform myplatform. The HDL card definition named mycard.xml will be placed in the subdirectory hdl/platforms/myplatform/devices/specs/: 

    ocpidev create hdl card mycard -P myplatform

  3. Inside the project, delete an HDL card definition named mycard.xml from a project’s hdl/cards/specs/ subdirectory: 

    ocpidev delete hdl card mycard

BUGS

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

RESOURCES

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

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

See the OpenCPI Documentation Writer Guide: https://opencpi.gitlab.io/releases/latest/docs/OpenCPI_Documentation_Writer_Guide.pdf

SEE ALSO

ocpidev(1) ocpidev-create(1) ocpidev-delete(1) ocpidev-device(1) ocpidev-platform(1) ocpidev-project(1) ocpidev-slot(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.