ocpiadmin

Name

ocpiadmin — command-line tool for managing an OpenCPI installation

Synopsis

ocpiadmin [<options>] <verb> <noun> [<name> [<argument>… ]]

DESCRIPTION

The ocpiadmin(1) command-line tool is used to perform installation and deployment tasks that are carried out on an OpenCPI installation after the basic installation procedure is completed to prepare OpenCPI for use on embedded systems. These tasks include:

Building platforms and simulators that are intended as targets for OpenCPI development that have not been automatically built as part of the basic OpenCPI installation. Building a platform enables OpenCPI assets for that platform to be developed in OpenCPI projects. It also enables the platform to be integrated into system boot kits - for example, on bootable SD cards - to be created for embedded systems that use them.
Creating a bootable media directory tree (SD card contents) for OpenCPI required by the software (RCC) and hardware (HDL/FPGA) platforms that comprise the embedded system. The bootable media directory tree for a particular software-hardware platform configuration can then be written to the manufacturer’s SD card to enable booting the embedded system for OpenCPI.

For more information about these tasks and how they relate to enabling OpenCPI development on embedded systems, see the OpenCPI Installation Guide.

For convenience, options can occur anywhere in the command. The general usage concept for ocpiadmin is: perform the <verb> operation on the <noun> whose name is <name>.

VERBS

The verbs supported by ocpiadmin are:

deploy: Create a bootable media directory tree for the named RCC (software) platform on the named HDL (FPGA) platform. The specified platforms must have been previously built.
install: Prepare the OpenCPI installation for using the named RCC or HDL platform or simulator.

NOUNS

The nouns supported by ocpiadmin are:

platform: A particular type of processing hardware and/or software that can host a container for executing OpenCPI workers.
tool: A software program or collection of programs provided by a third-party/vendor, used by OpenCPI to enable it to target embedded software and FPGA/HDL platforms.

OPTIONS

In addition to the options common to all OpenCPI tools (see opencpi(1)), the following options can be specified for the install verb plus platform noun only. In the descriptions below, a plus sign (+) after the option indicates that it can be specified more than once on the command line. Arguments to word-form options are preceded by an equal sign (=) (as shown in the following descriptions) or a space. Arguments to letter options are preceded by a space.

-g <git-rev>, --git-revision=<git-rev>: Specifies the branch, tag or other valid git revision to check out after downloading/cloning the project specified in the --package-id (-p) option (described below). This option can be used with the -p (--package-id) option to install a different git revision of a project from the one currently checked out. If this option is not used, the git revision for the specified package-ID defaults to the git revision of the OpenCPI framework repository.
-p <package-id>, --package-id=<package-id>: Specifies the OpenCPI package-ID of the project that provides the support for the platform. This option is only required when support for the platform is provided in an OSP (OpenCPI System support Project) instead of in a built-in OpenCPI project. The default format for a package-ID is <package-prefix>.<package-name>; for example, ocpi.osp.e3xx, ocpi.osp.plutosdr. See the chapter on package-IDs in the OpenCPI Component Development Guide for details.
-u <url>, --url=<url>: Specifies the internet URL where the project resides. This option can be used with the -p (--package-id) option (described above) to specify the location of a project that is not hosted on the OpenCPI Gitlab site. If this option is not used, the URL defaults to https://gitlab.com/opencpi/osps/<package-id>.git, where <package-id> is the one specified in the --package-id= option. For example, if <package-id> is ocpi.osp.e3xx, the URL is https://gitlab.com/opencpi/osps/ocpi.osps.e3xx.git.
--minimal: Specifies a minimized installation process that does not pre-build HDL workers or run any installation tests.
--artifacts-only: Cleans intermediate build files when building workers and assemblies, keeps only artifacts required for building at the next level or deploying onto hardware.
--no-kernel: Specifies to skip building the OpenCPI Linux kernel device driver when the OpenCPI framework is built for the platform. Use this option when secure boot is required for the system or the driver is otherwise not required.
--optimize: For RCC (software) platforms only, specifies that the framework software and software workers should be built with optimization enabled. If this option is not used, the default is to build with optimization disabled, which is perhaps better suited for debugging.

The following options can be specified for the install verb plus tool noun only.

-d <DIR>, --directory=<DIR>: Specifies the installation directory for the tool. The default installation directory depends on the tool.
--installer-file=<IFILE>: If required to install a particular tool, this is an installation program or bundle downloaded from (or otherwise provided by) the third-party/vendor. There is no default value.
--tool-options="[ARG]…": These are options to pass to the tool installer script. There is no default value. Double-quotes around the value are required to ensure proper parsing. Legal ARGs (typically specified to override the default tool installation parameters) are defined by the tool installation script (use --tool-options="--help" to see them) and are space-separated.

OPERATIONS

The command syntax for the install platform operation is:

ocpiadmin <options> install platform <platform>

where <platform> is the name of an RCC platform, HDL platform or HDL simulator to be built for OpenCPI. If necessary, the operation downloads the platform’s OSP into the projects/osps/ directory in the OpenCPI installation directory and then builds the built-in projects and the platform’s OSP (if any) for the specified platform. If the specified platform is an HDL platform, the operation also builds a single test artifact/bitstream: the testbias assembly in the assets project. After the operation is performed, any asset in any project can be built for the specified platform.

The command syntax for the install tool operation is:

ocpiadmin <options> install tool <name>

where <name> is the name of the third-party/vendor tool to be installed. Currently, the only valid value for <name> is "vivado": see EXAMPLES below for more info.

The command syntax for the deploy platform operation is:

ocpiadmin deploy platform <rcc-platform> <hdl-platform>

where <rcc-platform> and <hdl-platform> are the names of the software (RCC) and hardware/FPGA (HDL) platforms for which the bootable media should be created. The operation creates the directory cdk/<hdl-platform>/sdcard-<rcc-platform>, whose contents can be copied to an SD card.

Keywords for specifying platform names are given in tables in the OpenCPI Installation Guide.

EXAMPLES

Build a minimal Xilinx Xsim (xsim) HDL simulator platform for OpenCPI:
```
ocpiadmin --minimal install platform xsim
```
Download and build the Ettus USRP E310 (e31x) HDL platform for OpenCPI:
```
 ocpiadmin  --package-id=ocpi.osp.e3xx install platform e31x
```
Download and build an optimized version of the Analog Devices Pluto Linux 0.38 (adi_plutosdr0_38) embedded software (RCC) platform for OpenCPI:
```
ocpiadmin --package-id=ocpi.osp.plutosdr --optimize install platform adi_plutosdr0_38
```
Build the Analog Devices ADALM-PLUTO (plutosdr) platform (you have already downloaded the OSP that supports this platform if you performed the previous example):
```
ocpiadmin install platform plutosdr
```
Download the third-party OSP that provides the myplat platform from the Github site and build the platform:
```
ocpiadmin --package-id=com.myco.myplat --url=https://github.com/myco/myplat.git install platform myplat
```
Download and build the latest "development" git revision of the plutosdr platform from a working branch using an earlier version:
```
ocpiadmin --package-id=ocpi.osp.plutosdr --git-revision=develop install platform plutosdr
```

Install the Xilinx Vivado tool using default installation parameters:

ocpiadmin --installer-file=FPGAs_AdaptiveSoCs_Unified_2024.1_0522_2023_Lin64.bin install tool vivado

Print the "vivado" installer script "help/usage" information and exit:

ocpiadmin --installer-file=FPGAs_AdaptiveSoCs_Unified_2024.1_0522_2023_Lin64.bin --tool-options="--help" install tool vivado

Create a bootable media directory tree for booting the RCC platform xilinx24_1_aarch32 on the HDL platform zed. This operation creates the directory cdk/zed/sdcard-xilinx24_1_aarch32/, whose contents can be copied to an SD card:
```
ocpiadmin deploy platform xilinx24_1_aarch32 zed
```

BUGS

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

RESOURCES

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 Installation Guide: https://opencpi.gitlab.io/releases/latest/docs/OpenCPI_Installation_Guide.pdf

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.