[SDFAB-601] Add chassis config guide
Change-Id: Ibbf6689c45efc1a128d5057c7e0993dea4a263cf
diff --git a/configuration/chassis.rst b/configuration/chassis.rst
index 776321f..1db3b1a 100644
--- a/configuration/chassis.rst
+++ b/configuration/chassis.rst
@@ -1,2 +1,193 @@
-Chassis Configuration
-=====================
+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
+ }