Skip to main content

Add Initial Support for Platform Services

Overview​

Adding support for Platform Services consists of creating the PlatformManager config, adding BSP support, ensuring that PlatformManager can start, and passing 100% of HW tests for Platform Services.

If you run into issues, try checking our troubleshooting guide.

After each section, check the Overall Outcomes below to ensure everything is completed.

Overall Outcomes​

Setup​

  • an FBOSS platform stack Docker container to perform builds in

Add PlatformManager Support​

  • platform_manager.json is committed to the FBOSS repository
  • platform_manager.json abides by the specification

Add BSP Support​

  • the BSP repository is setup and accessible by Meta
  • the BSP abides by the API specification and development requirements
  • the BSP is compiled as out-of-tree kernel modules and deployed in FBOSS to unblock FBOSS development
  • bsp_tests.json is modified as needed based on guidance in bsp_tests_config.thrift
  • 100% of BSP tests pass
  • expected errors are defined in the test config if and only if the hardware has a valid reason and this is agreed to by Meta

Build, Run, and Test Platform Services​

  • platform services can be built successfully
  • platform manager can start successfully
  • 100% of platform service hardware tests pass

Setup​

This setup step is required for adding BSP support and validating platform services. At the end of it, you should have an FBOSS platform stack Docker container that can be used to build and test artifacts in all other steps.

Step 1: Clone the FBOSS Repository​

git clone https://github.com/facebook/fboss.git
cd fboss

Step 2: Stop Existing Containers and Clean Docker Artifacts​

sudo docker container kill -a && sudo docker container prune -f
sudo docker image prune -af

Step 3: Build the FBOSS Docker Image​

# Builds a docker container image that is tagged as fboss_docker:latest
sudo docker build . -t fboss_docker -f fboss/oss/docker/Dockerfile

Step 4: Start a Platform Stack Container​

# Use stable commits
rm -rf build/deps/github_hashes/
tar xvzf fboss/oss/stable_commits/latest_stable_hashes.tar.gz

# If you know your host has enough space for the build
sudo docker run -d \
    -it --name=FBOSS_DOCKER_CONTAINER \
    -v $PWD:/var/FBOSS/fboss:z \
    fboss_docker:latest bash

# A full FBOSS build may take significant space (>50GB of storage). You
# can mount a volume with more storage for building by using the -v flag
sudo docker run -d \
    -it --name=FBOSS_DOCKER_CONTAINER \
    -v $PWD:/var/FBOSS/fboss:z \
    -v /opt/app/localbuild:/var/FBOSS/tmp_bld_dir:z \
    fboss_docker:latest bash

At this point, you should have a Docker container which can be used to build the required artifacts in later steps.

Add PlatformManager Support​

PlatformManager support is required for all other platform services to run. A configuration needs to be created and placed in the repository.

Step 1: Create the Config File​

The vendor needs to create the platform_manager.json config file. There is a sample file located in the repository. The guidelines for creating the config file are specified here.

Step 2: Upstream the Changes​

After the config is created, raise a PR placing it in its config directory. Configs are stored here, where the name of the directory should be the name of the new platform using all lowercase.

Add BSP Support​

Adding BSP support involves creating a new repository, implementing the BSP, and then running tests to ensure adherence to guidelines.

Step 1: Create a BSP Repository​

Please work with your Meta POC to initialize a private repository where your BSP implementation will be hosted.

Step 2: Implement the BSP​

Implement the BSP to support the platforms under development. When implementing the BSP, you need to ensure it abides by the API specifications and development requirements.

Step 3: Install the KMODS on the Switch​

Install the KMODS on the switch.

Step 4: Configure BSP Tests​

BSP Tests use the platform_manager.json file to know which devices to test, but some additional information needs to be provided to the bsp_tests.json configuration file. More details can be found in the thrift file and bsp_tests.json file.

Step 5: Build BSP Tests​

Use the platform stack Docker container from the Setup step.

Step 5.1: Enter the Container​

# Attaches our current terminal to a new bash shell in the docker container so
# that we can perform the build within it
sudo docker exec -it FBOSS_DOCKER_CONTAINER bash

Step 5.2: Build BSP Tests​

Build BSP tests by using the build command, where $TARGET is bsp_tests:

# Navigate to the right directory
cd /var/FBOSS/fboss

# Build using a cmake target
time ./build/fbcode_builder/getdeps.py build --allow-system-packages \
--extra-cmake-defines='{"CMAKE_BUILD_TYPE": "MinSizeRel", "CMAKE_CXX_STANDARD": "20"}' \
--scratch-path /var/FBOSS/tmp_bld_dir --cmake-target $TARGET fboss

Step 6: Send Build Artifacts to the Switch​

Step 6.1: Package the BSP Tests​

# On the container used for building FBOSS:

# Clean any existing packages
rm -rf /var/FBOSS/tmp_bld_dir/fboss_bins*

# Navigate to the FBOSS repository
cd /var/FBOSS/fboss

# Creates a package directory with prefix /var/FBOSS/tmp_bld_dir/fboss_bins
./fboss/oss/scripts/package-fboss.py --copy-root-libs --scratch-path /var/FBOSS/tmp_bld_dir/

# or

# Creates a tarball called "fboss_bins.tar.zst" under /var/FBOSS/tmp_bld_dir/
./fboss/oss/scripts/package-fboss.py --copy-root-libs --scratch-path /var/FBOSS/tmp_bld_dir/ --compress

Step 6.2: Copy and Set Up the Package​

# From the host that the container is running on, use the appropriate command to
# copy the FBOSS package directory or tarball to the switch:

# If copying the directory
scp -r /opt/app/FBOSS_DIR/tmp_bld_dir/fboss_bins-$PKG_ID root@$SWITCHNAME:/opt/

# If copying the tarball
scp /opt/app/FBOSS_DIR/tmp_bld_dir/fboss_bins.tar.zst root@$SWITCHNAME:/opt/



# On the switch, use the appropriate command to set up the package:

# If using the directory
cd /opt
ln -s /opt/fboss_bins-$PKG_ID /opt/fboss

# If using the tarball
cd /opt
mkdir fboss && mv fboss_bins.tar.zst fboss/
cd fboss && tar -xvf fboss_bins.tar.zst



# You will have a directory /opt/fboss/ which contains a bin/, lib/, and share/
# directory

Step 7: Run BSP Tests​

BSP tests are intended to be a comprehensive test suite for the FBOSS platform BSP. Tests are designed to cover each statement in the two BSP specification documents mentioned above.

On the switch that you have copied the package to and installed KMODS on, simply set up the environment and invoke the binary to run tests:

cd /opt/fboss
source ./bin/setup_fboss_env

# Run all tests
./bin/bsp_tests

# Filter on specific tests
./bin/bsp_tests --gtest_filter="I2C*"

Note: A test failure indicates that at least one of the requirements of the specifications linked above is not met.

Expected Errors​

In some cases it may not be possible for a specific hardware to meet all specification requirements. In that case we provide an ExpectedErrors field in the bsp tests config. Errors apply to one device and require a reason string to be supplied to it. Currently supported error types can be found with their documentation in the thrift file and sample config.

We do not plan to use this as a way to get around difficult requirements, but if your hardware truly cannot meet a requirement for some reason please reach out to your Meta contact.

Contributing​

Vendors are welcome to contribute to the test suite. The test suite lives at fboss/platform/bsp_tests.

Build, Run, and Test Platform Services​

Step 1: Build Platform Services​

Use the platform stack Docker container from the Setup step.

Step 1.1: Enter the Container​

# Attaches our current terminal to a new bash shell in the docker container so
# that we can perform the build within it
sudo docker exec -it FBOSS_DOCKER_CONTAINER bash

Step 1.2: Build Platform Services​

Build platform services by using the build command, where $TARGET is fboss_platform_services:

# Navigate to the right directory
cd /var/FBOSS/fboss

# Build using a cmake target
time ./build/fbcode_builder/getdeps.py build --allow-system-packages \
--extra-cmake-defines='{"CMAKE_BUILD_TYPE": "MinSizeRel", "CMAKE_CXX_STANDARD": "20"}' \
--scratch-path /var/FBOSS/tmp_bld_dir --cmake-target $TARGET fboss

Step 2: Send Build Artifacts to the Switch​

Step 2.1: Package the Platform Services​

# On the container used for building FBOSS:

# Clean any existing packages
rm -rf /var/FBOSS/tmp_bld_dir/fboss_bins*

# Navigate to the FBOSS repository
cd /var/FBOSS/fboss

# Creates a package directory with prefix /var/FBOSS/tmp_bld_dir/fboss_bins
./fboss/oss/scripts/package-fboss.py --copy-root-libs --scratch-path /var/FBOSS/tmp_bld_dir/

# or

# Creates a tarball called "fboss_bins.tar.zst" under /var/FBOSS/tmp_bld_dir/
./fboss/oss/scripts/package-fboss.py --copy-root-libs --scratch-path /var/FBOSS/tmp_bld_dir/ --compress

Step 2.2: Copy and Set Up the Package​

# From the host that the container is running on, use the appropriate command to
# copy the FBOSS package directory or tarball to the switch:

# If copying the directory
scp -r /opt/app/FBOSS_DIR/tmp_bld_dir/fboss_bins-$PKG_ID root@$SWITCHNAME:/opt/

# If copying the tarball
scp /opt/app/FBOSS_DIR/tmp_bld_dir/fboss_bins.tar.zst root@$SWITCHNAME:/opt/



# On the switch, use the appropriate command to set up the package:

# If using the directory
cd /opt
ln -s /opt/fboss_bins-$PKG_ID /opt/fboss

# If using the tarball
cd /opt
mkdir fboss && mv fboss_bins.tar.zst fboss/
cd fboss && tar -xvf fboss_bins.tar.zst



# You will have a directory /opt/fboss/ which contains a bin/, lib/, and share/
# directory

Step 3: Run Platform Manager​

Ensure that platform manager can run:

cd /opt/fboss
source ./bin/setup_fboss_env

./bin/setup.py
./bin/platform_manager

Step 4: Test Platform Services​

We have binaries that test the functionality of our platform services. On the switch that you have copied the package to, simply set up the environment variables, run the binaries, and observe the output for each binary:

cd /opt/fboss
source ./bin/setup_fboss_env

./bin/platform_hw_test
./bin/data_corral_service_hw_test
./bin/fan_service_hw_test
./bin/fw_util_hw_test
./bin/platform_manager_hw_test
./bin/sensor_service_hw_test
./bin/weutil_hw_test