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

2.0                                                18 Dec 2019                                            man(8)