First pass up to configuration
Change-Id: Ifd82c38aa18d5216c5772a64d9d77046def005fe
diff --git a/configuration/chassis.rst b/configuration/chassis.rst
index 8d75245..9181a6a 100644
--- a/configuration/chassis.rst
+++ b/configuration/chassis.rst
@@ -3,37 +3,44 @@
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 `examples <https://github.com/stratum/stratum/tree/main/stratum/hal/config>`_
- for every platform supported by Stratum.
+ 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 `Deployment Guide <../deployment.rst>`_ to learn about how to deploy Stratum
+ See the :ref:`deployment_guide` 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.
+ 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 `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 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),
@@ -41,13 +48,10 @@
A chassis contains the following fields:
-* ``platform``: The chassis platform. **Required**
+* ``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 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>`_
+* ``config_params``: Parameters for the entire chassis, usually empty for Tofino-based devices. **Optional**
Node
----
@@ -57,68 +61,57 @@
A node contains the following fields:
-* ``id``: The unique ID of the switch node on the chassis as used by the P4Runtime controller. **Required**
+* ``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) which this node belongs. **Required**
-* ``index``: The optional 1-base index of the node within the chassis. **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`` in the chassis configuration uniquely identifies a single physical port on
-a single chassis.
+A ``singleton port`` uniquely identifies a switch port and it contains the following fields:
-A singleton port contains the following fields:
+* ``id``: An arbitrary ID, unique in the scope of a chassis. **Required**
+* ``name``: An optional user friendly name for the port (e.g., ``10/1`` to identify channel
+ 1 of front-panel port 10). **Required**
-* ``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.
+ 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``: Parameters configured for this port. **Optional**
+* ``config_params``: **Optional**
- * ``admin_state``: The initial admin state for this port, port will be disabled by default.
+ * ``admin_state``: The initial admin state for this port, 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
+ * ``fec_mode``: Forward Error Correction (FEC) mode
* 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.
+In this example, we want to set up a **Tofino-based switch** with only one node, one slot,
+and two ports:
-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.
+* 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
-Below is an example of a chassis configuration with a list of singleton port:
-
.. code-block::
description: "A chassis config example."