configuration/chassis.rst

Stratum Chassis Configuration
=============================

.. tip::

    Check out `examples <https://github.com/stratum/stratum/tree/main/stratum/hal/config>`_
    for every platform supported by Stratum.

    See the `Deployment Guide <../deployment.rst>`_ to learn about how to deploy Stratum
    with a custom chassis config.

The Stratum chassis config is the internal data structure that encapsulates the so called
"config" pushed to the entire chassis. The term "chassis" refers to the a switching box
with one or more switching nodes managed by a management interface.

The chassis config file will be placed on the disk of the device and loaded when starting the Stratum.
The config includes all the not-so-frequent settings that are required before the switch
can accept flow programming requests from the controller.

A valid chassis config includes a ``chassis`` and a ``node`` field, and may includes one
or more ``singleton_port`` field. See each section below for more detail.

.. note::

    In Stratum the external interface for pushing config is gNMI.
    The protobuf realization of the YANG models for the config is internally converted
    to a chassis config before it is consumed by the internal stack components.

    The `format of chassis config <https://github.com/stratum/stratum/blob/main/stratum/hal/lib/common/common.proto#L824-L833>`_
    is based on protobuf text format, check out
    `the protobuf language guide for more info <https://developers.google.com/protocol-buffers/docs/overview?hl=en>`_

Chassis
-------

A ``chassis`` uniquely identifies a switch with a single management interface.
Each chassis may contain one or more slots (aka linecards),
and one or more switching nodes (aka chips) on each slot.

A chassis contains the following fields:

* ``platform``: The chassis platform. **Required**
* ``name``: An arbitrary name for the chassis. **Optional**
* ``config_params``: Parameters configured for the entire chassis when config is pushed to the the switch. **Optional**

.. tip::

    Check out the list of platforms `here <https://github.com/stratum/stratum/blob/main/stratum/hal/lib/common/common.proto#L33-L47>`_

Node
----

A ``node`` uniquely identifies a single switching node (aka chip) on a chassis linecard
and all its flow-related and config-related parameters.

A node contains the following fields:

* ``id``: The unique ID of the switch node on the chassis as used by the P4Runtime controller. **Required**
* ``name``: An arbitrary name for the switching node. **Optional**
* ``slot``: The 1-base index of the slot (aka linecard) which this node belongs. **Required**
* ``index``: The optional 1-base index of the node within the chassis. **Optional**

Singleton Port
--------------

A ``singleton port`` in the chassis configuration uniquely identifies a single physical port on
a single chassis.

A singleton port contains the following fields:

* ``id``: The unique ID of the singleton port. **Required**
* ``name``: An optional arbitrary name for the singleton port. **Required**

    The control plan (e.g., ONOS) can use this name to query port information as a gNMI path key.

* ``slot``: The 1-base index of the slot (aka linecard) of the port. **Required**
* ``port``: The 1-base index of the singleton port on the slot. **Required**
* ``channel``: The 1-base channel index. Absence or zero means non-channelized. **Optional**
* ``speed_bps``: The speed of the port in bps. **Required**
* ``node``: The id of the corresponding node that the port belongs to. **Required**
* ``config_params``: Parameters configured for this port. **Optional**

  * ``admin_state``: The initial admin state for this port, port will be disabled by default.

    * Choose from ``ADMIN_STATE_DISABLED`` or ``ADMIN_STATE_ENABLED``.

  * ``mtu``: The maximum transmission unit for this port.
  * ``autoneg``: Whether auto-negotiation is enabled or not for this port.

    * Choose from ``TRI_STATE_FALSE`` or ``TRI_STATE_TRUE``
    * The initial configuration might be different if this field is empty, based on the
      platform or the connector you are using.

  * ``fec_mode``: The

    * Choose from ``FEC_MODE_ON``, ``FEC_MODE_OFF``, or ``FEC_MODE_AUTO``

  * ``loopback_mode``:

    * Choose from ``LOOPBACK_STATE_NONE``, ``LOOPBACK_STATE_MAC``, or ``LOOPBACK_STATE_PHY``

Example chassis config
----------------------

In this example, we want to set up a **Tofino-based switch** with only one node/slot.

And we want to set up two ports:

* Port 1: 100G port without channelization, enabled by default, and disable auto auto-negotiation.
* Port 2: break out to four 10G ports, uses different channels for each port and enable
  them by default with auto-negotiation.

.. image:: ../images/chassis-config-example.svg
    :width: 500px

Below is an example of a chassis configuration with a list of singleton port:

.. code-block::

    description: "A chassis config example."
    chassis {
        platform: PLT_GENERIC_BAREFOOT_TOFINO
        name: "leaf-1"
    }
    nodes {
        id: 1
        slot: 1
        index: 1
    }
    singleton_ports {
        id: 1
        name: "1/0"
        slot: 1
        port: 1
        speed_bps: 100000000000 # 100G
        config_params {
            admin_state: ADMIN_STATE_ENABLED
            autoneg: TRI_STATE_FALSE
        }
        node: 1
    }
    singleton_ports {
        id: 200
        name: "2/0"
        slot: 1
        port: 2
        channel: 1
        speed_bps: 10000000000 # 10G
        config_params {
            admin_state: ADMIN_STATE_ENABLED
            autoneg: TRI_STATE_TRUE
        }
        node: 1
    }
    singleton_ports {
        id: 201
        name: "2/1"
        slot: 1
        port: 2
        channel: 2
        speed_bps: 10000000000 # 10G
        config_params {
            admin_state: ADMIN_STATE_ENABLED
            autoneg: TRI_STATE_TRUE
        }
        node: 1
    }
    singleton_ports {
        id: 202
        name: "2/2"
        slot: 1
        port: 2
        channel: 3
        speed_bps: 10000000000 # 10G
        config_params {
            admin_state: ADMIN_STATE_ENABLED
            autoneg: TRI_STATE_TRUE
        }
        node: 1
    }
    singleton_ports {
        id: 203
        name: "2/3"
        slot: 1
        port: 2
        channel: 4
        speed_bps: 10000000000 # 10G
        config_params {
            admin_state: ADMIN_STATE_ENABLED
            autoneg: TRI_STATE_TRUE
        }
        node: 1
    }