man(8)

📦
version 2.7.1 · 5 versions
, in fedora 44

🌸 rshim — the user-space rshim driver for BlueField SoC (from man(8)) 🌸

okay bestie sit DOWN because this one is a whole manual page, section 8, and it's giving very much "driver that talks to your BlueField SoC over USB or PCIe" energy ✨

✨ NAME ✨

rshim — user-space rshim driver for BlueField SoC 💖

🎀 SYNOPSIS 🎀

rshim [options]

that's it. that's the whole vibe. options only, no positional args, slay 💅

🦋 DESCRIPTION 🦋

okay so rshim is the user-space rshim driver for BlueField SoC. It literally provides the ways to access the rshim resources on the BlueField target via USB or PCIe from an external host machine. No cap. 🫶

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 inside. 💖

A systemd link file (/etc/systemd/network/10-tmfifo-net.link) is installed to disable persistent MAC assignment for tmfifo_net interfaces so the MAC addresses set by rshim are not overridden by udev defaults. 🧚 (yes bestie, that's a whole real thing it does, not me being dramatic.)

🌈 /dev/rshim<N>/boot

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

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

push that stream, queen 👑

🌈 /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

screens and consoles and connecting to the target, oh my 💜

🌈 /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)
    BF_MODE         DPU mode
    BOOT_MODE       1 (0:rshim, 1:emmc, 2:emmc-boot-swap)
    BOOT_TIMEOUT    150 (seconds)
    USB_TIMEOUT     20 (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)

Values for BF_MODE could be "Unknown", "DPU mode", "NIC mode", or, "Reserved" 👀

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)
    BF_MODE         DPU mode
    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)

see how DISPLAY_LEVEL 1 unlocks the advanced tea ☕✨ that's the moment.

💅 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.
  • -c, --cmdmode — Run rshim as command line rather than as driver. Run "-c --help" to see the sub-commands.

Syntax: rshim -c --help

OPTIONS:

  • -g, --get-debug — Get the debug code.
  • -m, --bfdump — Start debug dump which is sent to the standard output.
  • -p, --get-config <NAME | all> — Get configuration value by name or use 'all' to see the list.
  • -r, --reg <addr.[32|64] [value]> — Read/write registers.
  • -s, --set-debug <0 | 1> set debug code — Set the debug code.

If rshim driver is already running on the current host, use "-i <index>" to specify /dev/rshim<index> to use. If "-i <index>" is not specified, it'll try to connect to the first USB backend. 🫶

  • -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. (yes bestie, that's the original spelling, I'm not touching it, character for character, periodt 💅)
  • -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

mapping devices by hand in a conf file? highkey iconic behavior 🎀

⭐ little reminder bestie: every path, flag, value, default and example above is exactly what the page says. don't go improvising on a driver page, fr fr. 🫶

and that's the whole thing! this was rshim, version 2.0, dated 18 Dec 2019, from the rshim man page (that's the manual name, we folded it in up top, you're welcome 💅). go forth and push boot streams, you absolute main character 👑💖✨

📦 where this page comes from