BlueField Rshim Host Driver

The rshim driver provides a way to access the rshim resources on the BlueField target from external host machine. The current version implements device files for boot image push and virtual console access. It also creates virtual network interface to connect to the BlueField target and provides a way to access the internal rshim registers.

*) Build

Linux:

Make sure autoconf/automake/pkg-config tools are available. Run bootstrap.sh for the first time to generate the configure file. Then run the ./configure script followed by make & make install to build and install it.

FreeBSD:

Require FreeBSD 12.0+ with packages autoconf, automake, gmake, libepoll-shim, libpciaccess, libpci, pkgconf.

Follow the same steps above to build it. Use 'gmake install' to install it.

*) Usage

rshim -h syntax: rshim [--help|-h] [--backend|-b usb|pcie|pcie_lf] [--device|-d device-name] [--foreground|-f] [--debug-level|-l <0~4>]

*) Device Files

Each rshim target will create a directory /dev/rshim<N>/ with the following device files. <N> is the device id, which could be 0, 1, etc.

• /dev/rshim<N>/boot

Boot device file used to push boot stream to the ARM side, for example,

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

• /dev/rshim<N>/console

Console device, which can be used by console apps to connect to the ARM side, such as

screen /dev/rshim<N>/console

• /dev/rshim<N>/rshim

Device file used to access the rshim registers. The read/write offset is encoded as "((rshim_channel << 16) | register_offset)".

• /dev/rshim<N>/misc

Key/Value pairs used to read/write misc information. For example,

Display the content:

cat /dev/rshim<N>/misc
  DISPLAY_LEVEL   0 (0:basic, 1:advanced, 2:log)
  BOOT_MODE       1 (0:rshim, 1:emmc, 2:emmc-boot-swap)
  BOOT_TIMEOUT    100 (seconds)
  DROP_MODE       0 (0:normal, 1:drop)
  SW_RESET        0 (1: reset)
  DEV_NAME        usb-3.3
  DEV_INFO        BlueField-3(Rev 1)
  OPN_STR         9009D3B400ENEA
  UP_TIME         179752(s)
  SECURE_NIC_MODE 1 (0:no, 1:yes)

Display more infomation:

echo "DISPLAY_LEVEL 1" > cat /dev/rshim<N>/misc
cat /dev/rshim<N>/misc
  ...
  PEER_MAC  00:1a:ca:ff:ff:01   # Target-side MAC address
  PXE_ID    0x01020304          # PXE DHCP-client-identifier

The 'PEER_MAC' attribute can be used to display and set the target-side MAC
address of the rshim network interface. It works when the target-side is in
UEFI BootManager or in Linux where the tmfifo has been loaded. The new MAC
address will take effect in next boot.

Initiate a SW reset:

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

When 'SECURE_NIC_MODE' is shown as 1, the NIC firmware is in Secure NIC mode and most rshim functionalities are disabled. This mode applies to PCIe rshim backend only. PCIe LF and USB rshim backends are not affected.

*) Multiple Boards Support

Multiple boards could connect to the same host machine. Each of them has its own device directory /dev/rshim/. Network subnet needs to be set properly just like any other standard NIC.

*) How to change the MAC address of the ARM side interface

Update the 'PEER_MAC' attribute in the misc file like below. Display the value to confirm it's set. Reboot the device to take effect.

echo "PEER_MAC 00:1a:ca:ff:ff:10" > /dev/rshim\<N\>/misc