[HLD] User Defined Fields(UDF) feature in SONiC by srodd-nexthop · Pull Request #2299 · sonic-net/SONiC

srodd-nexthop · 2026-04-17T11:34:35Z

Description:

Adds HLD for the UDF feature in SONiC, covering:

CONFIG_DB schema for UDF and UDF_SELECTOR tables
UdfOrch orchestration for SAI UDF Group, Match, and UDF object lifecycle
ACL integration with udf_field name resolution
YANG model validation, match deduplication, and dependency ordering

Yang changes: sonic-net/sonic-buildimage#26874
Swss changes: sonic-net/sonic-swss#4493
sairedis changes: sonic-net/sonic-sairedis#1856

linux-foundation-easycla · 2026-04-17T11:34:42Z

The committers listed above are authorized under a signed CLA.

✅ login: srodd-nexthop / name: satishkumar rodd (2606b72, 3b6d857, 5ff4e3c, 626db5d)
✅ login: srodd-nexthop / name: Satishkumar Rodd (bcd2d5d)

mssonicbld · 2026-04-17T11:34:43Z

/azp run

azure-pipelines · 2026-04-17T11:34:49Z

No pipelines are associated with this pull request.

mssonicbld · 2026-04-20T04:07:22Z

/azp run

azure-pipelines · 2026-04-20T04:07:28Z

No pipelines are associated with this pull request.

bingwang-ms · 2026-04-21T05:27:24Z

+
+### Object Roles(one-liner)
+
+- **UDF** = WHERE and how big (udf_field position/length in ACL key)


Where is position defined?

"Position" here means the slot index in the ACL key where the extracted udf_field bytes are written, not a property of the UDF object itself. Hence its called out as position in acl key

bingwang-ms · 2026-04-21T05:37:38Z

+{
+  // UDF definition
+  "UDF":            { "BTH_RESERVED":          { "field_type": "GENERIC", "length": "1" } },
+  "UDF_SELECTOR":   { "BTH_RESERVED|roce_v1":  { "match": { "l2_type": "0x8915", "l2_type_mask": "0xFFFF", "priority": "100" }, "select": { "base": "L2", "offset": "22" } },


I suppose base defined the start point of UDF object. But I think L2, L3 or L4 could be misleading sometimes. For example, there could be encapsulated frames, including VXLAN, IPinIP, and different IP hearers.

What's the difference between GENERIC and hash?

the base here are looking for the outer headers and for inner header we have to rely on the offset. Its been documented as an example in sonic-sairedis/SAI/doc/ACL/UDF-based-ACL.md

GENERIC is used for ACL integration
HASH is to define fields for ECMP hashing.

mssonicbld · 2026-04-21T05:38:10Z

/azp run

azure-pipelines · 2026-04-21T05:38:16Z

No pipelines are associated with this pull request.

bingwang-ms · 2026-04-21T05:41:22Z

+  // UDF definition
+  "UDF":            { "BTH_RESERVED":          { "field_type": "GENERIC", "length": "1" } },
+  "UDF_SELECTOR":   { "BTH_RESERVED|roce_v1":  { "match": { "l2_type": "0x8915", "l2_type_mask": "0xFFFF", "priority": "100" }, "select": { "base": "L2", "offset": "22" } },
+                      "BTH_RESERVED|roce_v2":  { "match": { "l3_type": "0x11",   "l3_type_mask": "0xFF",   "priority": "100" }, "select": { "base": "L4", "offset": "16" } } },


Can you please clarify how match and select work together?
I suppose match + select = When this packet type appears, extract bytes from HERE. Is that correct?

yes, match acts as a filter and select acts as a pointer from where the field has to be extracted.

bingwang-ms · 2026-04-21T05:57:24Z

+
+### 8.2 CLI
+
+CLI configuration for UDF is **not implemented**. Configuration is applied directly via CONFIG_DB using `sonic-cfggen` or `redis-cli`:


GCU (Generic Config Update) should be the preferred mechanism if CLI is not in plan.

Thanks — your json-in-config_db comment pushed me to drop the JSON-string model. select and match are now flat CONFIG_DB fields (select_base, select_offset, match_l2_type, …), so GCU, sonic-cfggen, and YANG all work natively.

bingwang-ms · 2026-04-21T06:04:20Z

+
+#### Why `select` and `match` are JSON values rather than flat fields
+
+CONFIG_DB stores each row as a flat Redis hash — one key, string-valued fields. Modeling `select` and `match` as nested containers would require splitting them into separate tables (e.g., `UDF_SELECTOR_SELECT`, `UDF_SELECTOR_MATCH`) keyed by the same `<udf>|<selector>`. We chose to keep the selector as a single atomic row so that a SET/DEL on one key represents one complete selector, and `match`/`select` cannot drift out of sync across tables. The tradeoff is that their internal structure lives inside a JSON value instead of the YANG tree.


Need to confirm and verify this json-in-config_db model is supported by GCU and other CLI, like sonic-cfggen.
YANG model validation can be another challenge as the json value will be handled as a pure string.

bingwang-ms · 2026-04-21T06:14:01Z

+  // UDF definition
+  "UDF":            { "BTH_RESERVED":          { "field_type": "GENERIC", "length": "1" } },
+  "UDF_SELECTOR":   { "BTH_RESERVED|roce_v1":  { "match": { "l2_type": "0x8915", "l2_type_mask": "0xFFFF", "priority": "100" }, "select": { "base": "L2", "offset": "22" } },
+                      "BTH_RESERVED|roce_v2":  { "match": { "l3_type": "0x11",   "l3_type_mask": "0xFF",   "priority": "100" }, "select": { "base": "L4", "offset": "16" } } },


May need some clarification on the priority, including

Is higher number = higher priority or lower?

What happens when two selectors have the SAME priority and both match?

Is priority globally unique required, or just per-field?

Thanks for the question, I'll validate the behavior on HW and update the HLD with concrete answers.

mssonicbld · 2026-04-21T09:45:15Z

/azp run

azure-pipelines · 2026-04-21T09:45:21Z

No pipelines are associated with this pull request.

Signed-off-by: satishkumar rodd <srodd@nexthop.ai>

mssonicbld · 2026-04-21T09:46:05Z

/azp run

azure-pipelines · 2026-04-21T09:46:11Z

No pipelines are associated with this pull request.

mssonicbld · 2026-04-21T09:55:34Z

/azp run

azure-pipelines · 2026-04-21T09:55:40Z

No pipelines are associated with this pull request.

Signed-off-by: satishkumar rodd <srodd@nexthop.ai>

mssonicbld · 2026-04-21T11:23:53Z

/azp run

azure-pipelines · 2026-04-21T11:24:00Z

No pipelines are associated with this pull request.

prsunny · 2026-04-21T15:35:07Z

+- Udf: Dependency handling, offset/base validation
+- UdfOrch: CONFIG_DB subscription, group OID resolution, ref-count tracking
+
+### 10.2 System Tests


can you elaborate this with scenarios and expectation. Also, please update PR link for sonic-mgmt tests.

e.g - https://github.com/sonic-net/SONiC/blob/master/doc/vxlan/Overlay%20ECMP%20with%20BFD.md#281-overlay-ecmp

mssonicbld · 2026-05-11T14:00:40Z

/azp run

azure-pipelines · 2026-05-11T14:00:49Z

No pipelines are associated with this pull request.

Replaces the high-level test categories in section 10 with explicit test scenarios drawn from the sonic-mgmt UDF suite, following the Step / Goal / Expected results format used in the Overlay ECMP HLD. 10.2 System Tests now covers: - Baseline programming - End-to-end traffic - UDF/ACL dependency and teardown order - ACL rule priority - Forward reference resolution - Multiple selectors per group - SAI attribute correctness (all 4 match types, 3 bases, auto-mask, match-presence regressions) - Match-type traffic filtering (L2 / L4 / IPv6) - Reference counting (UDF_MATCH dedup, UDF_GROUP refcount layers, ACL_RULE refcount on selectors) - Immutability and idempotency - Validation edge cases 10.3 Negative Tests: - Invalid CONFIG_DB - Selector field validation Each subsection references the corresponding test class(es) in the sonic-mgmt suite (tests/udf/test_udf.py, parallel PR -- Open Item #9). Addresses prsunny review comment. Signed-off-by: Satishkumar Rodd <srodd@nexthop.ai>

srodd-nexthop force-pushed the srodd.nexthopai-udf branch from 9ffbae4 to b2df6c0 Compare April 20, 2026 04:07

bingwang-ms reviewed Apr 21, 2026

View reviewed changes

srodd-nexthop force-pushed the srodd.nexthopai-udf branch from b2df6c0 to 800d9cc Compare April 21, 2026 05:38

bingwang-ms reviewed Apr 21, 2026

View reviewed changes

Comment thread doc/udf/UDF_HLD.md

bingwang-ms reviewed Apr 21, 2026

View reviewed changes

srodd-nexthop force-pushed the srodd.nexthopai-udf branch from 800d9cc to f3f9670 Compare April 21, 2026 09:45

srodd-nexthop added 3 commits April 21, 2026 09:45

UDF HLD

2606b72

Signed-off-by: satishkumar rodd <srodd@nexthop.ai>

Changes with new schema

626db5d

Signed-off-by: satishkumar rodd <srodd@nexthop.ai>

UDF core concepts removed

5ff4e3c

Signed-off-by: satishkumar rodd <srodd@nexthop.ai>

srodd-nexthop force-pushed the srodd.nexthopai-udf branch from f3f9670 to 4efbcde Compare April 21, 2026 09:45

srodd-nexthop force-pushed the srodd.nexthopai-udf branch from 4efbcde to 42e0539 Compare April 21, 2026 09:55

addressing review comments

3b6d857

Signed-off-by: satishkumar rodd <srodd@nexthop.ai>

srodd-nexthop force-pushed the srodd.nexthopai-udf branch from 42e0539 to 3b6d857 Compare April 21, 2026 11:23

prsunny requested a review from kperumalbfn April 21, 2026 15:30

prsunny reviewed Apr 21, 2026

View reviewed changes

srodd-nexthop mentioned this pull request May 11, 2026

[udf] Add sonic-mgmt tests for UDF feature sonic-net/sonic-mgmt#24518

Draft

6 tasks

srodd-nexthop force-pushed the srodd.nexthopai-udf branch from 320c343 to bcd2d5d Compare May 11, 2026 14:28


		### Object Roles(one-liner)

		- UDF = WHERE and how big (udf_field position/length in ACL key)


		### 8.2 CLI

		CLI configuration for UDF is not implemented. Configuration is applied directly via CONFIG_DB using `sonic-cfggen` or `redis-cli`:


		#### Why `select` and `match` are JSON values rather than flat fields

		CONFIG_DB stores each row as a flat Redis hash — one key, string-valued fields. Modeling `select` and `match` as nested containers would require splitting them into separate tables (e.g., `UDF_SELECTOR_SELECT`, `UDF_SELECTOR_MATCH`) keyed by the same `<udf>\|<selector>`. We chose to keep the selector as a single atomic row so that a SET/DEL on one key represents one complete selector, and `match`/`select` cannot drift out of sync across tables. The tradeoff is that their internal structure lives inside a JSON value instead of the YANG tree.

Conversation

srodd-nexthop commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

linux-foundation-easycla Bot commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mssonicbld commented Apr 17, 2026

Uh oh!

azure-pipelines Bot commented Apr 17, 2026

Uh oh!

mssonicbld commented Apr 20, 2026

Uh oh!

azure-pipelines Bot commented Apr 20, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mssonicbld commented Apr 21, 2026

Uh oh!

azure-pipelines Bot commented Apr 21, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mssonicbld commented Apr 21, 2026

Uh oh!

azure-pipelines Bot commented Apr 21, 2026

Uh oh!

mssonicbld commented Apr 21, 2026

Uh oh!

azure-pipelines Bot commented Apr 21, 2026

Uh oh!

mssonicbld commented Apr 21, 2026

Uh oh!

azure-pipelines Bot commented Apr 21, 2026

Uh oh!

mssonicbld commented Apr 21, 2026

Uh oh!

azure-pipelines Bot commented Apr 21, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mssonicbld commented May 11, 2026

Uh oh!

azure-pipelines Bot commented May 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

srodd-nexthop commented Apr 17, 2026 •

edited

Loading

linux-foundation-easycla Bot commented Apr 17, 2026 •

edited

Loading