.. SPDX-FileCopyrightText: 2021 Open Networking Foundation <info@opennetworking.org>
.. SPDX-License-Identifier: Apache-2.0

.. _stratum_chassis_config:

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

Chassis config is an internal data structure used by Stratum. The term "chassis"
refers to a switching box with one or more switching nodes (e.g., chips). The
chassis config file is usually placed on disk and loaded when starting Stratum.
This config includes all the not-so-frequent settings that are required before
the switch can accept flow programming requests from the controller.

In the following, we provide a **non-exhaustive overview of the configurations
relevant to SD-Fabric for Tofino-based devices**. For a complete reference check
out the `ChassisConfig Protobuf message format
<https://github.com/stratum/stratum/blob/main/stratum/hal/lib/common/common.proto#L824-L833>`_
and the `guide for running Stratum on Tofino-based switches
<https://github.com/stratum/stratum/blob/main/stratum/hal/bin/barefoot/README.run.md>`_
in the Stratum repository.

.. tip::

    Check out the `Stratum repository
    <https://github.com/stratum/stratum/tree/main/stratum/hal/config>`_ for
    examples of chassis config files for different switch platforms.

    See the :ref:`deployment_guide` to learn about how to deploy Stratum
    with a custom chassis config.

.. 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. Not
    all configurations are available through gNMI, for this reason we recommend
    using the chassis config file.

    The file uses the protobuf text format, check out
    `the protobuf language guide for more info <https://developers.google.com/protocol-buffers/docs/overview?hl=en>`_

Chassis
-------
A valid chassis config includes a ``chassis``, a ``node`` field, and one
or more ``singleton_port`` fields.

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, e.g., ``PLT_GENERIC_BAREFOOT_TOFINO`` for
  Tofino-based devices (check out `here <https://github.com/stratum/stratum/blob/main/stratum/hal/lib/common/common.proto#L33-L47>`_ for other platforms). **Required**
* ``name``: An arbitrary name for the chassis. **Optional**
* ``config_params``: Parameters for the entire chassis, usually empty for Tofino-based devices. **Optional**

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``: An arbitrary ID of the switch node on the chassis (corresponds to the P4Runtime device ID). **Required**
* ``name``: An arbitrary name for the switching node. **Optional**
* ``slot``: The 1-base index of the slot (aka linecard) to which this node belongs. **Required**
* ``index``: An optional 1-based index of the node within the chassis. **Optional**

.. _singleton_port:

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

A ``singleton port`` uniquely identifies a switch port and it contains the following fields:

* ``id``: An arbitrary ID, unique in the scope of a chassis. **Required**

    .. note::
        We recommend using the following naming convention for both ONOS network config and Stratum chassis config:
            - For unchannelized ports, use the **front panel port** number directly.
            - For channelized ports, use the **front panel port number * 100 + channel id**.
              For example, we can use port id ``2903`` for port ``29/3`` (port 29 channel 3).
            - Note that we use **zero-based** channel number for singleton port ``id``
              but the ``channel`` field described below uses **one-based** channel number.

* ``name``: An optional user friendly name for the port (e.g., ``10/1`` to identify channel
  1 of front-panel port 10). **Required**

    ONOS obtains this name via gNMI and uses it internally to represent ports.

* ``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``: **Optional**

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

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

  * ``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``: Forward Error Correction (FEC) mode

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

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

In this example, we want to set up a **Tofino-based switch** with only one node, one slot,
and two ports:

* Port 1: 100G port without channelization, enabled by default, without auto-negotiation.
* Port 2: break out port with four 10G channels, enabled by default, with auto-negotiation.

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

.. 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
    }