ocpiremote — command-line tool for remotely managing an OpenCPI container server
The ocpiremote(1) command-line tool enables a local system
to load, start, and control a remote system, enabling it to act as an OpenCPI container server.
The target remote system requires network login via the Secure Shell (SSH),
the bash shell and the tar command. It must be running an OpenCPI-supported software
(RCC) platform. No additional installation is necessary since ocpiremote loads
OpenCPI software as needed.
The ocpiremote tool loads an ocpiserve executable
"package" over an SSH connection into a "sandbox" directory
(by default, ~/sandbox) on the remote system
and can subsequently be used to start it. When started, ocpiserve
makes its local containers available to any and
all remote clients through the network interfaces
on the remote system. See the ocpiserve(1)
tool for details. The ocpiremote tool manages the container server
in the sandbox directory without affecting the rest of the remote system’s
installation or configuration, providing a convenient way to set up and operate
container servers remotely.
The ocpiremote tool is part of OpenCPI’s
remote containers feature, which adds containers
available in other (remote) systems on the network to the set
of containers considered when applications are executed on the local system.
See the chapter "Using Remote Containers: Network-Connected Processors"
in the OpenCPI Application Development Guide for information
on how to set up and use this feature.
For convenience, options can occur anywhere in the command.
The general usage concept is: perform the <verb> operation on the
<noun> asset type whose name is <name>.
When invoked without any verbs and options, ocpiremote displays help information.
The ocpiremote command performs operations on the remote system
whose IP address and TCP port are listed first in
the OCPI_SERVER_ADDRESSES environment variable or whose
IP address and (optional) TCP port are specified as options
on the command line.
The verbs supported by ocpiremote are:
deploy
--remote-dir option is used to specify the location of the boot directory
on the remote system. If --remote-dir is not specified, the boot directory will be
determined heuristically, based on where a previous deploy operation was done.
load
ocpiserve container server package in that directory. That package
contains all necessary files to run ocpiserve.
log
ocpiserve container server logging. If the server is not running,
the log is displayed and the command finishes. If the server is running the log is displayed
continuously while the server is running, similar to the -f option to the tail command.
reboot
deploy operation.
reload
ocpiserve container server sandbox directory and then reload it.
restart
ocpiserve container server on a remote system.
start
ocpiserve container server on a remote system, which includes reloading
any required kernel drivers and FPGA bitstreams (when the --bitstream option is specified).
status
ocpiserve container server on a remote system.
stop
ocpiserve container server on a remote system.
test
ocpiserve container server on a remote system.
unload
None of these verbs take any arguments.
In addition to the general-purpose options common
to all OpenCPI tools (see opencpi(1)),
the options described below can be specified for ocpiremote operations.
In the following descriptions, 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.
These common options can be placed before the verb or after it.
-c <options>, --scp-opts=<options>
-d <directory-name>, --remote-dir=<directory-name>
deploy verb, this specifies the name of a directory on the
target remote system in which to create and use a container server sandbox.
If this option is not used, the default directory
name sandbox is created in the home directory
of the specified user.
With the deploy verb this specifies where the boot files are placed, and has no default.
-i <ip-address>, --ip-addr=<ip-address>
OCPI_SERVER_ADDRESSES environment variable is used.
-p <password>, --password=<password>
root.
-o <options>, --ssh-opts=<options>
-u <username>, --user=<username>
root.
-r <tcp-port-number>, --port=<tcp-port-number>
OCPI_SERVER_ADDRESSES environment variable is used.
--hdl-platform=<HDL-platform-identifier>
zed. See the OpenCPI User Guide
for the possible identifiers for OpenCPI HDL platforms.
--optimize
ocpiadmin or ocpidev commands
with this same option.
If this option is not
used, the default is to use the unoptimized software perhaps better suited for debugging.
--rcc-platform=<RCC-platform-identifier>
xilinx19_2_aarch32. See the OpenCPI User Guide
for the possible identifiers for OpenCPI RCC platforms.
--valgrind
ocpiserve under the valgrind tool be included in the
ocpiserve package. This requires that valgrind has been built as an OpenCPI prerequisite for the
remote RCC software platform.
--remote-dir=<directory-name>
--hdl-platform and --rcc-platform as described above.
-b, --bitstream
-e<value>, --environment=<value>
ocpiserve when it is started.
-l<value>, --log-level=<value>
OCPI_LOG_LEVEL environment
variable in the OpenCPI User Guide for a description
of possible values. Using this option overrides the
level set in the OCPI_LOG_LEVEL environment variable.
The default log level is 0 (no logging).
-m<value>, --memory=<value>
ocpiserve is running.
The value may be decimal, octal or hex (using 0x). I.e. 0x400000 is 4 megabytes.
--valgrind
ocpiserve should be run under the valgrind tool.
This requires that the same option was specified when the load or reload verb was used.
The valgrind output will be in the log.
The following OpenCPI environment variables affect ocpiremote execution:
OCPI_SERVER_ADDRESSES
:<tcp-port>[:<ocpiremote-args>]. For example,
192.168.1.102:12345 or 192.168.1.102:12345:-p analog -b. When ocpiserve with the --verbose
option is started, it prints its IP addresses/TCP ports in the log.
OCPI_SERVER_ADDRESSES_FILE
:<tcp-port>[:<ocpiremote-args>]. For example,
192.168.1.102:12345.
The chapter "Using Remote Containers: Network-Connected Processors" in the OpenCPI Application Development Guide provides more information about when to use these environment variables and why.
Load an ocpiserve container server on the remote system
with IP address 192.168.1.102. The operation creates the
container server executable in the directory ~/sandbox
ocpiremote --ip-addr=192.168.1.102 load
Load and start an ocpiserve container server
on a remote Ettus E310 system with IP address 192.168.1.102 and TCP port 12345,
specified with the OCPI_SERVER_ADDRESSES environment variable to apply them to all subsequent ocpiremote commands.
Before starting the server, establish 4 megabytes of DMA memory, and load an OpenCPI bitstream
on top of whatever is currently loaded. Since the required RCC platform is not specified as
an option to the load verb, it defaults to xilinx19_2_aarch32, which is the desired
RCC platform for the E310.
export OCPI_SERVER_ADDRESSES=192.168.1.102:12345 ocpiremote --hdl-platform=e31x load ocpiremote --bitstream --memory 0x400000 start
Load and start an ocpiserve container server
on a remote ADALM-PLUTO system with IP address 192.168.1.2 and TCP port 12345,
specified with the OCPI_SERVER_ADDRESSES environment variable to apply them to all subsequent ocpiremote commands.
Supply the server login password as an option to the load and start verbs.
export OCPI_SERVER_ADDRESSES=192.168.2.1:12345 ocpiremote --rcc-platform=adi_plutosdr0_32 --hdl-platform=plutosdr --password=analog load ocpiremote --password=analog start
Stop the ocpiserve container server on the remote system
with IP address 192.168.1.102:
ocpiremote --ip-addr=192.168.1.102 stop
Observe logging on the ocpiserve container server
on the remote system with IP address 192.168.1.102:
ocpiremote --ip-addr=192.168.1.102 log
Load an ocpiserve container server into the ~/myserver/
directory on the remote system listed
first in the OCPI_SERVER_ADDRESSES environment variable:
ocpiremote --remote-dir=myserver load
Delete and then load an ocpiserve container server
on the remote system with the IP address 192.168.1.102
and the TCP port 9233:
ocpiremote --ip-addr=192.168.1.102 --port=9233 reload
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 User Guide: https://opencpi.gitlab.io/releases/latest/docs/OpenCPI_User_Guide.pdf