Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Generic Table First draft #435

Merged
merged 45 commits into from
Feb 22, 2024
Merged
Changes from 1 commit
Commits
Show all changes
45 commits
Select commit Hold shift + click to select a range
e553d88
Initial changes for generic tables
saynb Apr 13, 2023
1d8eff5
second changes
saynb Apr 13, 2023
4690968
3rd changes
saynb Apr 14, 2023
55bf9be
4th changes
saynb Apr 14, 2023
f775ddc
5th changes
saynb Apr 14, 2023
07b2da6
Adding p4types and p4info changes for GenericData (#4)
saynb May 12, 2023
e4a5309
Adding varbits and a readme writeup (#5)
saynb May 12, 2023
fd132e7
Adding proto changes
saynb May 12, 2023
2a5eae6
Adding genericTable for direct resources. Adding P4datatypespec to ge…
saynb May 19, 2023
35dc65a
* Adding more container types
saynb May 26, 2023
6e7c5f1
* Add Table categories introduction
saynb May 26, 2023
d6e042b
* Adding 3-level property details (Table, Entry, field)
saynb Jun 2, 2023
53b105f
* Adding Read RPC details in table categories
saynb Jun 9, 2023
b0c29d2
Expanding combinations
saynb Jun 16, 2023
4ab7546
review comments
saynb Jun 23, 2023
88a0dd1
* Explain more on indexed tables. How are duplicates handled
saynb Jun 29, 2023
74c1661
Update Go dependencies (#438)
antoninbas Jul 6, 2023
d76a364
Fixes https://github.com/p4lang/p4runtime/issues/439 (#440)
chrispsommers Jul 6, 2023
be046f3
* Adding categories and properties in p4info
saynb Jul 7, 2023
cd271fd
* Removed GenericTable category from the p4info
saynb Jul 13, 2023
1131a75
Adding space for dummy commit
saynb Jul 21, 2023
eef4daf
Correcting typo
saynb Aug 3, 2023
0e2fb58
Adding dev branches to workflows (#443)
saynb Aug 4, 2023
119bdd6
Merge branch 'main' into generic_table_2
saynb Aug 8, 2023
5797394
Merge branch 'generic-table-dev' of https://github.com/saynb/p4runtim…
saynb Aug 8, 2023
e9e996e
Correcting linter errors
saynb Aug 8, 2023
3a5f4e4
Generating go and py files
saynb Aug 8, 2023
29aab4e
Adding text regarding direct resources as GenericTables in TableEntry
saynb Aug 11, 2023
185fa08
some review comment changes
saynb Aug 19, 2023
090aa0a
Andy review comments
saynb Aug 25, 2023
48f04d9
remove whitespace
saynb Aug 25, 2023
b101dab
* Correcting GenericTable.md according to the p4info
saynb Sep 7, 2023
4d4d9f7
* Removing float from p4info and spec
saynb Sep 7, 2023
89f11d9
* Adding section to P4DataTypeSpec to indicate adding to
saynb Sep 7, 2023
371d184
Moving GenericTable.md to docs
saynb Sep 7, 2023
b4dfa73
Correcting spec for removal of p4_type in generic_type. Adding genera…
saynb Sep 7, 2023
a8ec796
* Shortening the field names in `GenericTable` to remove "genric_table_"
saynb Sep 7, 2023
1c026e4
* Making default_value as bytes
saynb Sep 7, 2023
727bab2
Adding default string value
saynb Sep 7, 2023
7f1a54a
review comments
saynb Sep 7, 2023
2cbd34c
linter error
saynb Sep 7, 2023
9ff6e4e
Review comments
saynb Sep 22, 2023
0fcf0c4
Correcting whitespace errors
saynb Dec 7, 2023
71eef58
Resolving conflicts in spec and proto only
saynb Feb 22, 2024
8bbd503
Updating generated code
saynb Feb 22, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Correcting linter errors
saynb committed Aug 8, 2023
commit e9e996e6229b35d05d571c7ec11285f2ac340fc9
160 changes: 87 additions & 73 deletions docs/v1/P4Runtime-Spec.mdk
Original file line number Diff line number Diff line change
@@ -2951,8 +2951,9 @@ tables {
~ End Prototext

### GenericData
See section [GenericData p4types](#sec-p4data-generic-data) for more info on the info type.
See section [GenericData p4data](#sec-p4types-generic-data) for more info on the runtime type.
See section [GenericData p4types](#sec-p4data-generic-data) for more info on the
info type. See section [GenericData p4data](#sec-p4types-generic-data) for more
info on the runtime type.

# P4 Entity Messages { #sec-p4-entity-msgs}

@@ -4809,7 +4810,8 @@ section on [Extending P4Runtime for non-PSA
Architectures](#sec-extending-p4runtime) for more information.

## `GenericTableEntry`
See section [GenericTableEntry p4runtime](#sec-generic-table-entry) for more info
See section [GenericTableEntry p4runtime](#sec-generic-table-entry) for more
info

# Error Reporting Messages { #sec-error-reporting-messages}

@@ -6319,18 +6321,18 @@ properties, but we may include on in future versions of the API.
## GenericTable p4info { #sec-p4info-generic-table}

`GenericTable` messages are used to map non-PSA P4-externs or non-P4 target-
specific "fixed" features to their implementation in a generic way. The same can be achieved
via `Extern`, but GenericTable provides a structured way in which every feature is
represented as a set of match-fields and data-fields. The data consists of unions
which are similar to actions. One use of GenericTable in a server backend is
with TDI [Table Driven Interface](https://github.com/p4lang/tdi), but targets
can use Generic table to map to their own specific feature implementations as
well.
It defines the following fields
specific "fixed" features to their implementation in a generic way. The same can
be achieved via `Extern`, but GenericTable provides a structured way in which
every feature is represented as a set of match-fields and data-fields. The data
consists of unions which are similar to actions. One use of GenericTable in a
server backend is with TDI [Table Driven
Interface](https://github.com/p4lang/tdi), but targets can use Generic table to
map to their own specific feature implementations as well. It defines the
following fields

* `generic_table_type_id`, an 8-bit unsigned integer which uniquely identifies
the generic_table_type in the context of the architecture.
This value is in the range of `[0x00, 0xff]`.
This value is in the range of `[0x00, 0xff]`.
The ID in the preamble is created as `0x18 + generic_table_type_id + 16 bits
of generated ID by compiler`. The `generic_table_type` depicts a new table
"type" which would have similar properties. The organization of the table
@@ -6360,13 +6362,13 @@ It defines the following fields
a generic-table-type. All tables of one type are grouped under this.

GenericTableInstance
* `preamble`, a `Preamble` message with the ID, name, and alias of this
* `preamble`, a `Preamble` message with the ID, name, and alias of this
GenericTable.

* `generic_match_fields`, a repeated field of type `GenericMatchField` representing
the data to be used to construct the lookup key matched in this table. For
information check the generic_match_fields info in the [Generic Table section]
(#sec-generic-table-entry)
* `generic_match_fields`, a repeated field of type `GenericMatchField`
representing the data to be used to construct the lookup key matched in this
table. For information check the generic_match_fields info in the [Generic
Table section](#sec-generic-table-entry)

* `union_refs`, a repeated `UnionRef` field representing the set of possible
unions for this table. Functionally, it behaves same as that of ActionRefs.
@@ -6410,35 +6412,37 @@ conflict, like bool, then the P4 data type should be used.
* generic_list : Used to define a list of same types. Only allows for a
collection of the same type. It can also be a list of generic_structs.
Members are ordered and duplicates are allowed.
* generic_unordered_set : Used to define a set of same types. It can also be a set
of generic_structs. Members are unordered and duplicates are not allowed.
* generic_unordered_set : Used to define a set of same types. It can also be
a set of generic_structs. Members are unordered and duplicates are not
allowed.
* string : Used to define control plane strings. The max string length is
defined by the size
* enum : String representation with which safe enums are realized
* enum_val : bytes value with which unsafe/serializable enums are defined
* p4_type : This is the same type as P4DataTypeSpec. This helps in achieving
parity with P4 types if the GenericTable is being generated from a P4 extern.
There are a few overlaps like bool, enums, new_type, bitstring. If the
entity is from a P4 extern and a P4 data type exists, then the p4_type is
used. Otherwise, the GenericDataType is used
parity with P4 types if the GenericTable is being generated from a P4
extern. There are a few overlaps like bool, enums, new_type, bitstring.
If the entity is from a P4 extern and a P4 data type exists, then the
p4_type is used. Otherwise, the GenericDataType is used

## `GenericTableEntry` { #sec-generic-table-entry}

GenericTableEntry can be used to program non-PSA externs or non-P4 target-specific
"fixed" features to their implementation in a generic way. This provides an alternative
to `Extern` in a structured way and within p4runtime guidelines and semantics.
The idea has been borrowed from TDI [Table Driven Interface](https://github.com/p4lang/tdi),
that every state can be representated as a table or multiple tables. A table here is any
data structure with one or more entries and each entry can be represented as a set of
key fields and data fields.
Actions in P4 tables behave like unions and that has been borrowed here in GenericTable.
This can be potentially used targets to map to either TDI based targets, or even non-TDI
based targets. If using TDI, then potentially, for every new feature to be added, only
TDI target support and remote client code will be required to make use of that function.
All other middle layers should theoretically remain unchanged.

P4Runtime supports inserting, modifying, deleting and reading GenericTable entries with
the `GenericTableEntry` entity, which has the following fields:
GenericTableEntry can be used to program non-PSA externs or non-P4
target-specific "fixed" features to their implementation in a generic way. This
provides an alternative to `Extern` in a structured way and within p4runtime
guidelines and semantics. The idea has been borrowed from TDI [Table Driven
Interface](https://github.com/p4lang/tdi), that every state can be representated
as a table or multiple tables. A table here is any data structure with one or
more entries and each entry can be represented as a set of key fields and data
fields. Actions in P4 tables behave like unions and that has been borrowed here
in GenericTable. This can be potentially used targets to map to either TDI
based targets, or even non-TDI based targets. If using TDI, then potentially,
for every new feature to be added, only TDI target support and remote client
code will be required to make use of that function. All other middle layers
should theoretically remain unchanged.

P4Runtime supports inserting, modifying, deleting and reading GenericTable
entries with the `GenericTableEntry` entity, which has the following fields:

* `table_id`, which identifies the table instance; the `table_id` is determined
by the P4Info message.
@@ -6465,14 +6469,13 @@ the `GenericTableEntry` entity, which has the following fields:
The `priority` field must be set to a non-zero value if the match key includes a
ternary match (&ie; in the case of PSA if the P4Info entry for the table
indicates that one or more of its match fields has an `OPTIONAL`, `TERNARY` or
`RANGE` match
type) or to zero otherwise. A higher priority number indicates that the entry
must be given higher priority when performing a table lookup. Clients must allow
multiple entries to be added with the same priority value. If a packet can
match multiple entries with the same priority, it is not deterministic in the
data plane which entry a packet will match. If a client wishes to make the
matching behavior deterministic, it must use different priority values for any
pair of table entries that the same packet matches.
`RANGE` match type) or to zero otherwise. A higher priority number indicates
that the entry must be given higher priority when performing a table lookup.
Clients must allow multiple entries to be added with the same priority value.
If a packet can match multiple entries with the same priority, it is not
deterministic in the data plane which entry a packet will match. If a client
wishes to make the matching behavior deterministic, it must use different
priority values for any pair of table entries that the same packet matches.

The `match` and `priority` fields are used to uniquely identify an entry within
a table. Therefore, these fields cannot be modified after the entry has been
@@ -6561,7 +6564,7 @@ build/generic-tables-insert-flow.[svg,png] \
If `default_entry` is true, then the default entry is returned. Match
fields should not be set in this case.
Wildcard read does NOT return default entry.

* Read-only tables: Entries can only be read. Write RPC doesn't work and
`NOT_SUPPORTED` is returned.
* `READ` : The Read RPC. All entries can be read. If no entities are
@@ -6588,7 +6591,7 @@ build/generic-tables-insert-flow.[svg,png] \
If `default_entry` is true, then the default entry is returned. Match
fields should not be set in this case.
Wildcard read does NOT return default entry.

* Calculation tables: Entries can only be read. However different from
Read-only in the sense that there is no defined size of the table since
the possible range of matchfields can be immense. For example, hash
@@ -6613,47 +6616,58 @@ Properties exist at 3 different levels - Table, entry and field (match or union)
Table properties are at table level. A combination of these define a certain
table category. By default, if absent, they are all always false

* Read-only : No Add/Del/Mod work
* Modify-only : Table entries can only be modifed
* Reset-only : Table can only be reset. Either entire table or individual entries.
* Indexed : The entries are ordered. Every entry has an index associated with
* Read-only : No Add/Del/Mod work Modify-only : Table entries can only be
* modifed Reset-only : Table can only be reset. Either entire table or
* individual entries. Indexed : The entries are ordered. Every entry has an
* index associated with
it. Indexed tables can be either of modify-only, read-only, reset-only or
regular tables. If regular tables, then the target is expected to fill up gaps
when deleting and then adding entries again. Duplicate entries can exist or
not depending upon the table restrictions. Duplicate entries cannot be present
in regular tables because there is no way to differentiate between the added
entries.
* Keyless : Only one entry, i.e., default entry exists.
* Calculation : No defined range of key values. For example, hash calculation table
for a set of field values.
* Keyless : Only one entry, &i.e; default entry exists. Calculation : No
* defined range of key values. For example, hash calculation
table for a set of field values.
* Volatile : Data plane can Add/Del/Mod entries. Example, Add-on-miss in PNA

#### Combinations that are possible

|Table Cat name | Read-only | Modify-only | Reset-only | Indexed | Keyless | Calculation | Volatile | Example |
| ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- |
| Regular | False | False | False | False | False | False | T/F | MatchActionTable |
| Regular-In | False | False | False | True | False | False | T/F | MatchActionTable with indexes |

| Read-Only | True | False | False | False | False | False | T/F | Port ID to name map |
| Read-Only-Kl | True | False | False | False | True | False | T/F | Target Efuse information table |
| Read-Only-In | True | False | False | True | False | False | T/F | Virtual port ID to name map |
| Read-Only-Cal | True | False | False | False | False | True | T/F | Hash calc table for field values |

| Modify-Only | False | True | False | False | False | False | T/F | |
| Modify-Only-Kl| False | True | False | False | True | False | T/F | Target configuration table |
| Modify-Only-In| False | True | False | True | False | False | T/F | Counter table |

| Reset-Only | False | False | True | False | False | False | T/F | Port stats |
| Reset-Only-Kl | False | False | True | False | True | False | T/F | Target stats |
| Reset-Only-In | False | False | True | True | False | False | T/F | Virtual port stats |
|Table Cat name | Read-only | Modify-only | Reset-only | Indexed | Keyless |
Calculation | Volatile | Example | | ---- | ---- | ---- |
---- | ---- | ---- | ---- | ---- | ---- | | Regular
| False | False | False | False | False | False | T/F
| MatchActionTable | | Regular-In | False | False |
False | True | False | False | T/F | MatchActionTable with
indexes |

| Read-Only | True | False | False | False | False |
False | T/F | Port ID to name map | | Read-Only-Kl |
True | False | False | False | True | False | T/F
| Target Efuse information table | | Read-Only-In | True | False |
False | True | False | False | T/F | Virtual port ID to
name map | | Read-Only-Cal | True | False | False | False
| False | True | T/F | Hash calc table for field values |

| Modify-Only | False | True | False | False | False |
False | T/F | | | Modify-Only-Kl|
False | True | False | False | True | False | T/F
| Target configuration table | | Modify-Only-In| False | True |
False | True | False | False | T/F | Counter table
| | Reset-Only | False | False | True | False | False |
False | T/F | Port stats | | Reset-Only-Kl |
False | False | True | False | True | False | T/F
| Target stats | | Reset-Only-In | False | False |
True | True | False | False | T/F | Virtual port stats
|

Where,
Kl - Keyless
In - Indexed
Cal - Calculation

In the above examples, Virtual ports have been considered to be an example where they are indexed but ports aren't.
In the above examples, Virtual ports have been considered to be an example
where they are indexed but ports aren't.

### Entry properties