Skip to main content

FBOSS BSP Mapping Config Generation

Introduction​

This document describes how to generate and consume Board Support Package (BSP) mapping configuration for FBOSS platforms.

The BSP mapping JSON is built into FBOSS binaries via per-platform *BspPlatformMapping C++ classes for platforms that use BSP mapping, such as MontblancBspPlatformMapping. For each module (PIM/FRU) in the system, it stores:

  • the transceiver reset/presence and I2C controller settings
  • the LED mapping for transceivers
  • MDIO and reset settings for external PHYs (when present)

Vendors are expected to provide CSV input files, run the BSP mapping generator to produce JSON, and then embed that JSON into the appropriate C++ mapping files.

Source File Specification​

BSP Mapping​

  • File name pattern: PLATFORM_BspMapping.csv
  • Location: fboss/lib/bsp/bspmapping/input/

This CSV file contains transceiver access, reset/presence, IO controller, and LED mapping information. Each row describes a set of lanes for a single transceiver and optionally a single LED.

Example: fboss/lib/bsp/bspmapping/input/Montblanc_BspMapping.csv.

Optional PHY BSP Mapping​

  • File name pattern: PLATFORM_PhyBspMapping.csv
  • Location: fboss/lib/bsp/bspmapping/input/

This CSV file is optional. When present, it describes the mapping between external PHYs and the MDIO controllers that manage them, including reset GPIO paths.

By convention, the PHY BSP mapping CSV name replaces the _BspMapping.csv suffix with _PhyBspMapping.csv. For example, for Ladakh800bcls_BspMapping.csv the corresponding PHY file is Ladakh800bcls_PhyBspMapping.csv in the same directory.

Example: fboss/lib/bsp/bspmapping/input/Ladakh800bcls_PhyBspMapping.csv.

CSV Column Definitions​

Transceiver Mapping CSV (PLATFORM_BspMapping.csv)​

The transceiver mapping CSV must have a header row and the following columns, in this order:

Column NameDefinition
TcvrIdID of the transceiver within the PIM.
TcvrLaneIdListSpace-separated list of logical lane IDs within the transceiver.
PimIdID of the PIM/FRU this transceiver belongs to (1 for a fixed system).
AccessControllerIdIdentifier for the reset/presence controller (e.g. a CPLD instance). Rows sharing this ID use the same controller.
AccessControlTypeType of reset/presence controller. Supported values: CPLD, GPIO.
ResetPathDevice path used to control the transceiver reset line, for the given access controller.
ResetMaskBit mask within the reset register that controls this transceiver.
ResetHoldHiReset polarity: 1 = active‑high, 0 = active‑low.
PresentPathDevice path used to read the transceiver presence signal.
PresentMaskBit mask within the presence register that corresponds to this transceiver.
PresentHoldHiPresence polarity: 1 = active‑high, 0 = active‑low.
IoControllerIdIdentifier of the I2C controller used to talk to this transceiver.
IoControlTypeType of IO controller. Supported value today: I2C.
IoPathDevice path for the IO controller (e.g. /run/devmap/xcvrs/xcvr_io_1).
LedId(Optional) ID of the LED associated with the lanes in TcvrLaneIdList.
LedBluePath(Optional) Device path for the blue or green portion of the LED.
LedYellowPath(Optional) Device path for the yellow or amber portion of the LED.

Notes:

  • The first row is treated as a header and skipped by the parser.
  • Only Lane IDs 1–8 are permitted in TcvrLaneIdList.
  • TcvrLaneIdList, LedId, LedBluePath and LedYellowPath may be empty.
  • Device path is usually PlatformManager device map path (e.g. /run/devmap/xcvrs/xcvr_io_1), but it can also be a sysfs path.

PHY Mapping CSV (PLATFORM_PhyBspMapping.csv)​

The optional PHY mapping CSV must have a header row and the following columns, in this order:

Column NameDefinition
PhyIdID of the external PHY.
PhyCoreIdID of the core within the PHY.
PimIdID of the PIM/FRU this PHY belongs to.
PhyResetPathDevice path used to control the reset line for this PHY.
IoControlTypeType of IO controller used to talk to this PHY. Supported value today: MDIO.
IoControllerIdID of the MDIO controller instance.
IoControllerResetPathDevice path used to control reset for the MDIO controller.
IoPathDevice path for the MDIO bus.
PhyAddrMDIO address of the PHY on the bus.

Notes:

  • If PLATFORM_PhyBspMapping.csv is not present for a platform, the generated BSP mapping will contain only transceiver and LED information.
  • Device path is usually PlatformManager device map path (e.g. /run/devmap/xcvrs/xcvr_io_1), but it can also be a sysfs path.

BSP Mapping Generation Workflow​

BSP Mapping JSON Generation Tool​

Prerequisites​

Python 3 is required in order to run the helper script. You can install it via one of the below commands depending on which Linux distribution you're on.

Debian​
sudo apt update
sudo apt -y upgrade
sudo apt install python3
CentOS​
sudo dnf upgrade -y
sudo dnf install python3

Instructions​

Generate the BSP Mapping configuration by running the helper shell script run-helper.sh from the root of the FBOSS repository:

$ ./fboss/lib/bsp/bspmapping/run-helper.sh

This runs the fboss-bspmapping-gen binary for each platform registered in the internal hardware map and writes one JSON file per platform to generated_configs in the system temporary directory, typically /tmp/generated_configs on Linux.

The JSON file names are derived from the platform type and lowercased. For example:

  • MONTBLANC → generated_configs/montblanc.json
  • JANGA800BIC → generated_configs/janga800bic.json
  • MERU400BFU → generated_configs/meru400bfu.json
  • ICECUBE → generated_configs/icecube.json
  • ICETEA → generated_configs/icetea.json

Adding or Updating a BSP Mapping for a Platform​

To add or update BSP mapping for a platform PLATFORM:

  1. Create/update CSV input files

    • Add or update fboss/lib/bsp/bspmapping/input/PLATFORM_BspMapping.csv.
    • (Optional) If the platform has external PHYs managed over MDIO, also add fboss/lib/bsp/bspmapping/input/PLATFORM_PhyBspMapping.csv.

  2. Register the platform CSV in the BSP mapping generator

    • Edit fboss/lib/bsp/bspmapping/Parser.h and add a new constant for the platform CSV, following the existing pattern:

      inline constexpr folly::StringPiece kPortMapping<PlatformName>Csv{
          "PLATFORM_BspMapping.csv"};

      PlatformName should be replaced with the new platform name being added, for example:

      inline constexpr folly::StringPiece kPortMappingMontblancCsv{
          "Montblanc_BspMapping.csv"};

    • Edit fboss/lib/bsp/bspmapping/Main.cpp and add an entry to kHardwareNameMap that maps the appropriate PlatformType to the new CSV constant, again following the existing pattern.

    • Edit fboss/lib/bsp/bspmapping/test/ParserTest.cpp to add the new platform to ParserTest.GetNameForTests.

  3. Generate BSP mapping JSON

    • From the FBOSS repository root, run:

      ./fboss/lib/bsp/bspmapping/run-helper.sh

    • After the script completes, locate the generated JSON file under /tmp/generated_configs/.

  4. Embed JSON into the per-platform C++ mapping class

Note: Unlike Platform Mapping, BSP Mapping currently does not have a dedicated verify_generated_files.py script. Only the CSV input files are committed to the repository; the embedded JSON string in each *BspPlatformMapping.cpp file must be kept in sync with those CSVs manually.

JSON File to C++ File Mapping​

For convenience, the table below shows the mapping between generated JSON files and the corresponding C++ BSP platform mapping classes for some of the existing platforms:

JSON File NameC++ File Location
generated_configs/janga800bic.jsonfboss/lib/bsp/janga800bic/Janga800bicBspPlatformMapping.cpp
generated_configs/ladakh800bcls.jsonfboss/lib/bsp/ladakh800bcls/Ladakh800bclsBspPlatformMapping.cpp
generated_configs/meru800bfa.jsonfboss/lib/bsp/meru800bfa/Meru800bfaBspPlatformMapping.cpp
generated_configs/minipack3n.jsonfboss/lib/bsp/minipack3n/Minipack3NBspPlatformMapping.cpp
generated_configs/montblanc.jsonfboss/lib/bsp/montblanc/MontblancBspPlatformMapping.cpp
generated_configs/morgan800cc.jsonfboss/lib/bsp/morgan800cc/Morgan800ccBspPlatformMapping.cpp
generated_configs/tahan800bc.jsonfboss/lib/bsp/tahan800bc/Tahan800bcBspPlatformMapping.cpp
generated_configs/wedge800bact.jsonfboss/lib/bsp/wedge800bact/Wedge800BACTBspPlatformMapping.cpp