From f55ab08cfcf1c5630b2fe207e077ffaff43e524d Mon Sep 17 00:00:00 2001 From: Andy Fingerhut Date: Sun, 20 Nov 2022 12:26:33 -0500 Subject: [PATCH 1/3] Add description of idle_timeout_with_auto_delete Also clarify some wording in the description of add-on-miss, and remove the old signature in the document, in favor of using Madoko INCLUDE mechanism to include the corresponding section of the pna.p4 include file, so that the document and include file will remain in sync with each other. --- PNA.mdk | 89 ++++++++++++++++++++++++++++++++++++++++++--------------- pna.p4 | 2 ++ 2 files changed, 68 insertions(+), 23 deletions(-) diff --git a/PNA.mdk b/PNA.mdk index a33c5f0..0d3cba9 100644 --- a/PNA.mdk +++ b/PNA.mdk @@ -884,6 +884,8 @@ specification. |-----------------------|------|---------------------------------------| | `pna_idle_timeout` | `PNA_IdleTimeout_t` | Section [#sec-idle-timeout] | |-----------------------|------|---------------------------------------| +| `idle_timeout_with_auto_delete` | `boolean` | Section [#sec-idle-timeout-auto-delete] | +|-----------------------|------|---------------------------------------| ~ A PNA implementation need not support both of a `pna_implementation` @@ -902,24 +904,39 @@ A PNA implementation need not support both `pna_implementation` and ## Tables with add-on-miss capability {#sec-add-on-miss} PNA defines the `add_on_miss` table property. If the value of this -property is `true` for a table, the P4 developer is allowed to define -a default action for the table that calls the `add_entry` extern -function. `add_entry` adds a new entry to the table whose default -action calls the `add_entry` function. The new entry will have the -same key that was just looked up. - -The control plane API is still allowed to add, modify, and delete -entries of such a table, but any entries added via the `add_entry` -function do not require the control plane software to be involved in -any way. It is expected that PNA implementations will be able to -sustain `add_entry` calls at a large fraction of their line rate, but -it need not be at the same packet rate supported for processing -packets that do not call `add_entry`. The new table entry will be -matchable when the next packet is processed that applies this table. +property is `true` for a table `t`, the P4 developer is allowed to +define a default action for `t` that calls the `add_entry` extern +function. + +When `t.apply()` is invoked, `t`'s lookup key is constructed, and the +entries of the table are searched. If there is no match, i.e. the +lookup results in a miss, `t`'s default action is executed. So far, +this is all standard behavior as defined in the P4~16~ language +specification. + +If `t`'s default action makes a call to `add_entry`, it causes a new +entry to be added to the table with the same key that was just looked +up and resulted in a miss, and the action name and action parameters +specified by the parameters of the call to the `add_entry` extern +function. Thus, future packets that invoke `t.apply()` with the same +lookup key will get a match and invoke the specified action (until and +unless this new table entry is removed). The new table entry will be +matchable when the next packet is processed that invoked `t.apply()`. + +Some PNA implementations may allow the control plane software to add, +modify, and delete entries of such a table, but any entries added via +the `add_entry` function do not require the control plane software to +be involved in any way. Other PNA implementations may choose not to +support control plane modification of the entries of an add-on-miss +table. + +It is expected that PNA implementations will be able to sustain +`add_entry` calls at a large fraction of their line rate, but it need +not be at the same packet rate supported for processing packets that +do not call `add_entry`. ~Begin P4Example -extern bool add_entry(string action_name, - in T action_params); +[INCLUDE=pna.p4:add_entry_extern_function] ~End P4Example It is expected that many PNA implementations will restrict @@ -942,17 +959,20 @@ table's default action to be executed. The action will be the one named by the string that is passed as the parameter `action_name`. If the attempt to add a table entry succeeds, the return value is -`true`, otherwise `false`. +`ADD_ENTRY_SUCCESS`, otherwise it will be some other value. PNA +implementations are free to define additional failure reasons other +than `ADD_ENTRY_NOT_DONE`, but it is perfectly acceptable for a PNA +implementation to only support those two possible return values. ## Table entry timeout notification {#sec-idle-timeout} -PNA uses the `pna_idle_timeout` to enable a table implementation send -notifications from the PNA device when a configurable time has passed -since an entry was last matched. The property may take one of two -values -- `NO_TIMEOUT`, and `NOTIFY_CONTROL`. `NO_TIMEOUT` disables -idle timeout support for the table and it is the default value when -the property is not present. `NOTIFY_CONTROL` enables the +PNA defines the table property `pna_idle_timeout` to enable a table to +send notifications from the PNA device when a configurable time has +passed since an entry was last matched. The property may take one of +two values -- `NO_TIMEOUT`, and `NOTIFY_CONTROL`. `NO_TIMEOUT` +disables idle timeout support for the table and it is the default +value when the property is not present. `NOTIFY_CONTROL` enables the notification. A PNA implementation will then generate an API for the control plane to set time-to-live (TTL) values for table entries and if at any time during its lifetime, the table entry is not "hit" (&ie; @@ -1009,6 +1029,29 @@ Restrictions on the TTL values and notifications: ActionProfiles do not support the `pna_idle_timeout` property. Future versions of the specification may remove this restriction. + +## Table entry auto-delete on timeout {#sec-idle-timeout-auto-delete} + +PNA defines the table property `idle_timeout_with_auto_delete` to +enable a table to automatically delete an entry from a table if a +configurable time has passed since the entry was last matched. The +default value of this property is `false` if not specified for a +table. + +PNA implementations may restrict `idle_timeout_with_auto_delete` to be +`true` only for tables that also have `add_on_miss` equal to `true`. + +PNA implementations are expected to be able to perform add-on-miss at +very high rates relative to line rate, and similarly for such +add-on-miss tables, they should be able to perform auto-deletion of +entries in the data plane at a similarly large rate. If a P4 +developer wishes to use the high rate add-on-miss capabilities for a +particular table, it is likely that they do not wish the control plane +to be responsible for keeping up with a high rate of deleting stale +entries, and thus will often use `add_on_miss = true` and +`idle_timeout_with_auto_delete = true` together. + + # Timestamps diff --git a/pna.p4 b/pna.p4 index f40f2f0..23ec0e1 100644 --- a/pna.p4 +++ b/pna.p4 @@ -637,6 +637,7 @@ extern void mirror_packet(MirrorSlotId_t mirror_slot_id, // probably be a parameter that specifies the new entry's initial // expire_time_profile_id. +// BEGIN:add_entry_extern_function // The bit width of this type is allowed to be different for different // target devices. It must be at least a 1-bit wide type. @@ -700,6 +701,7 @@ extern AddEntryErrorStatus_t add_entry( string action_name, in T action_params, in ExpireTimeProfileId_t expire_time_profile_id); +// END:add_entry_extern_function // The following call to add_entry_if(): // From 1c1c72e924cd51ea7ee0369e8549868c0fb5e078 Mon Sep 17 00:00:00 2001 From: Andy Fingerhut Date: Fri, 25 Nov 2022 16:40:24 -0500 Subject: [PATCH 2/3] Remove table property idle_timeout_with_auto_delete Instead, define a new value AUTO_DELETE for table property pna_idle_timeout. --- PNA.mdk | 104 ++++++------------ .../pna-example-tcp-connection-tracking.p4 | 21 ++-- pna.p4 | 5 +- 3 files changed, 49 insertions(+), 81 deletions(-) diff --git a/PNA.mdk b/PNA.mdk index 0d3cba9..904b56a 100644 --- a/PNA.mdk +++ b/PNA.mdk @@ -884,8 +884,6 @@ specification. |-----------------------|------|---------------------------------------| | `pna_idle_timeout` | `PNA_IdleTimeout_t` | Section [#sec-idle-timeout] | |-----------------------|------|---------------------------------------| -| `idle_timeout_with_auto_delete` | `boolean` | Section [#sec-idle-timeout-auto-delete] | -|-----------------------|------|---------------------------------------| ~ A PNA implementation need not support both of a `pna_implementation` @@ -965,81 +963,43 @@ than `ADD_ENTRY_NOT_DONE`, but it is perfectly acceptable for a PNA implementation to only support those two possible return values. -## Table entry timeout notification {#sec-idle-timeout} +## Table entry idle timeout {#sec-idle-timeout} -PNA defines the table property `pna_idle_timeout` to enable a table to -send notifications from the PNA device when a configurable time has -passed since an entry was last matched. The property may take one of -two values -- `NO_TIMEOUT`, and `NOTIFY_CONTROL`. `NO_TIMEOUT` -disables idle timeout support for the table and it is the default -value when the property is not present. `NOTIFY_CONTROL` enables the -notification. A PNA implementation will then generate an API for the -control plane to set time-to-live (TTL) values for table entries and -if at any time during its lifetime, the table entry is not "hit" (&ie; -not selected by any packet lookup) for a lapse of time greater or -equal to its TTL, the device should generate a notification to the -control plane. The rate and mode of how the notifications are -generated and delivered to the control plane are subject to -configuration parameters specified by the control plane API. +PNA defines the table property `pna_idle_timeout` to enable specifying +whether a table should maintain an idle time for each of its entries, +and if so, what the data plane should do when a table entry has not +been matched for a length of time at least its configured idle time. -Example: +The value assigned to `pna_idle_timeout` must be a value of type +`PNA_IdleTimeout_t`: ~Begin P4Example -enum PNA_IdleTimeout_t { - NO_TIMEOUT, - NOTIFY_CONTROL -} - -table t { - action a1 () { ... } - action a2 () { ... } - key = { hdr.f1: exact; } - actions = { a1; a2; } - default_action = a2; - pna_idle_timeout = PNA_IdleTimeout_t.NOTIFY_CONTROL; -} +[INCLUDE=pna.p4:enum_PNA_IdleTimeout_t] ~End P4Example -Restrictions on the TTL values and notifications: - -- It is likely that any hardware implementation will have a limited - number of bits to represent the values, and, since the values are - programmed at runtime, it is the responsibility of the runtime - (P4Runtime or other controller software) to guarantee that the TTL - values can be represented in the device. This can be done by scaling - the values to the number of bits available on the platform, ensuring - that the range of values between different entries are - representable. A PNA implementation should only enable the - programming of such tables, and return an error if the device does - not support the idle timeout at all. - -- If no value is programmed for a table entry, even though the table - has enabled the idle timeout property, the entry will not generate a - notification. - -- PNA does not require a timeout value for a default action entry. The - reason for not making this mandatory in the specification is that - the default action may not have an explicit table entry to - represent it, and also there are no known compelling use cases for a - controller knowing when no misses have occurred for a particular - table for a long time. The default action entry will not be aged - out. - -- Currently, tables implemented using ActionSelectors and - ActionProfiles do not support the `pna_idle_timeout` property. - Future versions of the specification may remove this restriction. - - -## Table entry auto-delete on timeout {#sec-idle-timeout-auto-delete} - -PNA defines the table property `idle_timeout_with_auto_delete` to -enable a table to automatically delete an entry from a table if a -configurable time has passed since the entry was last matched. The -default value of this property is `false` if not specified for a -table. +If the property `pna_idle_timeout` is not specified for a table, its +default value is `NO_TIMEOUT`. Such tables need not maintain an idle +time for any of its table entries, and will not perform any special +action regardless of how long a table entry remains unmatched. + +If the property `pna_idle_timeout` is assigned a value of +`NOTIFY_CONTROL`, the behavior is the same as defined in the Portable +Switch Architecture if a table has its property `psa_idle_timeout` +assigned a value of `NOTIFY_CONTROL`. See the section titled "Table +entry timeout notification" in the PSA specification[^PSA]. + +[^PSA]: The Portable Switch Architecture specification can be found here: + + +If the property `pna_idle_timeout` is assigned a value of +`AUTO_DELETE`, the behavior is similar to the behavior of the value +`NOTIFY_CONTROL`, except that no notification message is generated to +the control plane when an entry's idle time is reached. Instead, the +data plane deletes the table entry. -PNA implementations may restrict `idle_timeout_with_auto_delete` to be -`true` only for tables that also have `add_on_miss` equal to `true`. +PNA implementations may restrict `pna_idle_timeout` to be +`AUTO_DELETE` only for tables that also have `add_on_miss` equal to +`true`. PNA implementations are expected to be able to perform add-on-miss at very high rates relative to line rate, and similarly for such @@ -1047,9 +1007,9 @@ add-on-miss tables, they should be able to perform auto-deletion of entries in the data plane at a similarly large rate. If a P4 developer wishes to use the high rate add-on-miss capabilities for a particular table, it is likely that they do not wish the control plane -to be responsible for keeping up with a high rate of deleting stale +to be responsible for keeping up with a high rate of deleting idle entries, and thus will often use `add_on_miss = true` and -`idle_timeout_with_auto_delete = true` together. +`pna_idle_timeout = PNA_IdleTimeout_t.AUTO_DELETE` together. # Timestamps diff --git a/examples/pna-example-tcp-connection-tracking.p4 b/examples/pna-example-tcp-connection-tracking.p4 index 994aa5a..555d5b1 100644 --- a/examples/pna-example-tcp-connection-tracking.p4 +++ b/examples/pna-example-tcp-connection-tracking.p4 @@ -283,14 +283,19 @@ control MainControlImpl( // from the data plane. add_on_miss = true; - default_idle_timeout_for_data_plane_added_entries = 1; - - // New PNA table property 'idle_timeout_with_auto_delete' is - // similar to 'idle_timeout' in other architectures, except - // that entries that have not been matched for their expire - // time interval will be deleted, without the control plane - // having to delete the entry. - idle_timeout_with_auto_delete = true; + // TODO: Andy Fingerhut added the next line to the example on + // 2022-Apr-26, but this table property is not yet documented + // anywhere. + // default_idle_timeout_for_data_plane_added_entries = 1; + + // Value AUTO_DELETE of table property pna_idle_timeout is new + // in PNA relative to PSA. It is similar to the value + // NOTIFY_CONTROL in the PSA architecture, except that entries + // that have not been matched for their idle time interval + // will be deleted, without the control plane having to delete + // the entry. Also, no notification messages will be sent to + // the control plane when this happens. + pna_idle_timeout = PNA_IdleTimeout_t.AUTO_DELETE; const default_action = ct_tcp_table_miss; } diff --git a/pna.p4 b/pna.p4 index 55198f3..a7f5561 100644 --- a/pna.p4 +++ b/pna.p4 @@ -327,11 +327,14 @@ PassNumberInHeader_t pna_PassNumber_int_to_header (in PassNumber_t x) { return (PassNumberInHeader_t) (PassNumberInHeaderUint_t) (PassNumberUint_t) x; } +// BEGIN:enum_PNA_IdleTimeout_t /// Supported range of values for the pna_idle_timeout table properties enum PNA_IdleTimeout_t { NO_TIMEOUT, - NOTIFY_CONTROL + NOTIFY_CONTROL, + AUTO_DELETE }; +// END:enum_PNA_IdleTimeout_t // BEGIN:Match_kinds match_kind { From 6a57f31ab33448a799ade7328b84b812bcc0dcaa Mon Sep 17 00:00:00 2001 From: Andy Fingerhut Date: Fri, 25 Nov 2022 19:14:40 -0500 Subject: [PATCH 3/3] Minor wording change in comment in pna.p4 --- pna.p4 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pna.p4 b/pna.p4 index a7f5561..62ed14e 100644 --- a/pna.p4 +++ b/pna.p4 @@ -328,7 +328,7 @@ PassNumberInHeader_t pna_PassNumber_int_to_header (in PassNumber_t x) { } // BEGIN:enum_PNA_IdleTimeout_t -/// Supported range of values for the pna_idle_timeout table properties +/// Supported values for the pna_idle_timeout table property enum PNA_IdleTimeout_t { NO_TIMEOUT, NOTIFY_CONTROL,