Support for initial entries

docs/v1/P4Runtime-Spec.mdk

@@ -3043,6 +3043,10 @@ limitation. It is recommended that, for the sake of portability, P4Runtime
 clients do not try to insert additional entries once the size indicated in
 P4Info has been reached.
 
+The `const` field must be `false` in any `INSERT`, `MODIFY`, or
+`DELETE` write request of a table entry.  If it is true, the server
+must reject the operation and return an `INVALID_ARGUMENT` error.
+
 ### Match Format { #sec-match-format}
 
 The bytes fields in the `FieldMatch` message follow the format described in
@@ -3270,10 +3274,13 @@ indirect tables --- tables with an ActionProfile or ActionSelector
 `implementation` property --- to a constant `NoAction` action entry, with the
 hope that it would simplify the implementation of the P4Runtime service.
 
-### Constant Tables
+### Constant Tables { #sec-constant-tables }
 
-Constant tables are defined as tables whose match entries are immutable. They
-are identified by the `is_const_table` flag in P4Info.
+Constant tables are defined as tables whose match entries are
+immutable. They are identified by the table property `const entries`
+in the P4~16~ source code, and the `is_const_table` flag in P4Info.
+For tables declared with the `entries` property, without `const`
+before `entries` see Section [#sec-tables-with-initial-entries].
 
 The only write updates which are allowed for constant tables are `MODIFY`
 operations on direct resources, and the default action (assuming the default
@@ -3293,10 +3300,71 @@ direct resources that are being queried.  Idle timeouts are not supported for
 static entries. If the table requires a priority value for entries, the server
 must populate the `priority` field appropriately, starting at 1 for the lowest
 priority entry and incrementing the value by 1 for each successive entry. Note
-that P4~16~ does not support assigning explicit priorities to static
-entries. When a priority value is required (⪚ for tables including `RANGE`,
-`TERNARY` or `OPTIONAL` matches), it is inferred based on the order in which
-entries appear in the table declaration.
+that P4~16~ does not support assigning explicit priorities to entries
+declared with `const entries`[^ConstEntriesPriorities].  When a
+priority value is required (⪚ for tables including `RANGE`,
+`TERNARY` or `OPTIONAL` matches), it is inferred based on the order in
+which entries appear in the table declaration.
+
+[^ConstEntriesPriorities]: This is not yet explicit in the P4~16~
+    language specification, but will become so if this or a similar
+    clarification is added to it:
+    <https://github.com/p4lang/p4-spec/pull/1259>
+
+### Tables with initial entries { #sec-tables-with-initial-entries }
+
+Tables with initial entries are those identified by the table property
+`entries` in the P4~16~ source code (with no `const` qualifier before
+`entries`), and the `has_initial_entries` flag in P4Info.  For tables
+declared with `const entries`, see Section [#sec-constant-tables].
+
+For every P4 table, it will fall into one of these three categories:
+
+* Neither `entries` nor `const entries` are declared in the source
+  code, and thus `is_const_table` and `has_initial_entries` will both
+  be false.  This will be called a "normal table" in this section
+  below.
+* The table has `const entries` declared, and thus a separate
+  `entries` property is not permitted by the language.  Such a table
+  will have `is_const_table` true and `has_initial_entries` false.
+* The table has `entries` declared, and thus a separate `const
+  entries` property is not permitted by the language.  Such a table
+  will have `is_const_table` false and `has_initial_entries` true.
+
+Since a table may not have both `entries` and `const entries`
+declared, no table will have `is_const_table` true and
+`has_initial_entries` true.
+
+A table with initial entries is allowed to have a mix of some entries
+marked `const`, and other entries not marked `const`.
+
+Entries not marked `const` may be modified or deleted, just as a
+client may do for any entry in a normal table.
+
+Entries marked `const` behave like entries in a constant table,
+&ie; only `MODIFY` operations on direct resources are allowed.
+
+Unlike a table with `is_const_table = true`, a client may insert
+entries into a table with `has_initial_entries = true`, subject to
+capacity constraints on the number of entries supported by the target
+for the table.
+
+The contents of tables with initial entries can be queried by the
+client through a `ReadRequest`.  When reading entries from a table
+with initial entris, the following fields must be set by the server:
+`table_id`, `match`, `action`, `is_default_action`, and `priority` (if
+required).  This is in addition to any direct resources that are being
+queried.  Idle timeouts are not supported for such tables.
+
+If the table requires a priority value for entries, the priorities of
+the initial entries are determined according to the P4~16~ language
+specification.  After the P4 program is initially loaded, the entries
+not marked `const` can be modified at run time just as table entries
+in a normal table can.
+
+The contents of all table entries within `entries` table properties in
+a P4 program can be written to a separate output file by the open
+source `p4c` compiler.  See Section [#sec-entries-files] for details.
 
 ### Wildcard Reads { #sec-table-wildcard-reads}
 
@@ -6598,4 +6666,53 @@ clients are aware that the server is using a larger maximum receive message
 size. The gRPC server running the P4Runtime service must not set the maximum
 receive message size to a value smaller than the default (4MB).
 
+## P4Runtime Entries files { #sec-entries-files }
+
+The open source P4 compiler `p4c` [@p4c] implements an option to
+generate an "entries file", &ie; a file that contains all table
+entries declared via the `entries` table property within the program.
+
+An example P4~16~ program that can be used to demonstrate this
+capability is `table-entries-ternary-bmv2.p4` [@p4cTestProgramForConstEntries]:
+
+    git clone https://github.com/p4lang/p4c
+    cd p4c/testdata/p4_16_samples
+    mkdir tmp
+    p4test --arch v1model \
+        --p4runtime-files tmp/p4info.txt \
+        --p4runtime-entries-files tmp/entries.txt \
+        table-entries-ternary-bmv2.p4
+
+You can replace the `.txt` suffix of the file name `tmp/entries.txt`
+in the example command above with `.json` or `.bin`.  The `.bin`
+format is a binary P4Runtime API protobuf message format.  The `.txt`
+format is the text encoding of the same Protobuf messages.
+
+Target devices are *not* required to use this file.  For example, if a
+target has a P4 compiler back end that encodes all of the necessary
+details from the P4 source program, including the `entries` of tables,
+in a target-specific binary format, then that target might hae no
+reason to generate these entries files.
+
+Some target devices might choose to generates entries files, and also
+to require doing so in order to have a correct implementation.  For
+example, a target runtime implementation might take a target-specific
+binary format for the compiled P4 program that does *not* contain any
+data describing the `entries` of tables, plus the entries file
+generated by p4c, and use the entries file to load the initial entries
+of tables into the device.
+
+The format of the entries file is a sequence of 0 or more `Update`
+messages.  All of them have `type` equal to `INSERT`, and `entity` is
+a `TableEntry` message containing the data for one table entry.  The
+file contains entries for all tables in the P4 program with at least
+one entry defined via an `entries` table property.
+
+Note that for a table with `const entries`, or with `entries` having
+one or more individual entries declared `const`, it would be an error
+for a P4Runtime client to send a `WriteRequest` to a P4Runtime server
+with the contents of the entries file, because the server should
+reject and return an error when attempting to insert entries that are
+immutable at run time.
+
 [BIB]

docs/v1/references.bib

@@ -210,3 +210,13 @@ @ONLINE { ArenaAllocation
     title = "C++ Arena Allocation Guide",
     url = "https://developers.google.com/protocol-buffers/docs/reference/arenas"
 }
+
+@ONLINE { p4c,
+    title = "P4_16 reference compiler",
+    url = "https://github.com/p4lang/p4c"
+}
+
+@ONLINE { p4cTestProgramForConstEntries,
+    title = "P4_16 reference compiler test program table-entries-ternary-bmv2.p4",
+    url = "https://github.com/p4lang/p4c/blob/main/testdata/p4_16_samples/table-entries-ternary-bmv2.p4"
+}