ocpirun

Description

The ocpirun 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.

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.

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.
OCPI_TRANSFER_PORT: The number to assign the socket port to be used for contacting remote systems running ocpiserve container servers. This can be used in combination with firewall rules to run ocpirun with an enabled firewall by opening the port used here in the system firewall, such as firewalld or ufw.

Usage

$ ocpirun
Usage for ocpirun (executed from /home/user/opencpi/build/autotools/target-rocky9/staging/bin/ocpirun):
Options are:
  Long name       Letter  Datatype  Multiple? Description
  dump              d       Bool       No    dump properties after execution.
  verbose           v       Bool       No    be verbose in describing what is happening.
  hex               x       Bool       No    print numeric property values in hex, not decimal.
  hidden            H       Bool       No    print hidden property values.
  selection         s       String     Yes   <instance-name>=<expression>.
                                             provide selection expression for worker instance
  model             m       String     Yes   [<instance-name>]=<model>.
                                             set model (rcc, hdl, ocl, etc.) for worker instance
  property          p       String     Yes   [<instance-name>]=<property>=<value>.
                                             set a property value of a worker instance
  container         c       String     Yes   [<instance-name>]=<container-name>].
                                             assign instance to container (name or number from -C)
  platform          P       String     Yes   [<instance-name>]=<platform-name>.
                                             assign instance to any container of this platform type
  scale             N       String     Yes   <instance-name>=<crew-size>.
                                             set scale factor for scalable worker
  worker            w       String     Yes   <instance-name>=<implementation-name>.
                                             choose a particular worker name
  processors        n       ULong      No    Number of RCC containers to create.
  file              f       String     Yes   <external-name>=<file-name>.
                                             connect external port to a specific file
  device            D       String     Yes   <instance-name>=<device-name>.
                                             assign instance to a specific device
  url               u       String     Yes   <external-name>=<URL>.
                                             connect external port to a URL
  log-level         l       ULong      No    <log-level>.
                                             set log level, overriding OCPI_LOG_LEVEL
  duration          t       Long       No    <seconds>.
                                             duration (seconds) to run the application if not done
                                             first; exit status is zero in either case
  timeout           O       ULong      No    <seconds>.
                                             time limit (seconds) to run the application; if not
                                             done/finished before that time; an error occurs
  list              C       Bool       No    show available containers.
                                             can be used with no xml file argument - no execution
  server            S       String     Yes   a server to explicitly contact, without UDP discovery.
  remote            R       Bool       No    discover/include/use remote containers.
  transport         T       String     Yes   <instance-name>=<port-name>=<transport-name>.
                                             set transport of connection at a port
  transfer-role     <none>  String     Yes   <instance-name>=<port-name>=<transfer-role>.
                                             set transfer role at a port
  buffer-count      B       String     Yes   <instance-name>=<port-name>=<buffercount>.
                                             set buffercount at a port
  buffer-size       Z       String     Yes   <instance-name>=<port-name>=<buffersize>.
                                             set buffer size at a port
  target            r       String     Yes   a target when printing artifacts/specs in path.
  list-artifacts    <none>  Bool       No    print artifacts in path, for specified targets.
  list-specs        <none>  Bool       No    print specs in path, for specified targets.
  uncached          U       Bool       No    dump cached properties uncached, ignoring cache.
  deployment        <none>  String     No    XML file to read deployment from, to avoid automatic.
                                             deployment process
  deploy-out        <none>  String     No    XML file to write deployment to.
  no-execute        <none>  Bool       No    Suppress execution, just determine deployment.
  library-path      <none>  String     No    Search path for executable artifacts, overriding.
                                             the OCPI_LIBRARY_PATH environment variable
  default-package   <none>  String     No    The package used for components without package prefixes.
  sim-dir           <none>  String     No    Directory in which simulations are run.
                                               Default: simulations
  dump-platforms    M       Bool       No    dump platform and device worker properties.
  sim-ticks         <none>  ULong      No    simulator clock cycles to allow.
  artifacts         A       String     No    deprecated: comma-separated targets for artifacts.
  specs             G       String     No    deprecated: comma-separated targets for specs.
  only-platforms    <none>  Bool       No    modifies the list command to show only platforms.
  dump-file         <none>  String     No    dump properties in raw parsable format to this file.
  component         <none>  Bool       No    first non-option argument is a component name,.
                                             not an application XML file
  seconds           <none>  Long       No    <seconds> -- legacy, use "duration" now.
  version           <none>  Bool       No    print the OpenCPI release version.
Long options are of the form:   --<long-name>[=<value>]
Short options are of the form:  -<letter>[<value>] or -<letter>  <value>
Boolean options have no value; their presence indicates 'true'.  Other types require values.

Usage is: ocpirun <options>... [<application-xml-file>]

Examples

Run the application described by the OAS named myapp.xml. The command locates and reads the application OAS and runs the application:
```
ocpirun myapp
```
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
```
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
```
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
```
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:
```
ocpirun -m=rcc -mfilter= myapp
```
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
```
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
```
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
```
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
```
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
```

List the available platforms on a CentOS7 system with modelsim and isim HDL (FPGA) simulators installed for OpenCPI:

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

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
```