ocpirun — command-line tool for running OpenCPI applications
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:
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:
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.
Options can occur anywhere in the command for the user’s convenience.
The ocpirun command supports the following option categories:
ocpirun deployment algorithm to
consider only certain workers or certain containers.
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 arguments, ocpirun displays information
about all of its options.
The OpenCPI Application Development Guide describes the XML structure of an application OAS and describes OpenCPI application development and execution in detail.
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.
--component
--deploy-out=<file>
--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.
--deployment=<file>
deploy-out option.
--dump, -d
stderr before starting the
application and after it is done.
--dump-file=<file>
--dump-platforms, -M
stderr before starting the application and when it is done.
--duration=<seconds>, -t <seconds>
--hex
--library-path=<library>
--log-level=<level>, -l <level>
--no-execute
--deploy-out option to write
the deployment decisions to a file.
--processors=<number-of-RCC-containers>, -n <number-of-RCC-containers>
--remote, -R
ocpirun with remote containers.
--server=<name-or-IP-address>, -S <name-or-IP-address>+
--remote (-R) option is
specified. See the OpenCPI Application Development Guide for
information on using ocpirun with remote containers.
--timeout=<seconds>, -O <seconds>
ocpirun exit
code is 1.)
--uncached, -U
ocpirun when they are written. Instead, query the
worker in its execution environment (which is much
more expensive).
--verbose, -v
--list, -C
-remote (-R) or --server (-S)
options are specified. The option assigns each container a number
for easy specification with the --container (-c) 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.
--list-artifacts, -A
--target (-r) option, based on
OCPI_LIBRARY_PATH, and then write the resulting list to
stdout. Use this function to collect artifacts
for a specific system.
--list-specs
--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
--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
--list (-C) 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.
--target=<target>, -r <target>+
--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.
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.
--container[=<instance-name>]=<container>, -c[<instance-name>]=<container>+
--list (-C) option.
Examples: -cfft=1, -cfir=rcc2, --container=fft=1,
--container=rcc2, -c=1, --container fft=1.
--model[=<instance-name>]=<authoring-model>, -m[<instance-name>]=<authoring-model>+
hdl or rcc.
Examples: -mfft=hdl, -m=hdl, --model=rcc, --model=fir=hdl, --model fir=hdl.
--platform[=<instance-name>=]=<platform-type>, -P[<instance-name>]=<platform-type>+
--list (-C) option to determine the
available containers and platform types.
--property[=<instance-name>]=<property-name>=<value>, -p[<instance-name>]=<property-name>=<value>+
--selection[=<instance-name>]=<expression>, -s[<instance-name>]=<expression>
selection OAS XML attribute in the
OpenCPI Application Development Guide for details.
--worker=<instance-name>=<worker-name>, -w[<instance-name>]=<worker-name>
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.
--buffer-count=<instance-name>=<port-name>=<value>, -B<instance-name>=<port-name>=<value>+
--buffer-size=<instance-name>=<port-name>=<value>, -Z<instance-name>=<port-name>=<value>+
--transport=<instance-name>=<port-name>=<identifier>, -T<instance-name>=<port-name>=<identifier>+
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.
--buffer-count=<external-port-name>=<value>, -B <port-name>=<value>+
--buffer-size=<external-port-name>=<value>, -Z <external-port-name>=<value>+
--file=<external-port-name>=<file-name>, -f <external-port-name>=<file-name>+
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.
--transport=<external-port-name>=<identifier>, -T <external-port-name>=<identifier>+
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.
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.
--sim_dir=<directory>
simulations/
relative to where ocpirun is running.
--sim-ticks=<value>
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.
The following environment variables affect ocpirun operation:
OCPI_LIBRARY_PATH
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
1) or not (set to 0) multicast User Datagram
Protocol (UDP) discovery of remote systems running ocpiserve is enabled.
OCPI_SOCKET_INTERFACE
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.
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 --verbose --dump --duration=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 --model=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 -model=ctl=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 --model option with an empty
value for filter unsets the previous
setting for it made with the --model=rcc option:
ocpirun --model=rcc --model=filter= myapp
Inside a project, specify that all instances
in the application described by the OAS named
myapp.xml should be run only on the ml605 HDL (FPGA) platform:
ocpirun --platform=ml605 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 --platform=mycomp=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 --property 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 --property 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 --file '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 --list
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 centos7 linux c7 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 --selection=ctl=snr<5 myapp