Name

ocpiremote — command-line tool for remotely managing an OpenCPI container server

Synopsis

ocpiremote [<options>] [<verb> [<options>]]

DESCRIPTION

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.

VERBS

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
Copy an OpenCPI bootable media directory tree (also called a "deployment package" or "SD card contents") to the remote system (usually to a directory on an SD card inserted into that system) and reboot it. See the ocpiadmin(1) tool for more information about creating bootable media directory trees for embedded systems. This operation is not needed if the boot files are already suitable: it is normally used to change operation system versions. This operation does not load OpenCPI files onto the remote system, just boot-up files to get the OS running. The --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
Create a sandbox directory on the remote system and then place an ocpiserve container server package in that directory. That package contains all necessary files to run ocpiserve.
log
Interactively view 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
Reboot the remote system, usually used after the deploy operation.
reload
Delete an ocpiserve container server sandbox directory and then reload it.
restart
Stop and then start an ocpiserve container server on a remote system.
start
Start an ocpiserve container server on a remote system, which includes reloading any required kernel drivers and FPGA bitstreams (when the --bitstream-- is specified.
status
Get the status of an ocpiserve container server on a remote system.
stop
Stop an ocpiserve container server on a remote system.
test
Test the basic connectivity between the local system and an ocpiserve container server on a remote system.
unload
Delete a container server sandbox directory.

None of these verbs take any arguments.

OPTIONS

Options Common to All Operations on a Container Server or Remote System

These common options can be placed before the verb or after it.

--ip-addr=<ip-address>, -i <ip-address>
Specify the IP address of the target remote system. If this option is not specified, the first IP address in the OCPI_SERVER_ADDRESSES environment variable is used.
--password=<password>, -p <password>
Specify the password associated with the username used for login to the target remote system. The default password is root.
--remote-dir=<directory-name>, -d <directory-name>
Except for the 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.
--ssh-opts=<options>, -o <options>
Specify the SSH options for connecting to the target remote system. If this option is not used, the default SSH options automatically accept host keys without notification and suppress most warning and diagnostic messages.
--scp-opts=<options>, -c <options>
Specify the SCP options for connecting to the target remote system. If this option is not used, the default SCP options accept host keys without notification and suppress most warning and diagnostic messages.
--user=<username>, -u <username>
Specify the username used for login to the target remote system. The default username is root.
--verbose, -v
Be verbose, printing additional information during command execution.

Options When Loading or Reloading a Container Server

--hdl-platform=<HDL-platform-identifier>
Specify the HDL (FPGA) platform to be used by the container server on the target remote system. If this option is not used, the default is zed. See the OpenCPI User Guide for the possible identifiers for OpenCPI HDL platforms.
--rcc-platform=<RCC-platform-identifier>
Specify the RCC (software) platform to be used by the container server on the target remote system. If this option is not used, the default is xilinx19_2_aarch32. See the OpenCPI User Guide for the possible identifiers for OpenCPI RCC platforms.
--optimize
Specify that the software loaded should be what has been built with optimization enabled. The RCC platform must have already been built for optimization using the 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.
--port=<tcp-port-number>, -r <tcp-port-number>
Specify the TCP port of the container server on the target remote system. If this option is not specified, the first port number in the OCPI_SERVER_ADDRESSES environment variable is used.
--valgrind
Specify that the files needed to run 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.

Options When Deploying OpenCPI Bootable Media Files to a Remote System

--remote-dir=<directory-name>
Specify the name of the directory on the target remote system where the boot files will be placed.

--hdl-platform and --rcc-platform as described above.

Options When Starting or Restarting a Container Server

--bitstream, -b
Reload a test OpenCPI bitstream on the HDL platform (FPGA) prior to starting the server. On some systems this is needed to displace a non-OpenCPI bitstream that may have been preloaded at boot time.
--environment=<value>, -e<value>
Specify environment variable settings that will be applied to ocpiserve when it is started.
--log-level=<value>, -l<value>
Specify the OpenCPI log level to be used during container server execution. See the description of the 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).
--memory=<value>, -m<value>
Specify the amount of DMA memory to use when ocpiserve is running. The value may be decimal, octal or hex (using 0x). I.e. 0x400000 is 4 megabytes.
--valgrind
Specify that 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.

ENVIRONMENT VARIABLES

The following OpenCPI environment variables affect ocpiremote execution:

OCPI_SERVER_ADDRESSES
A comma- or space-separated list of IP addresses/TCP ports of remote systems to contact, where each IP/TCP address is in the format <ip-address>:<tcp-port>. For example, 192.168.1.102:12345. When ocpiserve with the --verbose option is started, it prints its IP addresses/TCP ports in the log.
OCPI_SERVER_ADDRESSES_FILE
The name of a file that contains remote system IP addresses/TCP ports, one per line. Each IP address is in the format <ip-address>:<tcp-port>. 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.

EXAMPLES

  1. 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

  2. Load and start an ocpiserve container server on the remote system with IP address 192.168.1.102 and port 12345 using the environment variable that will apply to all ocpiremote commands. Before starting the server, establish 4 megabytes of DMA memory, and load an OpenCPI bitstream on top of whatever is currently loaded. 

    export OCPI_SERVER_ADDRESSES=192.168.1.102:12345
ocpiremote load --rcc-platform=xilinx19_2_aarch32 --hdl-platform=e31x
ocpiremote start --bitstream --memory 0x400000

  3. Stop the ocpiserve container server on the remote system with IP address 192.168.1.102: 

    ocpiremote --ip-addr=192.168.1.102 stop

  4. 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

  5. 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

  6. 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

BUGS

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

RESOURCES

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

SEE ALSO

ocpiadmin(1) ocpidev(1) ocpidev-application(1) ocpidev-assembly(1) ocpidev-worker(1) ocpiserve(1) ocpirun(1)

COPYING

Copyright (C) 2020 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.