diff --git a/PNA.mdk b/PNA.mdk index a33c5f0..904b56a 100644 --- a/PNA.mdk +++ b/PNA.mdk @@ -902,24 +902,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,72 +957,60 @@ 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} +## Table entry idle timeout {#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 -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. +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 `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 +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 idle +entries, and thus will often use `add_on_miss = true` and +`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 5b7513a..f541b61 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; } -/// Supported range of values for the pna_idle_timeout table properties +// BEGIN:enum_PNA_IdleTimeout_t +/// Supported values for the pna_idle_timeout table property enum PNA_IdleTimeout_t { NO_TIMEOUT, - NOTIFY_CONTROL + NOTIFY_CONTROL, + AUTO_DELETE }; +// END:enum_PNA_IdleTimeout_t // BEGIN:Match_kinds match_kind { @@ -645,6 +648,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. @@ -708,6 +712,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(): //