blob: 8d752450458ece58a03ed8c8fd1d87ed21b3d90a [file] [log] [blame]
.. _stratum_chassis_config:
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 agent.
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:
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
}