                  BlueField Rshim Host Driver

*) Build & Install

  make -C /lib/modules/`uname -r`/build M=$PWD
  make -C /lib/modules/`uname -r`/build M=$PWD modules_install

  The following kernel modules will be installed:

  Common modules:
    rshim.ko           rshim common code including console support
    rshim_net.ko       rshim network driver

  Different Backends:
    rshim_usb.ko       rshim USB backend
    rshim_pcie.ko      rshim PCIe backend with firmware burnt
    rshim_pcie_lf.ko   rshim PCIe backend in livefish mode

*) Module Load

  Usually rshim.ko and rshim_usb.ko (or rshim_pcie.ko) will be loaded
  automatically after reboot. If not, run "modprobe rshim" and
  "modprobe rshim_<usb | pcie | pcie_lf>.ko" to load it manually.
  rshim_net.ko will create a rshim network interface and can be loaded
  on demand.

  Note: Load multiple backends for the same board is not recommended.
        It could cause potential data corruption when both backends
        read / write at the same time.

*) Device Files

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

  - /dev/rshim<N>/boot
  Boot device file used to send boot stream to the ARM side, for example,
    cat install-bluewhale.bfb > /dev/rshim<N>/boot

  - /dev/rshim<N>/console
  Console device, which can be used by console tools to connect to the ARM side,
  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, encode the offset as "((rshim_channel << 16) | register_offset)".

  - /dev/rshim<N>/misc:
  Key/Value pairs used to read/write misc information. For example,
    # Dump the content.
    cat /dev/rshim<N>/misc
      BOOT_MODE 1
      SW_RESET  0

    # Initiate a SW reset.
    echo "SW_RESET 1" > /dev/rshim<N>/misc

*) What if both USB and PCIe access are enabled

  If both USB and PCIe are enabled, both rshim_usb.ko and rshim_pcie.ko will
  be loaded automatically which causes conflict when they write to RShim
  at the same time. One solution is to create a configuation file to pass
  'rshim_disable=1' to the specified kernel module. Below is an example to
  disable RShim access via USB.

      # Configuration file /etc/modprobe.d/rshim.conf
      options rshim_usb rshim_disable=1

*) Multiple Boards Support

  Multiple boards could connect to the same host machine. Each of them has its
  own device directory /dev/rshim<N>. Below are some guidelines how to set up
  rshim networking properly in such case.

  - Each target should load only one backend (usb, pcie or pcie_lf).

  - The host rshim network interface should have different MAC address and IP
    address, which can be configured with ifconfig like below or save it in
    configuration.
      ifconfig tmfifo_net0 192.168.100.2/24 hw ether 02:02:02:02:02:02

  - The ARM side tmfifo interface should have unique MAC and IP as well, which
    can be done in the console.

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

  - Login into Linux from the ARM console;
  - mount -t efivarfs none /sys/firmware/efi/efivars
  - chattr -i /sys/firmware/efi/efivars/RshimMacAddr-8be4df61-93ca-11d2-aa0d-00e098032b8c
  - printf "\x07\x00\x00\x00\x00\x1a\xca\xff\xff\x03" > \
      /sys/firmware/efi/efivars/RshimMacAddr-8be4df61-93ca-11d2-aa0d-00e098032b8c

  The above 'printf' command set the MAC address to 00:1a:ca:ff:ff:03 (the last
  six bytes of the printf value).
