Skip to main content

FBOSS BSP Kernel Module API Specification

Version 1.0.0​

tip
TNoteThis indicates that this statement is covered by a BSP Tests test case. Hover to see the test case id.

1. Device References​

Any interaction between userspace and devices shall use the device interfaces created by the FBOSS PlatformManager service.

2. PCIe Character Device Interface​

Most I/O (I2C, SPI, etc) Controllers are provided by the PCIe FPGA in the FBOSS environment.

2.1 Subdevice (I/O Controller) Creation & Deletion​

Device topology/settings are managed from userspace with the PlatformManager service.

TCDEV.CdevIsCreatedThe PCIe FPGA driver registers a character device for each FPGA instance in the system with the following naming pattern:

fbiob_%04x.%04x.%04x.%04x% (vendor, device, subsystem_vendor, subsystem_device)

TCDEV.CdevCreateAndDeleteThis character device supports the following IOCTL commands:
  • FBIOB_IOC_NEW_DEVICE
  • FBIOB_IOC_DEL_DEVICE

More details can be found in the fbiob-ioctl.h header file.

2.2 Supported Controller Interfaces​

2.2.1 FPGA Information (fpga_info)​

Interface:

The FPGA Info driver exports the following sysfs files:

  • fw_ver
    • Type: unsigned integer
    • Description: This file reports the FPGA's firmware version in the format "%u.%u\n", major_ver, minor_ver
    • Read/Write: RO

2.2.2 I2C Controller (i2c_master)​

Interface:

TI2C.I2CAdapterCreatesBusses

Below are the list of I2C sysfs and character device interfaces used by FBOSS user space services:

  • /sys/bus/i2c/drivers/
  • /sys/bus/i2c/devices/i2c-#/
  • /sys/bus/i2c/devices/<bus>-00<addr>/
  • /dev/i2c-#
TI2C.I2CAdapterNames

PlatformManager creates mappings between /run/devmap/i2c-busses/BUS_NAME and the corresponding character device /dev/i2c-#. For example:

  • /run/devmap/i2c-busses/OPTICS_1 → /dev/i2c-5
TI2C.I2CAdapterDevicesExist

Once an i2c adapter has been created, devices are instantiated by using userspace API as described here:

Example:

# echo eeprom 0x50 > /sys/bus/i2c/devices/i2c-3/new_device
TI2C.I2CTransactions

If devices attached to this adapter are not managed by a kernel driver it is possible to interact with them directly by using ioctl commands. See the below document for a full explanation.

2.2.3 SPI Controller (spi_master)​

  • Interface:

  • SPI EEPROMs

    • Flashes and EEPROM devices must be managed by kernel drivers, and user space programs access devices through their client driver interfaces. Please see the documentation for the eeprom driver interface defiition.

  • SPIDEV

2.2.4 GPIO Controller (gpiochip)​

Interface:

TGPIO.GpioCreated

All FBOSS user space services access GPIOs via the character device interface at /dev/gpiochip#. Full description can be found here. https://docs.kernel.org/userspace-api/gpio/chardev.html

TGPIO.GpioInfo

A GPIO Line is identified by <gpiochip, offset> pair: gpiochip is a symlink located under /run/devmap/gpiochips/, and offset is a non-negative offset within the corresponding gpiochip.

2.2.5 HWMON and PMBUS Device​

Typical hardware monitoring devices in FBOSS include temperature, voltage, current and power sensors, PWM and Fan, etc. These device drivers are developed under the Linux hardware monitoring framework.

Interface:

THWMON.HwmonSensors

FBOSS services access hwmon devices via /sys/class/hwmon/hwmon#.

hwmon drivers must report values to user space with proper units, and below link defines all the details:

2.2.6 Fan Controller (fan_ctrl)​

Interface:

Fan control devices shall be implemented as hwmon devices and as such will follow the hwmon sysfs interface generally.

Behavior:

In cases where a fan is not present, all writes and reads to/from that fan must fail. For example, reading the RPM from a fan which is not present should not return 0 or some other "bad" value, but rather the operation must return an error code.

2.2.7 Fan Watchdog (watchdog_fan)​

Interface:

TWATCHDOG.WatchdogStart

FBOSS adopts the standard Linux watchdog daemon to feed watchdog via character device interface /dev/watchdog#. The watchdog API is defined here. kernel.org/doc/html/v6.4/watchdog/watchdog-api

TWATCHDOG.WatchdogPing

FBOSS Watchdog devices support start, stop, ping and set_timeout operations.

Behavior:

When the watchdog expires and is subsequently kicked, the watchdog shall rearm itself. This behavior ensures that the watchdog remains active and continues to monitor system status after an expiration event subsequent service recovery.

2.2.8 Transceiver Controller (xcvr_ctrl)​

Interface:

TXCVR.XcvrCreatesSysfsFiles

The xcvr_ctrl driver exports following sysfs entries for each transceiver port (port_num is 1-based integer):

  • xcvr_reset_<portnum>
    • TYPE: Bit
    • Description: Setting to 1 puts the optics in reset state, 0 takes it out of reset.
    • Read/Write: RW
  • xcvr_low_power_<portnum>
    • Type: Bit
    • Description: 1 sets the xcvr to low power mode.
    • Read/Write: RW
  • xcvr_present_<portnum>
    • Type: Bit
    • Description: 1 indicates xcvr is present, 0 indicates not present.
    • Read/Write: RO

2.2.9 LED​

LEDs are accessed via their original sysfs paths since they are non-dynamic. No symlinks are created by PlatformManager. All leds are found at /sys/class/leds/

Naming:

TLED.LedsCreated

LEDs are named with a common scheme:

<type><id?>_led:<color>:status

For example:

port10_led:blue:status
sys_led:red:status
port1_led::status

If an LED has no id in the name, it is a system-level LED, for example front-panel LEDs.

Interface:

TLED.DeviceLedsCreated
  • FBOSS services control LEDs by writing 0 or max_brightness to /sys/class/leds/<LED_NAME>/brightness files.
  • If a physical LED is separated into multiple logical LEDs (entries in /sys/class/leds/), then writing non-zero to any color will turn off the other colors.
    • This behavior must be reflected in the brightness file. For example,
      $ echo 1 > /sys/class/leds/port1_led:blue:status/brightness
      $ cat /sys/class/leds/port1_led:blue:status/brightness
      1
      $ echo 1 > /sys/class/leds/port1_led:amber:status/brightness
      $ cat /sys/class/leds/port1_led:blue:status/brightness
      0