Skip to content

Commit 1b369bd

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

6 files changed

Lines changed: 376 additions & 0 deletions

File tree

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

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
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_IN_PROGRESS` | `IN_PROGRESS` | At least one lane is training; no lanes have failed |
48+
| `SAI_PORT_ILT_TRAINING_STATUS_READY` | `READY` | All lanes are TRAINED or OK with at least one TRAINED |
49+
| `SAI_PORT_ILT_TRAINING_STATUS_OK` | `OK` | All lanes are OK (fully trained and stable) |
50+
| `SAI_PORT_ILT_TRAINING_STATUS_FAIL` | `FAIL` | At least one lane has `training_failure = true` |
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_IN_PROGRESS` | `IN_PROGRESS` | RTS handshake in progress |
66+
| `SAI_PORT_ILT_RTS_STATUS_READY` | `READY` | Local RTS set; awaiting remote RTS |
67+
| `SAI_PORT_ILT_RTS_STATUS_OK` | `OK` | Both local and remote RTS established; ISL in DATA mode |
68+
| `SAI_PORT_ILT_RTS_STATUS_FAIL` | `FAIL` | `training_status = FAIL`; RTS cannot proceed |
69+
70+
---
71+
72+
## SAI Port Attribute to IEEE 802.3dj Variable Mapping
73+
74+
### Control Attributes
75+
76+
| SAI Attribute | IEEE Variable | IEEE Section | MDIO Register (PMD) | MDIO Ref | Granularity | SAI Type |
77+
|---|---|---|---|---|---|---|
78+
| `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`) |
79+
| `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`) |
80+
81+
**`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.
82+
83+
**`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.
84+
85+
---
86+
87+
### Per-Interface Status Attributes
88+
89+
| SAI Attribute | IEEE Variable | IEEE Section | MDIO Register (PMD) | MDIO Ref | SAI Type |
90+
|---|---|---|---|---|---|
91+
| `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` |
92+
| `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` |
93+
| `SAI_PORT_ATTR_APSU_LOCAL_RTS_STATUS` | `local_rts` | §178B.8.2.1 | `1.1320.10` | 45.2.1.165 | `sai_latch_status_t` |
94+
| `SAI_PORT_ATTR_APSU_REMOTE_RTS_STATUS` | `remote_rts` | §178B.8.2.1 | `1.1120.10` | 45.2.1.161 | `sai_latch_status_t` |
95+
| `SAI_PORT_ATTR_APSU_ISL_READY` | `isl_ready` | §178B.8.2.1 | `1.1476.8` | 45.2.1.168c | `sai_latch_status_t` |
96+
97+
**`training_status`**: Per-interface aggregation of all per-lane `lane_training_status` values. See enum table above.
98+
99+
**`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`.
100+
101+
**`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).
102+
103+
**`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.
104+
105+
**`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.
106+
107+
---
108+
109+
### Per-Lane Status Attributes
110+
111+
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.
112+
113+
| SAI Attribute | IEEE Variable | IEEE Section | MDIO Register (PMD, lane 0) | MDIO Ref | SAI Type |
114+
|---|---|---|---|---|---|
115+
| `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` |
116+
| `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` |
117+
| `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` |
118+
| `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` |
119+
| `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` |
120+
121+
> **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.
122+
123+
**`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`.
124+
125+
**`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).
126+
127+
**`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).
128+
129+
**`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.
130+
131+
**`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.
132+
133+
> **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.
134+
135+
---
136+
137+
## Variable Interaction and Bring-Up Sequence
138+
139+
```
140+
For each lane i:
141+
1. Training frames exchanged (tx_mode = TRAINING)
142+
2. local_tf_lock[i] → true (frame boundaries found)
143+
3. remote_tf_lock[i] → true (peer reports frame lock in status field)
144+
4. Coefficient update / equalization runs
145+
5. local_rx_ready[i] → true (local adaptation complete)
146+
6. remote_rx_ready[i] → true (peer reports ready in status field)
147+
OR training_failure[i] → true (max_wait_timer expired)
148+
149+
Across all lanes (interface level):
150+
7. isl_ready → true (local_rx_ready AND remote_rx_ready for ALL lanes)
151+
8. local_rts → true (clock swap completes, NRTS bit set to 0 in all TX frames)
152+
9. remote_rts → true (all peer lanes have NRTS=0)
153+
10. rts_status → OK (tx_mode = DATA; live traffic)
154+
```
155+
156+
---
157+
158+
## MDIO Register Summary (PMD, Annex 178B Tables 178B–6 and 178B–7)
159+
160+
| IEEE Variable | MDIO Register (lane 0) | MDIO Ref | Control/Status | Granularity |
161+
|---|---|---|---|---|
162+
| `mr_restart` | `1.150.0` | 45.2.1.95 | Control | Per interface |
163+
| `mr_training_enable` | `1.150.1` | 45.2.1.95 | Control | Per interface |
164+
| `max_wait_timer_duration` | `1.1459.15:0` | 45.2.1.168a | Control | Per interface |
165+
| `isl_ready` | `1.1476.8` | 45.2.1.168c | Status | Per interface |
166+
| `rts_status` | `1.1476.14:13` | 45.2.1.168c | Status | Per interface |
167+
| `training_status` | `1.1476.11:10` | 45.2.1.168c | Status | Per interface |
168+
| `local_rts` | `1.1320.10` | 45.2.1.165 | Status | Per interface |
169+
| `remote_rts` | `1.1120.10` | 45.2.1.161 | Status | Per interface |
170+
| `lane_training_status` | `1.1477.1:0` | 45.2.1.168d | Status | Per lane |
171+
| `local_tf_lock` | `1.151.1` (lanes 0–3) | 45.2.1.96 | Status | Per lane |
172+
| `remote_tf_lock` | `1.1420.9` | 45.2.1.167 | Status | Per lane |
173+
| `local_rx_ready` | `1.1420.15` | 45.2.1.167 | Status | Per lane |
174+
| `remote_rx_ready` | `1.1220.15` | 45.2.1.163 | Status | Per lane |
175+
| `training_failure` | `1.151.3` (lanes 0–3) | 45.2.1.96 | Status | Per lane |
176+
| `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
*/

‎inc/saitypes.h‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -570,6 +570,39 @@ typedef struct _sai_prbs_per_lane_rx_state_list_t
570570
sai_prbs_per_lane_rx_state_t *list;
571571
} sai_prbs_per_lane_rx_state_list_t;
572572

573+
/**
574+
* @brief Per-lane ILT training status
575+
*/
576+
typedef enum _sai_port_ilt_lane_training_status_t
577+
{
578+
/** Lane training status is reserved */
579+
SAI_PORT_ILT_LANE_TRAINING_STATUS_RESERVED,
580+
581+
/** Lane training is in progress */
582+
SAI_PORT_ILT_LANE_TRAINING_STATUS_IN_PROGRESS,
583+
584+
/** Lane training completed */
585+
SAI_PORT_ILT_LANE_TRAINING_STATUS_TRAINED,
586+
587+
/** Lane training fully trained */
588+
SAI_PORT_ILT_LANE_TRAINING_STATUS_OK,
589+
590+
/** Lane training failed (training_failure true on this lane) */
591+
SAI_PORT_ILT_LANE_TRAINING_STATUS_FAIL
592+
} sai_port_ilt_lane_training_status_t;
593+
594+
typedef struct _sai_ilt_lane_training_status_t
595+
{
596+
uint32_t lane;
597+
sai_port_ilt_lane_training_status_t training_status;
598+
} sai_ilt_lane_training_status_t;
599+
600+
typedef struct _sai_port_ilt_lane_training_status_list_t
601+
{
602+
uint32_t count;
603+
sai_ilt_lane_training_status_t *list;
604+
} sai_port_ilt_lane_training_status_list_t;
605+
573606
/**
574607
* @brief Field match mask
575608
*
@@ -1807,6 +1840,9 @@ typedef union _sai_attribute_value_t
18071840
/** @validonly meta->attrvaluetype == SAI_ATTR_VALUE_TYPE_UINT64_RANGE_LIST */
18081841
sai_u64_range_list_t u64rangelist;
18091842

1843+
/** @validonly meta->attrvaluetype == SAI_ATTR_VALUE_TYPE_PORT_ILT_LANE_TRAINING_STATUS_LIST */
1844+
sai_port_ilt_lane_training_status_list_t port_ilt_lane_training_status_list;
1845+
18101846
} sai_attribute_value_t;
18111847

18121848
/**

0 commit comments

Comments
 (0)