ocpidev-primitive — manage an OpenCPI HDL primitive.
The hdl primitive noun represents an OpenCPI primitive, which is an HDL asset
at a level that is lower than HDL workers and that can be used as building
blocks for workers or other primitives. HDL primitives are useful when there is lower-level code
that is reused or shared in different HDL workers or when workers import
non-OpenCPI code modules that should be left untouched.
An HDL primitive is either:
HDL primitive library, which is a collection of HDL
primitive modules compiled from source code into a library
from which individual modules can be used as needed by HDL workers or other primitives or cores.
HDL primitive core, which is a single primitive module that can be
built and/or synthesized from source code, imported from a third party
presynthesized and possibly encrypted, or generated by vendor-specific
FPGA synthesis tools like Xilinx CoreGen and Altera MegaWizard.
In a project, an HDL primitive resides in its own directory <name> in the
hdl/primitives/ subdirectory.
An HDL primitive cannot have the same name as a worker.
The directory contains the HDL primitive’s XML file, <name>.xml, and
its source code (Verilog or VHDL, with possible pre-built files
for HDL primitive cores). The ocpidev create operation for an HDL primitive
creates an initial version of the <name>.xml file
and, for primitive libraries, an initial <name>_pkg.vhd file.
These files can then be edited as necessary for the HDL primitive.
For details on how to develop an HDL primitive, see the chapter
"HDL Primitives" in the OpenCPI HDL Development Guide.
A skeleton OpenCPI HDL primitive library or core asset document is also created along with the initial primitive XML file and (for a primitive library) VHDL file to allow for HDL primitive documentation development to occur during the overall HDL primitive development process. Unless suppressed by an option, compiling the HDL primitive or the asset that contains it also generates viewable HTML output of its asset document. The chapter "Documenting OpenCPI Assets" in the OpenCPI Documentation Writer Guide provides more information about this feature and how to write a HDL primitive asset document.
Verbs that can operate on an HDL primitive are:
build
--doc-only and --no-doc
options to control the asset document building function.
clean
--doc-only and --no-doc options
to control the asset document cleaning function.
create
delete
Note that an asset’s name is implied by the directory you’re in when
you issue the ocpidev command. For an HDL primitive, this means that you can
perform operations (verbs) on the HDL primitive without having to specify its
name when you issue the ocpidev command from inside the HDL primitive directory.
The ocpidev tool can also operate on a plural primitives noun.
The syntax is:
ocpidev [<options>] [build|clean] primitives
where the build and clean operations and any specified options
are applied to all HDL primitives in a project.
In addition to the options common to all OpenCPI tools (see opencpi(1)), the options described below can be specified for operations on HDL primitives. In the following descriptions, 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, zynq, zynq_ultra, zynq_ise, spartan3adsp.
-G <platform>, --only-platform=<platform>+
-Q <platform>, --exclude-platform=<platform>+
-T <target>, --only-target=<target>+
-Z <target>, --exclude-target=<target>+
-k, --keep
-B <file>, --prebuilt=<file>
.edf file from Xilinx Vivado, an .ngc file
from Coregen or a .qxp file from Quartus.
-M <module>, --module=<module>
create operation.
-H, --no-depend
$OCPI_ROOT_DIR/projects/core/hdl/primitives
(currently bsv, cdc, fixed_float, and ocpi).
-J, --no-elaborate
-f
--doc-only
--no-doc
--hdl-platform=<platform>+
--hdl-target=<target>+
Inside the project or the project’s hdl/primitives/ directory,
create an HDL primitive core named myprimcore where the top module
of the core will be mytopmod:
ocpidev -M mytopmod create hdl primitive core myprimcore
Inside the project or the project’s hdl/primitives/ directory,
create an HDL primitive library named myprimlib
and indicate that it does not depend on any other primitive
libraries:
ocpidev -H create hdl primitive library myprimlib
In the project that contains the HDL primitive, compile
the source code for the HDL primitive core named myprimcore
for the Zynq architecture but do not build its asset document:
ocpidev build hdl primitive core myprimcore --hdl-target=zynq --no-doc
Inside the project, remove the generated HTML output of the HDL primitive asset documents for all HDL primitives in the project:
ocpidev clean hdl primitives --doc-only
See the main web site: https://www.opencpi.org
See the OpenCPI Component Development Guide: https://opencpi.gitlab.io/releases/latest/docs/OpenCPI_Component_Development_Guide.pdf
See the OpenCPI HDL Development Guide: https://opencpi.gitlab.io/releases/latest/docs/OpenCPI_HDL_Development_Guide.pdf
See the OpenCPI Documentation Writer Guide: https://opencpi.gitlab.io/releases/latest/docs/OpenCPI_Documentation_Writer_Guide.pdf