Add SwitchProfile docs

docs/install-upgrade/build-wiring.md

@@ -3,6 +3,10 @@
 !!! warning ""
     Under construction.
 
+You can find mode details in the User Guide including [switch features and port naming](../user-guide/profiles.md). It's
+mandatoy to for all switches to reference a `SwitchProfile` in the `spec.profile` of the `Switch` object. Only port
+naming defined by switch profiles could be used in the wiring diagram, NOS (or any other) port names aren't supported.
+
 In the meantime, to have a look at working wiring diagram for Hedgehog Fabric, run the sample generator that produces
 VLAB-compatible wiring diagrams:
 

docs/install-upgrade/supported-devices.md

@@ -1,5 +1,7 @@
 # Supported Devices
 
+You can find mode details in the User Guide including [switch features and port naming](../user-guide/profiles.md).
+
 ## Spine
 
 * DELL: S5232F-ON

docs/reference/profiles.md

@@ -0,0 +1,3 @@
+# Switch Profiles
+
+TBD

docs/user-guide/connections.md

@@ -3,6 +3,11 @@
 The `Connection` object represents logical and physical connections between any devices in the Fabric (`Switch`,
 `Server` and `External` objects). It's needed to define all connections between the devices in the Wiring Diagram.
 
+All connections referencing some switch and device ports. Only port naming defined by switch profiles could be used in
+the wiring diagram for thr switches, NOS (or any other) port names aren't supported. Server ports aren't validated by
+the Fabric API other than for uniqueness. See the [Switch Profiles and Port Naming](../user-guide/profiles.md) section
+for more details.
+
 There are multiple types of connections.
 
 ## Server connections (user-facing)

docs/user-guide/devices.md

@@ -8,7 +8,8 @@ roles in the Wiring Diagram as well as [Connections](./connections.md) between t
 
 Switches are the main building blocks of the Fabric. They are represented by `Switch` objects in the API. These objects
 consist of basic metadata like name, description, location, role, as well as port group speeds, port breakouts, ASN,
-IP addresses, and more.
+IP addresses, and more. Additionally, it contains a reference to the `SwitchProfile` object that defines the switch
+model and capabilities, more details can be found in the [Switch Profiles and Port Naming](./profiles.md) section.
 
 ```yaml
 apiVersion: wiring.githedgehog.com/v1alpha2
@@ -17,6 +18,7 @@ metadata:
   name: s5248-01
   namespace: default
 spec:
+  profile: dell-s5248f-on # Mandatory reference to the SwitchProfile object defining the switch model and capabilities
   asn: 65101 # ASN of the switch
   description: leaf-1
   ip: 172.30.10.100/32 # Switch IP that will be accessible from the Control Node
@@ -25,11 +27,13 @@ spec:
   locationSig:
     sig: <undefined>
     uuidSig: <undefined>
-  portBreakouts: # Configures port breakouts for the switch
-    1/55: 4x25G
-  portGroupSpeeds: # Configures port group speeds for the switch
+  portBreakouts: # Configures port breakouts for the switch, see the SwitchProfile for available options
+    E1/55: 4x25G
+  portGroupSpeeds: # Configures port group speeds for the switch, see the SwitchProfile for available options
     "1": 10G
     "2": 10G
+  portSpeeds: # Configures port speeds for the switch, see the SwitchProfile for available options
+    E1/1: 25G
   protocolIP: 172.30.11.100/32 # Used as BGP router ID
   role: server-leaf # Role of the switch, one of server-leaf, border-leaf and mixed-leaf
   vlanNamespaces: # Defines which VLANs could be used to attach servers

docs/user-guide/profiles.md

@@ -0,0 +1,86 @@
+# Switch Profiles and Port Naming
+
+## Switch Profiles
+
+All supported switches have a `SwitchProfile` that defines the switch model, supported features, and available ports
+with supported configurations such as port group and speeds as well as port breakouts. `SwitchProfiles` available
+in-cluster or generated documentation can be found in the [Reference section](../reference/profiles.md).
+
+Each switch used in the wiring diagram should have a `SwitchProfile` references in the `spec.profile` of the `Switch`
+object.
+
+Switch profile defines what features and ports are available on the switch. Based on the ports data in the profile, it's
+possible to set port speeds (for non-breakout and non-group ports), port group speeds and port breakout modes in the
+`Switch` object in the Fabric API.
+
+## Port Naming
+
+Each switch port is named using one of the the following formats:
+
+- `M<management-port-number>`
+    - `<management-port-number>` is the management port number starting from `1` (usually only one named `1` for most
+  switches)
+
+- `E<asic-or-chassis-number>/<port-number>[/<breakout>][.<subinterface.]`
+    - `<asic-or-chassis-number>` is the ASIC or chassis number (usually only one named `1` for the most switches)
+    - `<port-number>` is the port number on the ASIC or chassis, starting from `1`
+    - optional `/<breakout>` is the breakout number for the port, starting from `1`, only for breakout ports and always
+    consecutive numbers independent of the lanes allocation and other implementation details
+    - optional `.<subinterface>` is the subinterface number for the port
+
+Examples of port names:
+
+- `M1` - management port
+- `E1/1` - port `1` on the ASIC or chassis `1`, usually a first port on the switch
+- `E1/55/1` - first breakout port of the switch port `55` on the ASIC or chassis `1`
+
+## Available Ports
+
+Each switch profile defines a set of ports available on the switch. Ports could be divided into the following types.
+
+### Directly configurable ports
+
+Non-breakout and non-group ports. Would have a reference to the port profile with default and available speeds. Could
+be configured by setting the speed in the `Switch` object in the Fabric API:
+
+```yaml
+.spec:
+  portSpeeds:
+    E1/1: 25G
+```
+
+### Port groups
+
+Ports that belong to a port group, non-breakout and not directly configurable. Would have a reference to the port group
+which will have a reference to the port profile with default and available speeds. Port couldn't be configured directly,
+speed configuration is applied to the whole group in the `Switch` object in the Fabric API:
+
+```yaml
+.spec:
+  portGroupSpeeds:
+    "1": 10G
+```
+
+It'll set the speed of all ports in the group `1` to `10G`, e.g. if the group `1` contains ports `E1/1`, `E1/2`, `E1/3`
+and `E1/4`, all of them will be set to `10G` speed.
+
+### Breakout ports
+
+Ports that are breakouts and non-group ports. Would have a reference to the port profile with default and available
+breakout modes. Could be configured by setting the breakout mode in the `Switch` object in the Fabric API:
+
+```yaml
+.spec:
+  portBreakouts:
+    E1/55: 4x25G
+```
+
+Configuring a port breakout mode will make "breakout" ports available for use in the wiring diagram. The breakout ports
+are named as `E<asic-or-chassis-number>/<port-number>/<breakout>`, e.g. `E1/55/1`, `E1/55/2`, `E1/55/3`, `E1/55/4` for
+the example above. Omitting the breakout number is allowed for the first breakout port, e.g. `E1/55` is the same as
+`E1/55/1`. The breakout ports are always consecutive numbers independent of the lanes allocation and other
+implementation details.
+
+### Management ports
+
+Not configurable, no port profile, only used for connecting the switch to the control node.