Daniele Moro | ed03356 | 2021-10-04 16:12:31 +0200 | [diff] [blame] | 1 | .. _stratum_chassis_config: |
| 2 | |
Yi Tseng | 22e7dbc | 2021-09-28 14:32:15 -0700 | [diff] [blame] | 3 | Stratum Chassis Configuration |
| 4 | ============================= |
| 5 | |
Carmelo Cascone | 4398998 | 2021-10-12 00:01:19 -0700 | [diff] [blame] | 6 | Chassis config is an internal data structure used by Stratum. The term "chassis" |
| 7 | refers to a switching box with one or more switching nodes (e.g., chips). The |
| 8 | chassis config file is usually placed on disk and loaded when starting Stratum. |
| 9 | This config includes all the not-so-frequent settings that are required before |
| 10 | the switch can accept flow programming requests from the controller. |
| 11 | |
| 12 | In the following, we provide a **non-exhaustive overview of the configurations |
| 13 | relevant to SD-Fabric for Tofino-based devices**. For a complete reference check |
| 14 | out the `ChassisConfig Protobuf message format |
| 15 | <https://github.com/stratum/stratum/blob/main/stratum/hal/lib/common/common.proto#L824-L833>`_ |
| 16 | and the `guide for running Stratum on Tofino-based switches |
| 17 | <https://github.com/stratum/stratum/blob/main/stratum/hal/bin/barefoot/README.run.md>`_ |
| 18 | in the Stratum repository. |
| 19 | |
Yi Tseng | 22e7dbc | 2021-09-28 14:32:15 -0700 | [diff] [blame] | 20 | .. tip:: |
| 21 | |
Carmelo Cascone | 4398998 | 2021-10-12 00:01:19 -0700 | [diff] [blame] | 22 | Check out the `Stratum repository |
| 23 | <https://github.com/stratum/stratum/tree/main/stratum/hal/config>`_ for |
| 24 | examples of chassis config files for different switch platforms. |
Yi Tseng | 22e7dbc | 2021-09-28 14:32:15 -0700 | [diff] [blame] | 25 | |
Carmelo Cascone | 4398998 | 2021-10-12 00:01:19 -0700 | [diff] [blame] | 26 | See the :ref:`deployment_guide` to learn about how to deploy Stratum |
Yi Tseng | 22e7dbc | 2021-09-28 14:32:15 -0700 | [diff] [blame] | 27 | with a custom chassis config. |
| 28 | |
Yi Tseng | 22e7dbc | 2021-09-28 14:32:15 -0700 | [diff] [blame] | 29 | .. note:: |
| 30 | |
Carmelo Cascone | 4398998 | 2021-10-12 00:01:19 -0700 | [diff] [blame] | 31 | In Stratum the external interface for pushing config is gNMI. The protobuf |
| 32 | realization of the YANG models for the config is internally converted to a |
| 33 | chassis config before it is consumed by the internal stack components. Not |
| 34 | all configurations are available through gNMI, for this reason we recommend |
| 35 | using the chassis config file. |
Yi Tseng | 22e7dbc | 2021-09-28 14:32:15 -0700 | [diff] [blame] | 36 | |
Carmelo Cascone | 4398998 | 2021-10-12 00:01:19 -0700 | [diff] [blame] | 37 | The file uses the protobuf text format, check out |
Yi Tseng | 22e7dbc | 2021-09-28 14:32:15 -0700 | [diff] [blame] | 38 | `the protobuf language guide for more info <https://developers.google.com/protocol-buffers/docs/overview?hl=en>`_ |
| 39 | |
| 40 | Chassis |
| 41 | ------- |
Carmelo Cascone | 4398998 | 2021-10-12 00:01:19 -0700 | [diff] [blame] | 42 | A valid chassis config includes a ``chassis``, a ``node`` field, and one |
| 43 | or more ``singleton_port`` fields. |
Yi Tseng | 22e7dbc | 2021-09-28 14:32:15 -0700 | [diff] [blame] | 44 | |
| 45 | A ``chassis`` uniquely identifies a switch with a single management interface. |
| 46 | Each chassis may contain one or more slots (aka linecards), |
| 47 | and one or more switching nodes (aka chips) on each slot. |
| 48 | |
| 49 | A chassis contains the following fields: |
| 50 | |
Carmelo Cascone | 4398998 | 2021-10-12 00:01:19 -0700 | [diff] [blame] | 51 | * ``platform``: The chassis platform, e.g., ``PLT_GENERIC_BAREFOOT_TOFINO`` for |
| 52 | 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** |
Yi Tseng | 22e7dbc | 2021-09-28 14:32:15 -0700 | [diff] [blame] | 53 | * ``name``: An arbitrary name for the chassis. **Optional** |
Carmelo Cascone | 4398998 | 2021-10-12 00:01:19 -0700 | [diff] [blame] | 54 | * ``config_params``: Parameters for the entire chassis, usually empty for Tofino-based devices. **Optional** |
Yi Tseng | 22e7dbc | 2021-09-28 14:32:15 -0700 | [diff] [blame] | 55 | |
| 56 | Node |
| 57 | ---- |
| 58 | |
| 59 | A ``node`` uniquely identifies a single switching node (aka chip) on a chassis linecard |
| 60 | and all its flow-related and config-related parameters. |
| 61 | |
| 62 | A node contains the following fields: |
| 63 | |
Carmelo Cascone | 4398998 | 2021-10-12 00:01:19 -0700 | [diff] [blame] | 64 | * ``id``: An arbitrary ID of the switch node on the chassis (corresponds to the P4Runtime device ID). **Required** |
Yi Tseng | 22e7dbc | 2021-09-28 14:32:15 -0700 | [diff] [blame] | 65 | * ``name``: An arbitrary name for the switching node. **Optional** |
Carmelo Cascone | 4398998 | 2021-10-12 00:01:19 -0700 | [diff] [blame] | 66 | * ``slot``: The 1-base index of the slot (aka linecard) to which this node belongs. **Required** |
| 67 | * ``index``: An optional 1-based index of the node within the chassis. **Optional** |
Yi Tseng | 22e7dbc | 2021-09-28 14:32:15 -0700 | [diff] [blame] | 68 | |
Daniele Moro | ed03356 | 2021-10-04 16:12:31 +0200 | [diff] [blame] | 69 | .. _singleton_port: |
| 70 | |
Yi Tseng | 22e7dbc | 2021-09-28 14:32:15 -0700 | [diff] [blame] | 71 | Singleton Port |
| 72 | -------------- |
| 73 | |
Carmelo Cascone | 4398998 | 2021-10-12 00:01:19 -0700 | [diff] [blame] | 74 | A ``singleton port`` uniquely identifies a switch port and it contains the following fields: |
Yi Tseng | 22e7dbc | 2021-09-28 14:32:15 -0700 | [diff] [blame] | 75 | |
Carmelo Cascone | 4398998 | 2021-10-12 00:01:19 -0700 | [diff] [blame] | 76 | * ``id``: An arbitrary ID, unique in the scope of a chassis. **Required** |
| 77 | * ``name``: An optional user friendly name for the port (e.g., ``10/1`` to identify channel |
| 78 | 1 of front-panel port 10). **Required** |
Yi Tseng | 22e7dbc | 2021-09-28 14:32:15 -0700 | [diff] [blame] | 79 | |
Carmelo Cascone | 4398998 | 2021-10-12 00:01:19 -0700 | [diff] [blame] | 80 | ONOS obtains this name via gNMI and uses it internally to represent ports. |
Yi Tseng | 22e7dbc | 2021-09-28 14:32:15 -0700 | [diff] [blame] | 81 | |
| 82 | * ``slot``: The 1-base index of the slot (aka linecard) of the port. **Required** |
| 83 | * ``port``: The 1-base index of the singleton port on the slot. **Required** |
| 84 | * ``channel``: The 1-base channel index. Absence or zero means non-channelized. **Optional** |
| 85 | * ``speed_bps``: The speed of the port in bps. **Required** |
| 86 | * ``node``: The id of the corresponding node that the port belongs to. **Required** |
Carmelo Cascone | 4398998 | 2021-10-12 00:01:19 -0700 | [diff] [blame] | 87 | * ``config_params``: **Optional** |
Yi Tseng | 22e7dbc | 2021-09-28 14:32:15 -0700 | [diff] [blame] | 88 | |
Carmelo Cascone | 4398998 | 2021-10-12 00:01:19 -0700 | [diff] [blame] | 89 | * ``admin_state``: The initial admin state for this port, disabled by default. |
Yi Tseng | 22e7dbc | 2021-09-28 14:32:15 -0700 | [diff] [blame] | 90 | |
| 91 | * Choose from ``ADMIN_STATE_DISABLED`` or ``ADMIN_STATE_ENABLED``. |
| 92 | |
Yi Tseng | 22e7dbc | 2021-09-28 14:32:15 -0700 | [diff] [blame] | 93 | * ``autoneg``: Whether auto-negotiation is enabled or not for this port. |
| 94 | |
| 95 | * Choose from ``TRI_STATE_FALSE`` or ``TRI_STATE_TRUE`` |
| 96 | * The initial configuration might be different if this field is empty, based on the |
| 97 | platform or the connector you are using. |
| 98 | |
Carmelo Cascone | 4398998 | 2021-10-12 00:01:19 -0700 | [diff] [blame] | 99 | * ``fec_mode``: Forward Error Correction (FEC) mode |
Yi Tseng | 22e7dbc | 2021-09-28 14:32:15 -0700 | [diff] [blame] | 100 | |
| 101 | * Choose from ``FEC_MODE_ON``, ``FEC_MODE_OFF``, or ``FEC_MODE_AUTO`` |
| 102 | |
Yi Tseng | 22e7dbc | 2021-09-28 14:32:15 -0700 | [diff] [blame] | 103 | Example chassis config |
| 104 | ---------------------- |
| 105 | |
Carmelo Cascone | 4398998 | 2021-10-12 00:01:19 -0700 | [diff] [blame] | 106 | In this example, we want to set up a **Tofino-based switch** with only one node, one slot, |
| 107 | and two ports: |
Yi Tseng | 22e7dbc | 2021-09-28 14:32:15 -0700 | [diff] [blame] | 108 | |
Carmelo Cascone | 4398998 | 2021-10-12 00:01:19 -0700 | [diff] [blame] | 109 | * Port 1: 100G port without channelization, enabled by default, without auto-negotiation. |
| 110 | * Port 2: break out port with four 10G channels, enabled by default, with auto-negotiation. |
Yi Tseng | 22e7dbc | 2021-09-28 14:32:15 -0700 | [diff] [blame] | 111 | |
| 112 | .. image:: ../images/chassis-config-example.svg |
| 113 | :width: 500px |
| 114 | |
Yi Tseng | 22e7dbc | 2021-09-28 14:32:15 -0700 | [diff] [blame] | 115 | .. code-block:: |
| 116 | |
| 117 | description: "A chassis config example." |
| 118 | chassis { |
| 119 | platform: PLT_GENERIC_BAREFOOT_TOFINO |
| 120 | name: "leaf-1" |
| 121 | } |
| 122 | nodes { |
| 123 | id: 1 |
| 124 | slot: 1 |
| 125 | index: 1 |
| 126 | } |
| 127 | singleton_ports { |
| 128 | id: 1 |
| 129 | name: "1/0" |
| 130 | slot: 1 |
| 131 | port: 1 |
| 132 | speed_bps: 100000000000 # 100G |
| 133 | config_params { |
| 134 | admin_state: ADMIN_STATE_ENABLED |
| 135 | autoneg: TRI_STATE_FALSE |
| 136 | } |
| 137 | node: 1 |
| 138 | } |
| 139 | singleton_ports { |
| 140 | id: 200 |
| 141 | name: "2/0" |
| 142 | slot: 1 |
| 143 | port: 2 |
| 144 | channel: 1 |
| 145 | speed_bps: 10000000000 # 10G |
| 146 | config_params { |
| 147 | admin_state: ADMIN_STATE_ENABLED |
| 148 | autoneg: TRI_STATE_TRUE |
| 149 | } |
| 150 | node: 1 |
| 151 | } |
| 152 | singleton_ports { |
| 153 | id: 201 |
| 154 | name: "2/1" |
| 155 | slot: 1 |
| 156 | port: 2 |
| 157 | channel: 2 |
| 158 | speed_bps: 10000000000 # 10G |
| 159 | config_params { |
| 160 | admin_state: ADMIN_STATE_ENABLED |
| 161 | autoneg: TRI_STATE_TRUE |
| 162 | } |
| 163 | node: 1 |
| 164 | } |
| 165 | singleton_ports { |
| 166 | id: 202 |
| 167 | name: "2/2" |
| 168 | slot: 1 |
| 169 | port: 2 |
| 170 | channel: 3 |
| 171 | speed_bps: 10000000000 # 10G |
| 172 | config_params { |
| 173 | admin_state: ADMIN_STATE_ENABLED |
| 174 | autoneg: TRI_STATE_TRUE |
| 175 | } |
| 176 | node: 1 |
| 177 | } |
| 178 | singleton_ports { |
| 179 | id: 203 |
| 180 | name: "2/3" |
| 181 | slot: 1 |
| 182 | port: 2 |
| 183 | channel: 4 |
| 184 | speed_bps: 10000000000 # 10G |
| 185 | config_params { |
| 186 | admin_state: ADMIN_STATE_ENABLED |
| 187 | autoneg: TRI_STATE_TRUE |
| 188 | } |
| 189 | node: 1 |
| 190 | } |