Merge pull request p4lang#92 from jfingerh/clarify-add-on-miss-and-ad…

…d-idle-timeout-with-auto-delete

Add description of new value AUTO_DELETE for table property pna_idle_timeout

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<T>(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:
+    <https://p4.org/specs>
+
+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
 

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;
     }
 

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<T>(
     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():
 //