ocpirun

Name

ocpirun — command-line tool for running OpenCPI applications

Synopsis

ocpirun [<options>] <application-name>

DESCRIPTION

The ocpirun(1) command-line tool is used to execute OpenCPI component-based applications in OpenCPI containers on OpenCPI platforms. An OpenCPI application is defined as an assembly of component instances with connections among them. An OpenCPI application can be specified in two different ways:

As a standalone XML file called an OpenCPI Application Specification (OAS)
As an XML document embedded in and manipulated by a C++ program using the OpenCPI Application Control Interface (ACI)

The ocpirun tool directly executes the applications defined in OAS XML files. The argument <application-name> is the name of an OAS file without the .xml extension. The ocpirun tool reads the OAS associated with the named application and then runs it.

Execution ends when the application described in the OAS is "done" or a time duration (set with an option to ocpirun) is exceeded. An application is done when all its workers indicate that they are "done" or when a single worker identified with the done XML attribute in the OAS indicates that it is "done".

The ocpirun tool runs applications in OpenCPI projects, which are development work areas for groups of assets like components and applications.

When ocpirun executes an application, it makes deployment decisions that determine, for each component instance in the application:

which worker in which compiled artifact should be used
which container the worker should run in

The ocpirun tool uses an automatic built-in algorithm to make these decisions that can be guided or overridden by using specific options.

Options to ocpirun are either single letters following one hyphen or complete words or acronyms following two hyphens and separated by hyphens. For convenience, options can occur anywhere in the command. The ocpirun command supports the following option categories:

General-purpose options
Function options, which direct the command to perform functions other than executing the application.
Instance options, which allow a value to be specified that applies to all instances in the application or to a single instance in the application. Instance options typically provide constraints on the ocpirun deployment algorithm to consider only certain workers or certain containers.
Instance port options, which apply to specific ports of instances in the application and modify the default behavior of communications occurring at that port. When a port is connected to a port of another instance, the connection is between two ports. Some instance port options apply only to one end (one port) of the connection, while others apply to the connection as a whole and thus to both the specified port and the port to which it is connected.
External port options, which apply to the external ports of the application (which are not connected to anything else in the OAS).
Simulation options, which control containers running HDL (FPGA) simulators and are used during HDL component development and testing. The OpenCPI HDL Development Guide provides more information on simulators.

Some of these options can also be expressed as XML attributes in the application OAS and some can be used in applications that use the Application Control Interface (ACI). See the "Options Summary" section in the OpenCPI Application Development Guide for information on how to invoke these options with ocpirun, as OAS XML attributes and for ACI.

When invoked without any options and arguments, ocpirun displays help information.

The OpenCPI Application Development Guide describes the XML structure of an application OAS and describes OpenCPI application development and execution in detail.

OPTIONS

In addition to the general-purpose options common to all OpenCPI tools (see opencpi(1)), the options described below can be specified for ocpirun operations. 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.

General Options

-M, --dump-platforms: Write all platform worker and HDL device worker properties in addition to properties of the workers in the application to stderr before starting the application and when it is done.
-O <seconds>, --timeout=<seconds>: Specify the number of seconds after which the application is stopped and considered to have failed (the ocpirun exit code is 1.)
-R, --remote: Automatically discover servers that offer remote containers using multicast User Data Protocol (UDP). See the OpenCPI Application Development Guide for information on using ocpirun with remote containers.
-S <name-or-IP-address>, --server=<name-or-IP-address>+: Specify the server name or IP address to be explicitly contacted for remote containers whether or not the --remote (-R) option is specified. See the OpenCPI Application Development Guide for information on using ocpirun with remote containers.
-U, --uncached: When dumping property values, do not use values cached by ocpirun when they are written. Instead, query the worker in its execution environment (which is much more expensive).
-d, --dump: Write property values to stderr before starting the application and after it is done.
-n <number-of-RCC-containers>, --processors=<number-of-RCC-containers>: Specify the number of RCC containers to create. The default is 1.
-t <seconds>, --duration=<seconds>: Specify the number of seconds after which execution should stop. If the application is not done before <seconds> is reached, the application stops and is considered to have executed successfully (the ocpirun exit code is zero).
--component: Specify that the first command argument that is not an option is a component name for a single-component application rather than the filename of an OAS.
--deployment=<file>: Specify a filename to read for deployment decisions rather than using the built-in deployment algorithm. See the deploy-out option.
--deploy-out=<file>: Specify the filename in which to record deployment decisions for this execution, in XML format, that can be used for execution later on with the --deployment option. The file generated with this option can contain the exact deployment recorded from a previous run or from a run that is executed with the no-execute option.
--dump-file=<file>: Specify the file in which to record the final property values in machine-parseable form.
--hex: Output numeric property values in hex, not decimal.
--library-path=<library>: Override the OCPI_LIBRARY_PATH environment variable with the specified library.
--no-execute: Specify that all deployment decisions should be made but the application should not be executed. This option can be used with the --deploy-out option to write the deployment decisions to a file.

Function Options

-A, --list-artifacts: Search for all artifacts for the targets or platforms specified with the -r (--target) option, based on OCPI_LIBRARY_PATH, and then write the resulting list to stdout. Use this function to collect artifacts for a specific system.
-C, --list: List all available containers, including those discovered on the network if the -R (-remote) or -S (--server) options are specified. The option assigns each container a number for easy specification with the -c (--container) option and returns it as output along with the authoring model, platform name, operating system and version, architecture and container name. Note that the application is still executed if an application filename argument is specified after the options.
-r <target>, --target=<target>+: Use with the --list-artifacts and --list-specs options to limit the list to the specified architecture. Specify the target in the format <os>-<os-version>-<arch>; for example, linux-c7-x86_64.
--list-specs: Search for all specs for the targets or platforms specified with the --target (-r) option, based on OCPI_LIBRARY_PATH, and then print the resulting list to stdout. Use this function to collect available specs for a specific system.
--no-execute: For each instance, determine the container on which it will run and the artifact to be used to run it without actually allocating any resources for performing the execution. Use this option with the --deploy-out option to execute a "dry run" of an application to see the results and record the deployment decisions in an XML file that can then be used with the --deployment option.
--only-platforms: Use with the -C (--list) option to direct it to output only the available platforms, listing any available platform only once even if there is more than one container with the same platform type.

Instance Options

Instance options allow a value to be specified that applies to either all instances or just one instance. These options take string values of the form:

[<instance-name>]=<value>

So, the option -m=rcc would set the m option (the authoring model) for all instances to rcc, while the option -mctl=rcc would set the m option for the ctl instance to be rcc. These options can appear more than once to indicate options for different instances. If you specify an instance with an empty value (e.g. -mctl= ), it unsets any previous default (such as -m=rcc). So the following example would say: all instances have the rcc model except filter.

-m=rcc -mfilter=

These options can provide constraints on the deployment algorithm to only consider certain workers or certain containers.

-P[<instance-name>]=<platform-type>, --platform[=<instance-name>=]=<platform-type>+: Assign the named instance or all instances only to available containers for the specified platform type. Examples: -Pfft=picoevb, --platform=rocky9. Use the -C (--list) option to determine the available containers and platform types.
-c[<instance-name>]=<container>, --container[=<instance-name>]=<container>+: Assign the named instance or all instances to the specified container using the container name or number returned by the -C (--list) option. Examples: -cfft=1, -cfir=rcc2, --container=fft=1, --container=rcc2, -c=1, --container fft=1.
-m[<instance-name>]=<authoring-model>, --model[=<instance-name>]=<authoring-model>+: Specify the authoring model of the named instance or all instances so that the worker used for the instance/all instances must have this model. The value of <authoring-model> is hdl or rcc. Examples: -mfft=hdl, -m=hdl, --model=rcc, --model=fir=hdl, --model fir=hdl.
-p[<instance-name>]=<property-name>=<value>, --property[=<instance-name>]=<property-name>=<value>+: Set the value of a property. Specify the instance name for per-instance property value settings. Omit the instance name for application-level property value settings. See the OpenCPI Application Development Guide for detailed information on specifying property values.
-s[<instance-name>]=<expression>, --selection[=<instance-name>]=<expression>: Set the selection expression for a single instance or all instances. See the description of the selection OAS XML attribute in the OpenCPI Application Development Guide for details.
-w[<instance-name>]=<worker-name>, --worker=<instance-name>=<worker-name>: Specify the name of the worker (specific implementation) to be used for the instance. Do not include the authoring model suffix or the package prefix in <worker-name>. Examples: --worker=mycomp2=worker3, --worker mycomp2=worker3, -wmycomp2=worker3.

Instance Port Options

Instance port options allow a value to be specified that applies to a port of an instance. These options take string values of the form:

<instance-name>=<port-name>=<value>

When a port is connected to a port of another instance, the connection is between two ports. Some of the port options apply to only one end (one port) of the connection, while others apply to the connection as a whole and thus apply to both the mentioned port as well as the port it is connected to.

-B<instance-name>=<port-name>=<value>, --buffer-count=<instance-name>=<port-name>=<value>+: Specify the number of buffers at this instance port, not for all the ports in the connection. The default is usually 2. Use this option to allow the number of buffers to be different on each end of the connection.
-T<instance-name>=<port-name>=<identifier>, --transport=<instance-name>=<port-name>=<identifier>+: Specify the transport technology to use for the connection (the specified port and the port to which it is connected). This option applies when using remote containers. See the description of the transport attribute of a connection element in the OpenCPI Application Development Guide for the list of identifiers that correspond to the transport technologies supported by OpenCPI.
-Z<instance-name>=<port-name>=<value>, --buffer-size=<instance-name>=<port-name>=<value>+: Specify the buffer size for the connection (the specified port and the port to which it is connected). The default is usually determined by a combination of the protocol used on the connection and other system constraints. The buffer size is always the same for both ends of a connection, so specifying it for one port also specifies it for the other port.

External Port Options

-B <port-name>=<value>, --buffer-count=<external-port-name>=<value>+: Specify the number of buffers for the specified external port.
-T <external-port-name>=<identifier>, --transport=<external-port-name>=<identifier>+: Specify the transport technology used for the connection (for this port and the port to which it is connected). This option applies when using remote containers. See the description of the transport attribute of a connection element in the OpenCPI Application Development Guide for the list of identifiers that correspond to the transport technologies supported by OpenCPI.
-Z <external-port-name>=<value>, --buffer-size=<external-port-name>=<value>+: Specify the the buffer size for the specified external port and the port inside the OAS to which it is connected. The default is usually determined by a combination of the protocol used on the connection and other system constraints.
-f <external-port-name>=<file-name>, --file=<external-port-name>=<file-name>+: Specify the file to be connected to the specified external port. Use this option to insert a file_read or file_write utility component into the application and connect it to the specified external port. It allows an OAS with external ports to be connected to files while also allowing it to be used with those same ports connected to an ACI application. See the description of the utility components and ACI applications in the OpenCPI Application Development Guide for details.

When the above file option is used to connect an external port to a file, the detailed property settings for the inserted file_read or file_write components may be supplied after the filename using the URL option syntax of:

?<name>=<value>;<name2>=<value>

So if an external port whose name was input was to be connected to the file myinput.txt, with the opcode option set to 2 and the suppressEOF option set to false, the option syntax would be:

-f "input=myinput.txt?opcode=2;suppressEOF=false"

Note that the option value is quoted since the question mark and semicolon are shell metacharacters.

Simulation Options

--sim_dir=<directory>: Specify the name of a directory where simulation outputs will be placed. The default directory is simulations/ relative to where ocpirun is running.
--sim-ticks=<value>: The number of simulation clock cycles to execute or until the application is done.

The section "Execution of Simulation Bitstreams and Containers" in the OpenCPI HDL Development Guide provides more information about running applications on HDL (FPGA) simulators. See ocpiview(1) for information on viewing the results of simulation runs.

ENVIRONMENT VARIABLES

The following environment variables affect ocpirun operation:

OCPI_LIBRARY_PATH: A list of directories, separated by colons, to be searched for runtime artifacts. When referencing the artifacts exported by a project with sources, be sure to reference the project’s exports/ subdirectory, not its source location. This variable is set automatically (if not already set) when running component unit tests or applications in projects with ocpidev run. In pure runtime environments, it may need to be set when artifacts are placed in directories of the user’s choice.
OCPI_ENABLE_REMOTE_DISCOVERY: Whether (set to 1) or not (set to 0) multicast User Datagram Protocol (UDP) discovery of remote systems running ocpiserve is enabled.
OCPI_SOCKET_INTERFACE: The name of the network interface (from the list of network interfaces returned by the Linux ifconfig or ip addr command) to be used for contacting remote systems running ocpiserve container servers. Set this variable to the interface with the same network address (IP address anded with the netmask) as the container servers being used.

EXAMPLES

Inside a project, run the application described by the OAS named myapp.xml. The command locates and reads the application OAS and runs the application:
```
ocpirun myapp
```
Inside a project, run the application described by the OAS named myapp.xml, displaying information about what is happening, dumping the property values after initialization, and limiting execution time to 10 seconds:
```
ocpirun -v -d -t=10 myapp
```
Inside a project, run the application described by the OAS named myapp.xml, specifying that all application instances must use the RCC authoring model:
```
ocpirun -m=rcc myapp
```
Inside a project, run the application described by the OAS named myapp.xml, specifying that the ctl instance in the application must use the RCC authoring model:
```
ocpirun -mctl=rcc myapp
```
Inside a project, run the application described by the OAS named myapp.xml, specifying that all the instances in the application except for the filter instance must use the RCC authoring model. Specifying the -m option with an empty value for filter unsets the previous setting for it made with the -m=rcc option:
```
ocpirun -m=rcc -mfilter= myapp
```
Inside a project, specify that all instances in the application described by the OAS named myapp.xml should be run only on the picoevb HDL (FPGA) platform:
```
ocpirun -P=picoevb myapp
```
Inside a project, specify that the instance mycomp in the application described by the OAS named myapp should be run only on the xsim HDL (FPGA) simulator platform:
```
ocpirun -Pmycomp=xsim myapp
```
Inside a project, run the application described by the OAS named myapp.xml, setting the top-level application property named control to 5:
```
ocpirun -p=control=5 myapp
```
Inside a project, run the application described by the OAS named myapp.xml, setting the filename property value of the file_read instance to the file myinput.data:
```
ocpirun -p=file_read=filename=myinput.data myapp
```
Inside a project, run the application described by the OAS named myapp.xml, connecting the external port named input to the file myinput.txt and setting the inserted file_read properties opcode to 2 and suppressEOF to false. Enclose the option value in quotes because the question mark and the semicolon are shell metacharacters:
```
ocpirun -f 'input=myinput.txt?opcode=2;suppressEOF=false' myapp
```

On a CentOS7 system with modelsim and isim HDL (FPGA) simulators installed for OpenCPI, list the available platforms:

ocpirun -C

The output from the command is:

Available containers:
   #  Model Platform   OS    OS-Version   Arch   Name
   0  hdl   isim                                 lsim:isim
   1  hdl   modelsim                             lsim:modelsim
   2  rcc   rocky9     linux r9           x86_64 rcc0

Inside a project, run the application described by the OAS named myapp.xml, using for the ctl instance only those workers whose snr property is less than 5:
```
ocpirun -sctl=snr<5 myapp
```

BUGS

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

RESOURCES

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

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

See the OpenCPI HDL Development Guide: https://opencpi.gitlab.io/releases/latest/docs/OpenCPI_HDL_Development_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.