Skip to content

Commit b87a00f

Browse files
prgeorprgeor
committed
APSU SAI port attributes
Signed-off-by: Prince George <prgeor@microsoft.com>
1 parent c8f0fe9 commit b87a00f

6 files changed

Lines changed: 389 additions & 0 deletions

File tree

‎doc/APSU/SAI-APSU-ILT.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
# SAI APSU / ILT Attributes
2+
3+
## Overview
4+
5+
This document maps the SAI APSU/ILT port attributes to their normative definitions in **IEEE P802.3dj Annex 178B** (*Autonomous PHY Start-Up (APSU) and In-band Link Training (ILT)*).
6+
7+
APSU defines a procedure by which two connected PHY interfaces autonomously bring up a link — including in-band link training (ILT) and a Ready-to-Send (RTS) handshake — without requiring out-of-band coordination. The procedure applies to both the host interface (C2M AUI) and the media interface (PMD to medium).
8+
9+
**Reference specification:** IEEE P802.3dj/D3.1, Annex 178B (4 June 2026 draft)
10+
11+
---
12+
13+
## Architecture Summary
14+
15+
```
16+
Per-LANE variables (independent per lane):
17+
local_tf_lock — local receiver has identified training frame boundaries
18+
remote_tf_lock — peer receiver has identified training frame boundaries (from status field)
19+
local_rx_ready — local receiver fully adapted, ready for data
20+
remote_rx_ready — peer receiver fully adapted (from status field)
21+
training_failure — training failed to complete on this lane
22+
lane_training_status — aggregate per-lane training state (IN_PROGRESS/TRAINED/OK/FAIL)
23+
24+
Per-INTERFACE variables (aggregated across all lanes):
25+
training_status — FAIL/IN_PROGRESS/READY/OK
26+
isl_ready — local_rx_ready AND remote_rx_ready true for ALL lanes
27+
local_rts — this interface is ready to send data
28+
remote_rts — peer interface is ready to send (all peer lanes have NRTS=0)
29+
rts_status — FAIL/IN_PROGRESS/READY/OK
30+
31+
Management variables (per interface):
32+
mr_training_enable — enables/disables ILT training on the interface
33+
mr_restart — triggers a restart of the RTS and ILT functions
34+
```
35+
36+
---
37+
38+
## Enum Definitions
39+
40+
### `sai_port_ilt_training_status_t`
41+
42+
Maps to the IEEE `training_status` per-interface variable (§178B.8.2.1, MDIO 1.1476.11:10).
43+
44+
| SAI Enum Value | IEEE Value | Description |
45+
|---|---|---|
46+
| `SAI_PORT_ILT_TRAINING_STATUS_RESERVED` | `—` | Unknown / not applicable |
47+
| `SAI_PORT_ILT_TRAINING_STATUS_FAIL` | `FAIL` | At least one lane has `training_failure = true` |
48+
| `SAI_PORT_ILT_TRAINING_STATUS_IN_PROGRESS` | `IN_PROGRESS` | At least one lane is training; no lanes have failed |
49+
| `SAI_PORT_ILT_TRAINING_STATUS_READY` | `READY` | All lanes are TRAINED or OK with at least one TRAINED |
50+
| `SAI_PORT_ILT_TRAINING_STATUS_OK` | `OK` | All lanes are OK (fully trained and stable) |
51+
52+
**Aggregation logic (§178B.8.2.1):**
53+
- `FAIL` if ANY lane has `lane_training_status = FAIL`
54+
- `IN_PROGRESS` if ≥1 lane is `IN_PROGRESS` and no lane is `FAIL`
55+
- `READY` if ALL lanes are `TRAINED` or `OK` and ≥1 lane is `TRAINED`
56+
- `OK` if ALL lanes are `OK`
57+
58+
### `sai_port_ilt_rts_status_t`
59+
60+
Maps to the IEEE `rts_status` per-interface variable (§178B.8.2.1, MDIO 1.1476.14:13).
61+
62+
| SAI Enum Value | IEEE Value | Description |
63+
|---|---|---|
64+
| `SAI_PORT_ILT_RTS_STATUS_RESERVED` | `—` | Unknown / not applicable |
65+
| `SAI_PORT_ILT_RTS_STATUS_FAIL` | `FAIL` | `training_status = FAIL`; RTS cannot proceed |
66+
| `SAI_PORT_ILT_RTS_STATUS_IN_PROGRESS` | `IN_PROGRESS` | RTS handshake in progress |
67+
| `SAI_PORT_ILT_RTS_STATUS_READY` | `READY` | Local RTS set; awaiting remote RTS |
68+
| `SAI_PORT_ILT_RTS_STATUS_OK` | `OK` | Both local and remote RTS established; ISL in DATA mode |
69+
70+
### `sai_port_ilt_lane_training_status_t`
71+
72+
Maps to the IEEE `lane_training_status` per-lane variable (§178B.8.3.1, MDIO 1.1477.1:0).
73+
74+
| SAI Enum Value | IEEE Value | Description |
75+
|---|---|---|
76+
| `SAI_PORT_ILT_LANE_TRAINING_STATUS_RESERVED` | `—` | Unknown / not applicable |
77+
| `SAI_PORT_ILT_LANE_TRAINING_STATUS_FAIL` | `FAIL` | Training failed on this lane |
78+
| `SAI_PORT_ILT_LANE_TRAINING_STATUS_IN_PROGRESS` | `IN_PROGRESS` | Lane is actively training |
79+
| `SAI_PORT_ILT_LANE_TRAINING_STATUS_TRAINED` | `TRAINED` | Lane completed training; both sides RX ready |
80+
| `SAI_PORT_ILT_LANE_TRAINING_STATUS_OK` | `OK` | Lane is in DATA mode and operational |
81+
82+
---
83+
84+
## SAI Port Attribute to IEEE 802.3dj Variable Mapping
85+
86+
### Control Attributes
87+
88+
| SAI Attribute | IEEE Variable | IEEE Section | MDIO Register (PMD) | MDIO Ref | Granularity | SAI Type |
89+
|---|---|---|---|---|---|---|
90+
| `SAI_PORT_ATTR_APSU_MR_TRAINING_ENABLE` | `mr_training_enable` | §178B.8.2.1 | `1.150.1` | 45.2.1.95 | Per interface | `bool` (default `true`) |
91+
| `SAI_PORT_ATTR_APSU_MR_RESTART` | `mr_restart` | §178B.8.2.1 | `1.150.0` | 45.2.1.95 | Per interface | `bool` (self-clearing, default `false`) |
92+
93+
**`mr_training_enable`** (§178B.8.2.1): When `true`, ILT training is enabled on the interface. Must be set to the same value at both ends of each ISL. Disabling training on ILT-capable ISLs may compromise APSU and link performance.
94+
95+
**`mr_restart`** (§178B.8.2.1): When set to `true`, triggers a restart of both the RTS and ILT state machines on the interface. The attribute is self-clearing — after the restart is initiated, hardware clears the bit, allowing subsequent restarts to be triggered by writing `true` again.
96+
97+
---
98+
99+
### Per-Interface Status Attributes
100+
101+
| SAI Attribute | IEEE Variable | IEEE Section | MDIO Register (PMD) | MDIO Ref | SAI Type |
102+
|---|---|---|---|---|---|
103+
| `SAI_PORT_ATTR_ILT_TRAINING_STATUS` | `training_status` | §178B.8.2.1 | `1.1476.11:10` | 45.2.1.168c | `sai_port_ilt_training_status_t` |
104+
| `SAI_PORT_ATTR_ILT_RTS_STATUS` | `rts_status` | §178B.8.2.1 | `1.1476.14:13` | 45.2.1.168c | `sai_port_ilt_rts_status_t` |
105+
| `SAI_PORT_ATTR_APSU_LOCAL_RTS_STATUS` | `local_rts` | §178B.8.2.1 | `1.1320.10` | 45.2.1.165 | `sai_latch_status_t` |
106+
| `SAI_PORT_ATTR_APSU_REMOTE_RTS_STATUS` | `remote_rts` | §178B.8.2.1 | `1.1120.10` | 45.2.1.161 | `sai_latch_status_t` |
107+
| `SAI_PORT_ATTR_APSU_ISL_READY` | `isl_ready` | §178B.8.2.1 | `1.1476.8` | 45.2.1.168c | `sai_latch_status_t` |
108+
109+
**`training_status`**: Per-interface aggregation of all per-lane `lane_training_status` values. See enum table above.
110+
111+
**`rts_status`**: Tracks the RTS handshake state machine. Transitions from `IN_PROGRESS` → `READY` (local RTS set) → `OK` (remote RTS received, ISL enters DATA mode). Set to `FAIL` if `training_status = FAIL`.
112+
113+
**`local_rts`**: Single boolean per interface. Set to `true` after all lanes reach `TRAINED`/`OK` and the clock swap completes. Its logical-NOT is encoded as the **Not Ready to Send (NRTS)** bit in the control field of every transmitted training frame (§178B.7.4.2).
114+
115+
**`remote_rts`**: Set to `true` when received training frames on **all lanes** of the interface have NRTS bit = 0. Represents `local_rts` of the peer interface as observed locally.
116+
117+
**`isl_ready`**: Set to `true` when `local_rx_ready` AND `remote_rx_ready` are `true` for **all lanes** of the interface (§178B.8.2.1). Triggers the RTS state machine. This is the primary observable indicator that bidirectional training has converged on all lanes.
118+
119+
---
120+
121+
### Per-Lane Status Attributes
122+
123+
The following attributes return a list of per-lane values (`sai_port_lane_latch_status_list_t`), with one entry per lane of the interface.
124+
125+
| SAI Attribute | IEEE Variable | IEEE Section | MDIO Register (PMD, lane 0) | MDIO Ref | SAI Type |
126+
|---|---|---|---|---|---|
127+
| `SAI_PORT_ATTR_APSU_LOCAL_TF_LOCK_STATUS` | `local_tf_lock` | §178B.8.3.1 | `1.151.1` (lane 0–3); see 45.2.1.96 for lanes 4–7 | 45.2.1.96 | `sai_port_lane_latch_status_list_t` |
128+
| `SAI_PORT_ATTR_APSU_REMOTE_TF_LOCK_STATUS` | `remote_tf_lock` | §178B.8.3.1 | `1.1420.9` (lane 0; lanes 1–7 offset in same reg) | 45.2.1.167 | `sai_port_lane_latch_status_list_t` |
129+
| `SAI_PORT_ATTR_APSU_LOCAL_RX_READY_STATUS` | `local_rx_ready` | §178B.8.3.1 | `1.1420.15` (lane 0; lanes 1–7 offset in same reg) | 45.2.1.167 | `sai_port_lane_latch_status_list_t` |
130+
| `SAI_PORT_ATTR_APSU_REMOTE_RX_READY_STATUS` | `remote_rx_ready` | §178B.8.3.1 | `1.1220.15` (lane 0; lanes 1–7 offset in same reg) | 45.2.1.163 | `sai_port_lane_latch_status_list_t` |
131+
| `SAI_PORT_ATTR_APSU_LOCAL_TRAINING_FAILURE_STATUS` | `training_failure` | §178B.8.3.1 | `1.151.3` (lane 0–3); see 45.2.1.101 for lanes 4–7 | 45.2.1.96 | `sai_port_lane_latch_status_list_t` |
132+
133+
> **Note on MDIO lane addressing:** Register bit references above are for lane 0 on a PMD. Lanes 1–7 are accessed at defined offsets within the same register (footnote c in Table 178B–7). Mappings for upper/lower AUI components are defined in §176C.8 and §176D.9 respectively.
134+
135+
**`local_tf_lock`** (§178B.8.3.1): `true` when the training frame marker position has been identified on a lane. Set by the training frame lock state diagram (Figure 178B–11). Reflected in the **Receiver frame lock** bit (bit 9) of the training frame status field (§178B.7.5.4), making it observable by the peer as `remote_tf_lock`.
136+
137+
**`remote_tf_lock`** (§178B.8.3.1): Reflects `local_tf_lock` of the peer on this lane. Derived from the Receiver frame lock bit (bit 9) of received training frames (Table 178B–4, Table 178B–5).
138+
139+
**`local_rx_ready`** (§178B.8.3.1): `true` when the receiver on a lane has completed equalization and is ready for data. Set by the training control state diagram (Figure 178B–10a). Encoded as the **Receiver ready** bit (bit 15) of the training frame status field (§178B.7.5.1).
140+
141+
**`remote_rx_ready`** (§178B.8.3.1): Reflects `local_rx_ready` of the peer on this lane. Derived from the Receiver ready bit (bit 15) of received training frames. `isl_ready` is `true` when this is `true` on all lanes.
142+
143+
**`training_failure`** (§178B.8.3.1): `true` when training fails to complete on a lane, typically due to `max_wait_timer` expiry. Set by the training control state diagram (Figure 178B–10a). When `true` on any lane, it causes `training_status = FAIL` and `rts_status = FAIL` at the interface level.
144+
145+
> **Observability note:** There is no `remote_training_failure` variable in IEEE 802.3dj. A remote-side training failure is only indirectly observable: it causes `remote_rx_ready` to remain `false`, which prevents `isl_ready` from being set, which causes the local `max_wait_timer` to expire and sets the local `training_failure = true`. Software cannot distinguish between a local-only failure and a remote-triggered timeout from these attributes alone.
146+
147+
---
148+
149+
## Variable Interaction and Bring-Up Sequence
150+
151+
```
152+
For each lane i:
153+
1. Training frames exchanged (tx_mode = TRAINING)
154+
2. local_tf_lock[i] → true (frame boundaries found)
155+
3. remote_tf_lock[i] → true (peer reports frame lock in status field)
156+
4. Coefficient update / equalization runs
157+
5. local_rx_ready[i] → true (local adaptation complete)
158+
6. remote_rx_ready[i] → true (peer reports ready in status field)
159+
OR training_failure[i] → true (max_wait_timer expired)
160+
161+
Across all lanes (interface level):
162+
7. isl_ready → true (local_rx_ready AND remote_rx_ready for ALL lanes)
163+
8. local_rts → true (clock swap completes, NRTS bit set to 0 in all TX frames)
164+
9. remote_rts → true (all peer lanes have NRTS=0)
165+
10. rts_status → OK (tx_mode = DATA; live traffic)
166+
```
167+
168+
---
169+
170+
## MDIO Register Summary (PMD, Annex 178B Tables 178B–6 and 178B–7)
171+
172+
| IEEE Variable | MDIO Register (lane 0) | MDIO Ref | Control/Status | Granularity |
173+
|---|---|---|---|---|
174+
| `mr_restart` | `1.150.0` | 45.2.1.95 | Control | Per interface |
175+
| `mr_training_enable` | `1.150.1` | 45.2.1.95 | Control | Per interface |
176+
| `max_wait_timer_duration` | `1.1459.15:0` | 45.2.1.168a | Control | Per interface |
177+
| `isl_ready` | `1.1476.8` | 45.2.1.168c | Status | Per interface |
178+
| `rts_status` | `1.1476.14:13` | 45.2.1.168c | Status | Per interface |
179+
| `training_status` | `1.1476.11:10` | 45.2.1.168c | Status | Per interface |
180+
| `local_rts` | `1.1320.10` | 45.2.1.165 | Status | Per interface |
181+
| `remote_rts` | `1.1120.10` | 45.2.1.161 | Status | Per interface |
182+
| `lane_training_status` | `1.1477.1:0` | 45.2.1.168d | Status | Per lane |
183+
| `local_tf_lock` | `1.151.1` (lanes 0–3) | 45.2.1.96 | Status | Per lane |
184+
| `remote_tf_lock` | `1.1420.9` | 45.2.1.167 | Status | Per lane |
185+
| `local_rx_ready` | `1.1420.15` | 45.2.1.167 | Status | Per lane |
186+
| `remote_rx_ready` | `1.1220.15` | 45.2.1.163 | Status | Per lane |
187+
| `training_failure` | `1.151.3` (lanes 0–3) | 45.2.1.96 | Status | Per lane |
188+
| `polarity_correction` | `1.1476.0` | 45.2.1.168c | Status | Per lane |

‎inc/saiport.h‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -869,6 +869,50 @@ typedef enum _sai_llr_frame_action_t
869869

870870
} sai_llr_frame_action_t;
871871

872+
/**
873+
* @brief Interface RTS status
874+
*/
875+
typedef enum _sai_port_ilt_rts_status_t
876+
{
877+
/** RTS status is unknown */
878+
SAI_PORT_ILT_RTS_STATUS_RESERVED,
879+
880+
/** RTS status is fail */
881+
SAI_PORT_ILT_RTS_STATUS_FAIL,
882+
883+
/** RTS status is in progress */
884+
SAI_PORT_ILT_RTS_STATUS_IN_PROGRESS,
885+
886+
/** RTS status is Ready */
887+
SAI_PORT_ILT_RTS_STATUS_READY,
888+
889+
/** RTS status is OK */
890+
SAI_PORT_ILT_RTS_STATUS_OK
891+
892+
} sai_port_ilt_rts_status_t;
893+
894+
/**
895+
* @brief Interface ILT Training status
896+
*/
897+
typedef enum _sai_port_ilt_training_status_t
898+
{
899+
/** Training status is reserved */
900+
SAI_PORT_ILT_TRAINING_STATUS_RESERVED,
901+
902+
/** Training status is failed */
903+
SAI_PORT_ILT_TRAINING_STATUS_FAIL,
904+
905+
/** Training status is in progress */
906+
SAI_PORT_ILT_TRAINING_STATUS_IN_PROGRESS,
907+
908+
/** Training status is Ready */
909+
SAI_PORT_ILT_TRAINING_STATUS_READY,
910+
911+
/** Training status is OK */
912+
SAI_PORT_ILT_TRAINING_STATUS_OK
913+
914+
} sai_port_ilt_training_status_t;
915+
872916
/**
873917
* @brief Attribute Id in sai_set_port_attribute() and
874918
* sai_get_port_attribute() calls
@@ -3327,6 +3371,116 @@ typedef enum _sai_port_attr_t
33273371
*/
33283372
SAI_PORT_ATTR_UNKNOWN_MULTICAST_STORM_CONTROL_POLICER_ID,
33293373

3374+
/**
3375+
* @brief Interface ILT Training status
3376+
*
3377+
* @type sai_port_ilt_training_status_t
3378+
* @flags READ_ONLY
3379+
*/
3380+
SAI_PORT_ATTR_ILT_TRAINING_STATUS,
3381+
3382+
/**
3383+
* @brief ILT per-lane training status
3384+
*
3385+
* Per-lane ILT training state.
3386+
*
3387+
* @type sai_port_ilt_lane_training_status_list_t
3388+
* @flags READ_ONLY
3389+
*/
3390+
SAI_PORT_ATTR_ILT_LANE_TRAINING_STATUS_LIST,
3391+
3392+
/**
3393+
* @brief Interface RTS status
3394+
*
3395+
* @type sai_port_ilt_rts_status_t
3396+
* @flags READ_ONLY
3397+
*/
3398+
SAI_PORT_ATTR_ILT_RTS_STATUS,
3399+
3400+
/**
3401+
* @brief APSU MR mr_training_enable variable to enable/disable the training on the interface
3402+
*
3403+
* @type bool
3404+
* @flags CREATE_AND_SET
3405+
* @default true
3406+
*/
3407+
SAI_PORT_ATTR_APSU_MR_TRAINING_ENABLE,
3408+
3409+
/**
3410+
* @brief APSU mr_restart variable to restart the RTS and ILT functions when true
3411+
*
3412+
* The variable should be self-clearing so that RTS+ILT functions can be restarted multiple times
3413+
*
3414+
* @type bool
3415+
* @flags CREATE_AND_SET
3416+
* @default false
3417+
*/
3418+
SAI_PORT_ATTR_APSU_MR_RESTART,
3419+
3420+
/**
3421+
* @brief APSU local_tf_lock variable
3422+
*
3423+
* @type sai_port_lane_latch_status_list_t
3424+
* @flags READ_ONLY
3425+
*/
3426+
SAI_PORT_ATTR_APSU_LOCAL_TF_LOCK_STATUS,
3427+
3428+
/**
3429+
* @brief APSU remote_tf_lock variable
3430+
*
3431+
* @type sai_port_lane_latch_status_list_t
3432+
* @flags READ_ONLY
3433+
*/
3434+
SAI_PORT_ATTR_APSU_REMOTE_TF_LOCK_STATUS,
3435+
3436+
/**
3437+
* @brief APSU local_rx_ready variable
3438+
*
3439+
* @type sai_port_lane_latch_status_list_t
3440+
* @flags READ_ONLY
3441+
*/
3442+
SAI_PORT_ATTR_APSU_LOCAL_RX_READY_STATUS,
3443+
3444+
/**
3445+
* @brief APSU remote_rx_ready variable
3446+
*
3447+
* @type sai_port_lane_latch_status_list_t
3448+
* @flags READ_ONLY
3449+
*/
3450+
SAI_PORT_ATTR_APSU_REMOTE_RX_READY_STATUS,
3451+
3452+
/**
3453+
* @brief Per lane ILT training_failure variable
3454+
*
3455+
* @type sai_port_lane_latch_status_list_t
3456+
* @flags READ_ONLY
3457+
*/
3458+
SAI_PORT_ATTR_ILT_TRAINING_FAILURE,
3459+
3460+
/**
3461+
* @brief APSU local_rts variable for the interface
3462+
*
3463+
* @type sai_latch_status_t
3464+
* @flags READ_ONLY
3465+
*/
3466+
SAI_PORT_ATTR_APSU_LOCAL_RTS_STATUS,
3467+
3468+
/**
3469+
* @brief APSU remote_rts variable for the interface
3470+
*
3471+
* @type sai_latch_status_t
3472+
* @flags READ_ONLY
3473+
*/
3474+
SAI_PORT_ATTR_APSU_REMOTE_RTS_STATUS,
3475+
3476+
/**
3477+
* @brief APSU isl_ready variable for the interface
3478+
*
3479+
* @type sai_latch_status_t
3480+
* @flags READ_ONLY
3481+
*/
3482+
SAI_PORT_ATTR_APSU_ISL_READY,
3483+
33303484
/**
33313485
* @brief End of attributes
33323486
*/

0 commit comments

Comments
 (0)