oracular (8) rshim.8.gz

Provided by: rshim_2.0.38+debian-2_amd64 bug

NAME

       rshim - user-space rshim driver for BlueField SoC

SYNOPSIS

       rshim [options]

DESCRIPTION

       rshim  is  the  user-space  rshim driver for BlueField SoC. It provides ways to access the
       rshim resources on the BlueField target via USB or PCIe from external  host  machine.  The
       current  version  implements virtual console, virtual network interface, boot stream push,
       register access and some utility commands.

       This driver will probe the rshim backend and create directory /dev/rshim<N>  for  each  of
       them with the following device files.

   /dev/rshim<N>/boot
       Boot device file used to push boot stream to the target, for example,

           cat install.bfb > /dev/rshim<N>/boot

   /dev/rshim<N>/console
       Console device file, which can be used by console tools to connect to the target, such as

           screen /dev/rshim<N>/console

   /dev/rshim<N>/rshim
       Device  file  used  to access rshim register space. When reading/writing to this file, the
       offset is encoded as "((rshim_channel << 16) | register_offset)". This file can be used by
       tools like openocd to do CoreSight debugging.

   /dev/rshim<N>/misc
       Key/Value pairs used to read/write misc information. For example

       Display the output

           cat /dev/rshim0/misc
               DISPLAY_LEVEL   0 (0:basic, 1:advanced, 2:log)
               BOOT_MODE       1 (0:rshim, 1:emmc, 2:emmc-boot-swap)
               BOOT_TIMEOUT    150 (seconds)
               DROP_MODE       0 (0:normal, 1:drop)
               SW_RESET        0 (1: reset)
               DEV_NAME        usb-1.1
               DEV_INFO        BlueField-2(Rev 1)
               OPN_STR         N/A
               FORCE_CMD       0 (1: send Force command)

       Initiate SW reset

           echo "SW_RESET 1" > /dev/rshim<N>/misc

       Send a Force command to request the other rshim driver to release the rshim device

           echo "FORCE_CMD 1" > /dev/rshim<N>/misc

       Enable the advanced options

           echo "DISPLAY_LEVEL 1" > /dev/rshim<N>/misc

           cat /dev/rshim0/misc
               DISPLAY_LEVEL   1 (0:basic, 1:advanced, 2:log)
               BOOT_MODE       1 (0:rshim, 1:emmc, 2:emmc-boot-swap)
               BOOT_TIMEOUT    100 (seconds)
               SW_RESET        0 (1: reset)
               DEV_NAME        pcie-04:00.2
               DEV_INFO        BlueField-1(Rev 0)
               PEER_MAC        00:1a:ca:ff:ff:01 (rw)
               PXE_ID          0x00000000 (rw)
               VLAN_ID         0 0 (rw)

OPTIONS

       -b, --backend
           Specify  the  backend  to  attach,  which  can  be one of usb, pcie or pcie_lf. If not
           specified, the driver will scan all rshim backends unless the  '-d'  option  is  given
           with a device name specified.

       -d, --device
           Specify  the  device  name  to attach with the format below. The backend driver can be
           deduced from the device name, thus the '-b' option is not needed.

               PCIe backend:
                   pcie-<bus>:<device>.<function>. Example: pcie-04:00.2
                   Devices can be found with command 'lspci -n'.

               PCIe backend in livefish mode:
                   pcie-lf-<bus>:<device>.<function>. Example: pcie-04:00.2
                   Devices can be found with command 'lspci -n'.

               USB backend:
                   usb-<bus>-xx.xx. Example: usb-2-1.7
                   Devices can be found under /sys/bus/usb/devices/.

       -f, --foreground
           Run in forground.

       -F, --force
           Put rshim driver in ownership-forceable mode (aka. force  mode).  In  this  mode,  the
           driver will be put rshim driver in ownership-forceable mode (aka, Force Mode):

           1.  It  also always enables "/dev/rshim<N>/" creation even when rshim is not attached,
           allowing user to manually send a ownership request to  "/dev/rshim<N>/misc"  interface
           at any time.

           2.  It  will send a one time ownership request command to the other rshim backend upon
           start-up if the rshim interface is already attached by another backend.  This one-time
           request is for each rshim device present (one request for rshim0, one for rshim1, etc)
           and will not be repeated until the next driver restart.

           For example, if the current rshim driver is running from host via PCIe, but the  rshim
           device  is already in use by the other rshim driver running from BMC via USB, then the
           user can use this option to try to force the other rshim driver to release  the  rshim
           device.   The   success  of  this  operation  depends  on  the  other  rshim  driver's
           implementation and behavior.

           This option is equivalent to setting "FORCE_MODE" to 1 in rshim.conf.

       -i, --index
           Specify the index to create device path /dev/rshim<index>. It's also  used  to  create
           network  interface  name  tmfifo_net<index>. This option is needed when multiple rshim
           instances are running.

       -l, --log-level
           Log level (0:none, 1:error, 2:warning, 3:notice, 4:debug) Log messages will be printed
           to standard output when running in foreground, or in syslog when running as a daemon.

       -v, --version
           Display version

CONFIGURATION FILE

       Rshim  configuration  file  (/etc/rshim.conf)  can  be  used to specify the static mapping
       between rshim devices and rshim names. It can also be used to ignore some rshim devices.

       Example:
           # Map usb-2-1.7 to rshim0
           rshim0       usb-2-1.7

           # Map pcie-0000:04:00.2 to rshim1
           rshim1       pcie-0000:04:00.2

           # Ignore usb-1-1.4
           none         usb-1-1.4