Porting Guide - mykolaf/SONiC GitHub Wiki

Description/Scope

SONiC is designed to be portable to a variety of network devices. Among devices, the majority of platform-dependent code involves controlling the ASIC, which SONiC handles via the Switch Abstraction Interface (SAI). However, many devices share the same ASIC platform, and only differ in other device-specific hardware components which require custom device drivers and/or configuration files which are loaded when the system is initialized. This guide describes requirements and general guidelines to follow when porting SONiC to a new device that contains a supported ASIC platform. Therefore, the remainder of this document assumes the device you are porting for contains an ASIC platform that SONiC currently supports.

Introduction

As mentioned above, to port SONiC to a new device, you will need to provide device-specific hardware drivers as well as device-specific configuration files to initialize your device properly. All device-specific changes will be made in the sonic-buildimage repository.

Platform Drivers

You are required to provide drivers to expose your device-specific hardware via sysfs to allow SONiC to communicate with them. Below is a list of drivers that are required along with their required feature sets.

  • QSFP transceivers
    • Read/write from/to EEPROMs
    • Enable/disable low-power mode
    • Reset transceiver
    • Query transceiver module presence
    • Detect interrupt
  • Sensors
    • Generate alarms at critical values
  • Front panel port status LEDs
    • Control LED state

These modules should be placed in the appropriate directory under the platform/ directory here.

SONiC images are compiled by ASIC manufacturer, and as such are designed to be installed on any supported device running that ASIC. Therefore, all platform modules for all devices running that ASIC are compiled into one image. The appropriate platform drivers are installed on the first boot of the device upon detection of the device's SKU.

In your module's .mk makefile you are able to specify which Debian package(s) are built and compiled into the images for which platform (by ONIE platform string). Also note that the same platform driver can be installed on multiple platforms; simply specify each platform in your module's .mk makefile.

Device-specific platform drivers added to SONiC must abide by the following rules:

  1. Drivers must be packaged into one or more Debian packages (.deb)
  2. All dependencies of the module must be specified in the Debian package, as they will be downloaded and compiled into the SONiC image, not at install time
  3. Drivers must not require a reboot after installation
  4. Drivers must support both initialization and deinitialization (required to allow for updating drivers on a running system in the future)

Device-Specific Files

All files that contain configuration or diagnostic information that are specific to a particular platform or hardware SKU reside under the device/ subdirectory here. The hierarchy of which is described in the following section.

Device-Specific File Directory Structure

SONiC distinguishes devices by a hierarchy of two levels, Platform and Hardware SKU. Some devices share the majority of the same hardware and only differ in, for example, the number/type of front panel ports (due to breakout configurations, etc.). In other words, multiple hardware SKUs can be configured on top of the same platform. While the front panel port configurations of these devices may differ, they still share common platform hardware like fans, sensors and system EEPROMs. The SONiC directory structure for device-specific files reflects this hierarchy and is designed to reduce the need for duplicate files as follows:

  • The device/ directory contains one subdirectory per switch vendor, named <VENDOR_NAME>/ (e.g., dell, mellanox).
    • Each <VENDOR_NAME>/ directory contains one subdirectory per unique ONIE platform string, named <ONIE_PLATFORM_STRING>/ (e.g., x86_64-dell_s6000_s1220-r0, x86_64-mlnx_msn2700-r0) and contains configuration files shared by all hardware SKUs built upon that platform.
      • Each <ONIE_PLATFORM_STRING>/ directory contains one subdirectory per unique hardware SKU, named <HARDWARE_SKU>/ (e.g., Force10-S6000, ACS-MSN2700) and contains configuration files specific to that individual hardware SKU.
device/
|-- <VENDOR_NAME>/
|   |-- <ONIE_PLATFORM_STRING>/
|   |   |-- <HARDWARE_SKU>/
|   |   |   |-- port_config.ini
|   |   |   |-- sai.profile
|   |   |   |-- xxx.config.bcm
|   |   |-- plugins/
|   |   |   |-- eeprom.py
|   |   |   |-- led_control.py
|   |   |   |-- psuutil.py
|   |   |   |-- sfputil.py
|   |   |-- fancontrol
|   |   |-- installer.conf
|   |   |-- led_proc_init.soc
|   |   |-- sensors.conf
  • Files that are specific to a unique platform as recognized by ONIE but are shared among all hardware SKU variations of said platform should be placed directly under the appropriate <ONIE_PLATFORM_STRING>/ directory.
  • Files that are specific to a unique hardware SKU (port_config.ini, etc.) should be placed under the appropriate <HARDWARE_SKU>/ directory within the appropriate <ONIE_PLATFORM_STRING>/ directory. The hardware SKU is determined at boot time via the <HwSku> tag in the minigraph file.

Common Device-Specific File Details

  • fancontrol
    • Configuration file for system fans used by fancontrol daemon.
      • NOTE: This file is optional. If your device uses an an entirely hardware-based fan control solution or you intend to use your own software for fan control, you can omit this file for your device.
    • Format: Specified in the fancontrol documentation
    • Example: 
      INTERVAL=10
DEVPATH=hwmon2=devices/pci0000:00/0000:00:1f.3/i2c-0/0-002f
DEVNAME=hwmon2=w83795adg
FCTEMPS=hwmon2/device/pwm2=hwmon2/device/temp2_input hwmon2/device/pwm1=hwmon2/device/temp2_input
FCFANS=hwmon2/device/pwm2=hwmon2/device/fan8_input hwmon2/device/pwm2=hwmon2/device/fan7_input hwmon2/device/pwm2=hwmon2/device/fan6_input hwmon2/device/pwm2=hwmon2/device/fan5_input hwmon2/device/pwm1=hwmon2/device/fan4_input hwmon2/device/pwm1=hwmon2/device/fan3_input hwmon2/device/pwm1=hwmon2/device/fan2_input hwmon2/device/pwm1=hwmon2/device/fan1_input
MINTEMP=hwmon2/device/pwm2=20 hwmon2/device/pwm1=20
MAXTEMP=hwmon2/device/pwm2=60 hwmon2/device/pwm1=60
MINSTART=hwmon2/device/pwm2=75 hwmon2/device/pwm1=75
MINSTOP=hwmon2/device/pwm2=22 hwmon2/device/pwm1=22
    • Testing: Testing is device-specific. You will need to devise a way to test your temperature thresholds and related fan speeds.
  • installer.conf
    • Configuration file for ONIE installer; allows for configuration of console device, port and speed as well as appending to the kernel command line
    • Requirements:
      • Must configure console port appropriately
    • Format: Key/value pairs in the form <KEY>=<VALUE>, one per line
      • VAR_LOG_SIZE (unit MB) can change the default VAR LOG SIZE to 100MB.
    • Example: 
      CONSOLE_PORT=0x2f8
CONSOLE_DEV=1
CONSOLE_SPEED=9600
ONIE_PLATFORM_EXTRA_CMDLINE_LINUX="acpi_enforce_resources=lax acpi=noirq"
VAR_LOG_SIZE=100
    • Testing: Build and install a SONiC image to confirm the installer was configured as expected.
  • sensors.conf
    • Libsensors configuration file. Used to configure sensor output from sensord daemon.
    • Requirements:
      • Provide clear and understandable labels for each sensor
      • Define critical values for each sensor. These can be defined either in this file or in hardware, as long as alarms are generated
    • Format: Specified in the sensors.conf documentation
    • Example: 
      # libsensors configuration file 
# ----------------------------------------------
#   
    
bus "i2c-2" "SCD SMBus master 0 bus 0"
bus "i2c-3" "SCD SMBus master 0 bus 1"
bus "i2c-5" "SCD SMBus master 0 bus 3"
bus "i2c-6" "SCD SMBus master 0 bus 4"
bus "i2c-7" "SCD SMBus master 0 bus 5"

chip "k10temp-pci-00c3"
    label temp1 "Cpu temp sensor"

chip "lm73-i2c-3-48"
    label temp1 "Rear Temp Sensor"
    set temp1_max 65 
    #set temp1_max_alarm 75 # read-only

chip "lm86-i2c-2-4c"
    label temp1 "Board Temp Sensor"
    set temp1_max 65 
    set temp1_crit 75

    label temp2 "Front-panel Temp Sensor"
    set temp2_max 65
    set temp2_crit 75
    
chip "pmbus-i2c-3-4e"
    label temp1 "Power Controller Sensor 1"
    set temp1_max 60
    set temp1_crit 70
    
    label temp2 "Power Controller Sensor 2"
    set temp2_max 60
    set temp2_crit 70

    ignore curr1
    
chip "pmbus-i2c-5-58"
    label temp1 "Power Supply 1 Sensor 1"
    set temp1_max 60
    set temp1_crit 70

    label temp2 "Power Supply 1 Sensor 2"
    set temp2_max 60
    set temp2_crit 70

    ignore temp3

    set in1_max 250
    set in1_crit 255
    set power1_max 525
    set power2_max 460
    set power2_crit 462
    set curr1_max 5.28
    set curr1_crit 5.30
    set curr2_max 36
    set curr2_crit 37
    
chip "pmbus-i2c-6-58"
    label temp1 "Power Supply 2 Sensor 1"
    set temp1_max 60
    set temp1_crit 70

    label temp2 "Power Supply 2 Sensor 2"
    set temp2_max 60
    set temp2_crit 70
    
    ignore temp3

    set in1_max 250
    set in1_crit 255
    set power1_max 525
    set power2_max 460
    set power2_crit 462
    set curr1_max 5.28
    set curr1_crit 5.30
    set curr2_max 36
    set curr2_crit 37
    • Testing: Testing is device-specific. You will need to adjust your thresholds and confirm that alarms are generated accordingly.
  • port_config.ini
    • Text file providing a SKU-specific mapping between SONiC port names, ASIC lanes and vendor port aliases.
    • Format: One line per port; variable number of columns, each separated by whitespace. Column order is also variable and must be specified by the column titles in the mandatory first line comment, as described below:
      • name: SONiC port name (required - Naming convention is at your discretion)
      • lanes: Comma-delimited list of the ASIC lanes connected to port (required)
      • alias: Vendor's alias for port (optional - this is helpful if converting an active switch from OEM software to SONiC. If the device was previously responding to SNMP queries using vendor port names, adding this alias will allow the device to continue responding to the SNMP queries). If alias column is omitted, SONiC will use port name as alias. Note that if aliases are provided, these aliases should be used to reference ports in the minigraph, not port names.
      • index: Physical index of port (optional - needed if ports do not begin with index zero or increment by one)
    • Example: 
      # name          lanes             alias         index
Ethernet0       9,10,11,12        Ethernet5/1   5
Ethernet4       13,14,15,16       Ethernet6/1   6
Ethernet8       17,18,19,20       Ethernet7/1   7
Ethernet12      21,22,23,24       Ethernet8/1   8
Ethernet16      29,30,31,32       Ethernet9/1   9
Ethernet20      25,26,27,28       Ethernet10/1  10
Ethernet24      33,34,35,36       Ethernet11/1  11
Ethernet28      37,38,39,40       Ethernet12/1  12
Ethernet32      45,46,47,48       Ethernet13/1  13
Ethernet36      41,42,43,44       Ethernet14/1  14
Ethernet40      49,50,51,52       Ethernet15/1  15
Ethernet44      53,54,55,56       Ethernet16/1  16
Ethernet48      69,70,71,72       Ethernet17/1  17
Ethernet52      65,66,67,68       Ethernet18/1  18
Ethernet56      73,74,75,76       Ethernet19/1  19
Ethernet60      77,78,79,80       Ethernet20/1  20
Ethernet64      93,94,95,96       Ethernet21/1  21
Ethernet68      89,90,91,92       Ethernet22/1  22
Ethernet72      97,98,99,100      Ethernet23/1  23
Ethernet76      101,102,103,104   Ethernet24/1  24
Ethernet80      109,110,111,112   Ethernet25/1  25
Ethernet84      105,106,107,108   Ethernet26/1  26
Ethernet88      121,122,123,124   Ethernet27/1  27
Ethernet92      125,126,127,128   Ethernet28/1  28
Ethernet96      61,62,63,64       Ethernet29    29
Ethernet100     57,58,59,60       Ethernet30    30
Ethernet104     81,82,83,84       Ethernet31    31
Ethernet108     85,86,87,88       Ethernet32    32
Ethernet112     117,118,119,120   Ethernet33    33
Ethernet116     113,114,115,116   Ethernet34    34
Ethernet120     1,2,3,4           Ethernet35    35
Ethernet124     5,6,7,8           Ethernet36    36
    • Testing: TODO
  • sai.profile and Broadcom config file

    • Profile for initializing SAI and ASIC

    • Format: Key/value pairs in the form <KEY>=<VALUE>, one per line

    • NOTE: Platforms based on Broadcom ASICs require a specific config.bcm file which is specified in the sai.profile file by the SAI_INIT_CONFIG_FILE property.

      • For existing platforms with working config.bcm with sai.profile, no change is needed.
      • Any newly added platform / changed config.bcm could be added to the device folder.
      • Please make sure sai.profile contents is "SAI_INIT_CONFIG_FILE=/usr/share/sonic/hwsku/"
      • If sai.profile is generated by a j2 template, please make sure it points to the new config.bcm file under /usr/share/sonic/hwsku/

    • Test new Broadcom configuration file.

      • Rebase branch to include PR #1611
      • Add new Broadcom configuration file to device/<vendor>/<Platform>/<hwsku> folder.
      • Run a regular make to build an image. If the build passes, the configuration file also passed the smoke test.
      • Install the built image on DUT and test it. The smoke test doesn't guarantee the configuration file actually works.

    • What if the new Broadcom configuration file contains entries denied by the build test?

      • Please don't create PR. It won't get approved or merged as-is.
      • Please don't add these entries to the permitted list. The PR won't be approved or merged.
      • Please contact Broadcom with list of entries currently being denied, ask Broadcom to give written permission to add these entries. Once we have the written approval from Broadcom, we will add the newly approved entries to the permission list. Then you can create PR.

    • Example:

  • led_control.py
    • Python module providing a unified API for updating front-panel LED state. It is used by the SONiC LED control daemon.
      • NOTE: This file is optional. If your device uses an an entirely hardware-based LED control solution you can omit this file for your device.
      • NOTE: This module is currently a work-in-progress.
    • Format: Python module that must implement the class LedControl which must inherit from sonic_led.led_control_base.LedControlBase. This class receives notifications when changes in link state occur and must update front panel LED state according to your platform-specific implementation.
    • Example:
    • Testing:
      1. Disconnect all cables from QSFP ports. All link status LEDs should indicate a "link down" state.
      2. Enter the Redis shell on the switch by running redis-cli
      3. Manually toggle link states in the Redis database and ensure the link status LEDs react accordingly. For example:
        • To set the link state for port Ethernet24 to "up": 127.0.0.1:6379> hset PORT_TABLE:Ethernet24 oper_status up
        • To set the link state for port Ethernet24 to "down": 127.0.0.1:6379> hset PORT_TABLE:Ethernet24 oper_status down
  • psuutil.py
    • Python module providing a unified API for interfacing with power supply units (PSUs) on your platform. Class supports the ability to query real-time statistics of PSUs on the platform.
    • NOTE: This plugin MUST be compatible with Python 3.6!
    • Format: Python module that must implement the class PsuUtil which must inherit from sonic_psu.psu_base.PsuBase which communicates with your PSU device driver
    • Example:
    • Testing: Call the psuutil application and confirm the following functionality is as expected:
      • psuutil numpsus : Verify the correct number of supported PSUs on the platform is displayed
      • psuutil status : Verify the correct status(es) of all PSUs on the platform are displayed
  • sfputil.py
    • Python module providing a unified API for interfacing with your SFP platform module. Class should support all features described in the Platform Drivers section above, such as the ability to read the EEPROM, reset transceivers, check for presence of a transceiver module and configure transceivers for low-power mode, etc.
    • Format: Python module that must implement the class SfpUtil which must inherit from sonic_sfp.sfputilbase.SfpUtilBase which communicates with your SFP device driver
    • Example:
    • Testing: Call the sfputil application and confirm the following functionality is as expected:
      • sfputil show eeprom : Verify all transceivers' EEPROM data is displayed properly
      • sfputil show presence : Verify all transceivers' presence status is displayed properly
      • sfputil show lpmode : Verify all transceivers' low-power mode status is displayed properly
      • sfputil reset ... : Attempt to reset every transceiver, verify all transceivers reset properly
      • sfputil lpmode ... : Enable low-power mode on all transceivers, verify all transceivers have low-power mode enabled. Disable low-power mode on all transceivers, verify all transceivers have low-power mode disabled.
Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️