Data plane writable per table entry state v1

p4-16/spec/P4-16-spec.mdk

@@ -6342,14 +6342,15 @@ starting with actions.
 ~ Figure { #fig-actions; caption: "Actions contain code and data. The code is in the P4 program, while the data is provided in the table entries, typically populated by the control plane. Other parameters are bound by the data plane." }
 ![actions]
 ~
-[actions]: figs/actions.png { width: 8cm; page-align: here }
+[actions]: figs/P4-actions.png { width: 10cm; page-align: here }
 
 Actions are code fragments that can read and write the data being
 processed. Actions may contain data values that can be written by the
-control plane and read by the data plane. Actions are the main
-construct by which the control plane can dynamically influence the
-behavior of the data plane. Figure [#fig-actions] shows the abstract
-model of an `action`.
+control plane and read by the data plane. Actions may also contain
+data values that are initialized by the control plane, and read and
+written by the data plane. Actions are the main construct by which the
+control plane can dynamically influence the behavior of the data
+plane. Figure [#fig-actions] shows the abstract model of an `action`.
 
 ~ Begin P4Grammar
 [INCLUDE=grammar.mdk:actionDeclaration]
@@ -6358,23 +6359,71 @@ model of an `action`.
 Syntactically actions resemble functions with no return
 value. Actions may be declared within a control block; in this case
 they can only be used within instances of that control block.
+Actions may also be declared at the top level of a P4 program.
 
-The following example shows an action declaration:
+The following examples show action declarations:
 ~ Begin P4Example
 action Forward_a(out bit<9> outputPort, bit<9> port) {
     outputPort = port;
 }
+
+action Forward_with_count(out bit<9> outputPort, bit<9> port, rmw bit<32> count) {
+    outputPort = port;
+    count = count + 1;
+}
 ~ End P4Example
 
-Action parameters may not have `extern` types. Action parameters that
-have no direction (e.g., `port` in the previous example) indicate
-"action data." All such parameters must appear at the end of the
-parameter list. When used in a match-action table (see Section
-[#sec-table-action-list]), these parameters will be provided by the
-table entries (e.g., as specified by the control plane, the
-`default_action` table property, or the `entries` table
+Action parameters may not have `extern` types.
+
+Action parameters that have no direction (e.g., `port` in the previous
+examples) indicate "action data" that is read-only in the data plane.
+When used in a match-action table (see Section
+[#sec-table-action-list]), the values of these parameters will be
+provided by the table entries (e.g., as specified by the control
+plane, the `default_action` table property, or the `entries` table
 property).
 
+Consider action `a1` with parameter `p1` that is declared
+directionless. Then:
+
++ There is an independent value of `p1` for each table entry that has
+  `a1` as its action.
++ `p1` may not be assigned a value in the body of `a1`.
++ If `p1` is passed as an argument to another action `a2`
+  corresponding to parameter `p2` of action `a2`, then `p2` must have
+  direction `in`, or be directionless.
++ Similarly if `p1` is passed as an argument to an extern function or
+  extern method `f1` as parameter `p2`: `p2` must have direction `in`,
+  or be directionless.
+
+Action parameters declared with `rmw` before them (e.g., `count` in
+the action `Forward_with_count`) indicate action data that can be
+modified in the P4 code.  The initial value of these parameters will
+be provided by the table entries (e.g. as specified by the control
+plane, the `default_action` table property, or the `entries` table
+property), but after that its value may be modified by the action when
+the action is invoked.
+
+Consider action `a1` with parameter `p1` that is declared `rmw`.
+Then:
+
++ There is separate storage for holding a value of `p1` for each table
+  entry that has `a1` as its action.
++ `p1` may be assigned a value in the body of `a1`, perhaps multiple
+  times.
++ If `p1` is passed as an argument to another action `a2`
+  corresponding to parameter `p2` of action `a2`, then `p2` may be
+  directionless, or have any direction, but it is an error if `p2` is
+  declared `rmw`.
++ If `p1` is passed as an argument to an extern function or extern
+  method `f1` as parameter `p2`, then `p2` may be directionless, or
+  have any direction.
+
+All parameters that are either directionless or declared `rmw` must
+appear after any parameters with a direction.  Directionless
+parameters and those declared `rmw` can appear in any order relative
+to each other.
+
 The body of an action consists of a sequence of statements and
 declarations.  No `table`, `control`, or `parser` applications can
 appear within actions.
@@ -6394,6 +6443,9 @@ Actions can be executed in two ways:
   parameters. In this case, the directionless parameters behave like `in`
   parameters.
 
+Actions with parameters declared as `rmw` may not be executed
+explicitly, only implicitly.
+
 ## Tables { #sec-tables }
 
 ~ Figure { #fig-maudataflow; caption: "Match-Action Unit Dataflow." }

p4-16/spec/figs/P4-actions.drawio

@@ -0,0 +1,75 @@
+<mxfile host="app.diagrams.net" modified="2023-04-01T20:11:09.833Z" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36" etag="exPne3oivc5jOSmiOkaR" version="21.1.2" type="google">
+  <diagram name="Page-1" id="BCE2OU4Sl7W31KCo3rTn">
+    <mxGraphModel grid="1" page="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+        <mxCell id="Qf5rXhnkIaSK_ay8ISDB-22" value="" style="rounded=0;whiteSpace=wrap;html=1;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="310" y="280" width="380" height="150" as="geometry" />
+        </mxCell>
+        <mxCell id="Qf5rXhnkIaSK_ay8ISDB-20" value="&lt;font style=&quot;font-size: 12px;&quot;&gt;in/inout/out parameters&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;strokeWidth=2;strokeColor=none;" vertex="1" parent="1">
+          <mxGeometry x="300" y="230" width="80" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="Qf5rXhnkIaSK_ay8ISDB-9" value="&lt;font style=&quot;font-size: 12px;&quot;&gt;directionless parameters&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;strokeWidth=2;strokeColor=none;" vertex="1" parent="1">
+          <mxGeometry x="450" y="230" width="80" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="Qf5rXhnkIaSK_ay8ISDB-2" value="&lt;font style=&quot;font-size: 18px;&quot;&gt;action code&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="320" y="290" width="160" height="130" as="geometry" />
+        </mxCell>
+        <mxCell id="Qf5rXhnkIaSK_ay8ISDB-3" value="" style="shape=flexArrow;endArrow=classic;html=1;rounded=0;fillColor=#66B2FF;strokeWidth=2;endWidth=14.285714285714286;endSize=4.714285714285714;width=20;" edge="1" parent="1">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="490" y="320" as="sourcePoint" />
+            <mxPoint x="450" y="320" as="targetPoint" />
+            <Array as="points" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="Qf5rXhnkIaSK_ay8ISDB-4" value="&lt;font style=&quot;font-size: 14px;&quot;&gt;action data (read-only from data plane)&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="490" y="290" width="100" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="Qf5rXhnkIaSK_ay8ISDB-5" value="&lt;font style=&quot;font-size: 14px;&quot;&gt;action data (writable from data plane)&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="580" y="360" width="100" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="Qf5rXhnkIaSK_ay8ISDB-7" value="" style="shape=flexArrow;endArrow=classic;html=1;rounded=0;fillColor=#66B2FF;strokeWidth=2;endWidth=18.285714285714285;endSize=5.902857142857143;width=20;entryX=0.5;entryY=0;entryDx=0;entryDy=0;exitX=0.306;exitY=1.086;exitDx=0;exitDy=0;exitPerimeter=0;" edge="1" parent="1" source="Qf5rXhnkIaSK_ay8ISDB-8" target="Qf5rXhnkIaSK_ay8ISDB-4">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="540" y="240" as="sourcePoint" />
+            <mxPoint x="460" y="330" as="targetPoint" />
+            <Array as="points" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="Qf5rXhnkIaSK_ay8ISDB-8" value="&lt;font style=&quot;font-size: 18px;&quot;&gt;control plane&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;strokeWidth=2;strokeColor=none;" vertex="1" parent="1">
+          <mxGeometry x="480" y="190" width="200" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="Qf5rXhnkIaSK_ay8ISDB-14" value="" style="shape=flexArrow;endArrow=classic;startArrow=classic;html=1;rounded=0;fillColor=#66B2FF;strokeWidth=2;endWidth=14.285714285714286;endSize=4.714285714285714;startWidth=14.285714285714286;startSize=4.714285714285714;width=20;exitX=0;exitY=0.5;exitDx=0;exitDy=0;" edge="1" parent="1" source="Qf5rXhnkIaSK_ay8ISDB-5">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="490" y="380" as="sourcePoint" />
+            <mxPoint x="450" y="390" as="targetPoint" />
+            <Array as="points" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="Qf5rXhnkIaSK_ay8ISDB-16" value="&lt;font style=&quot;font-size: 12px;&quot;&gt;parameters declared &#39;rmw&#39;&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;strokeWidth=2;strokeColor=none;" vertex="1" parent="1">
+          <mxGeometry x="640" y="220" width="70" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="Qf5rXhnkIaSK_ay8ISDB-17" value="" style="shape=flexArrow;endArrow=classic;html=1;rounded=0;fillColor=#66B2FF;strokeWidth=2;endWidth=18.285714285714285;endSize=5.902857142857143;width=20;entryX=0.5;entryY=0;entryDx=0;entryDy=0;exitX=0.75;exitY=1;exitDx=0;exitDy=0;" edge="1" parent="1" source="Qf5rXhnkIaSK_ay8ISDB-8" target="Qf5rXhnkIaSK_ay8ISDB-5">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="621" y="226.5" as="sourcePoint" />
+            <mxPoint x="620" y="293.5" as="targetPoint" />
+            <Array as="points" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="Qf5rXhnkIaSK_ay8ISDB-18" value="" style="shape=flexArrow;endArrow=classic;startArrow=classic;html=1;rounded=0;fillColor=#66B2FF;strokeWidth=2;endWidth=14.285714285714286;endSize=4.714285714285714;startWidth=14.285714285714286;startSize=4.714285714285714;width=20;" edge="1" parent="1" target="Qf5rXhnkIaSK_ay8ISDB-2">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="400" y="220" as="sourcePoint" />
+            <mxPoint x="460" y="400" as="targetPoint" />
+            <Array as="points" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="Qf5rXhnkIaSK_ay8ISDB-19" value="&lt;font style=&quot;font-size: 18px;&quot;&gt;data plane&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;strokeWidth=2;strokeColor=none;" vertex="1" parent="1">
+          <mxGeometry x="340" y="190" width="120" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="Qf5rXhnkIaSK_ay8ISDB-23" value="&lt;font style=&quot;font-size: 18px;&quot;&gt;action&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;strokeWidth=2;strokeColor=none;" vertex="1" parent="1">
+          <mxGeometry x="240" y="340" width="60" height="30" as="geometry" />
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>

p4-16/spec/figs/README.md

@@ -1,11 +1,46 @@
+# Notes on drawing files
+
 This directory contains files in PNG format of the figures in the
 P4_16 language specification.
 
-They were created from the figures in this PowerPoint file, also in
+
+## PowerPoint format figures
+
+Most were created from the figures in this PowerPoint file, also in
 this repository:
 + p4-16/discussions/P4-16-draft-spec.pptx
 
-If you wish to edit a figure, or create a new one similar to an
-existing one, it is recommended to edit and check in a new version of
-the PowerPoint file above, and generate a PNG version to add to this
-directory.
+If you wish to edit a figure in PowerPoint format, or create a new
+PowerPoint format figure similar to an existing one, it is recommended
+to edit and check in a new version of the PowerPoint file above, and
+generate a PNG version to add to this directory.
+
+
+## draw.io format figures
+
+The web site:
+
++ https://draw.io
+
+which may redirect to:
+
++ https://app.diagrams.net
+
+has a free web application for editing figures, similar in style to
+Visio, Omnigraffle, and the drawing capabilities of Powerpoint.
+
+If you use it to create a drawing, it is good to save the source file
+of the drawing.  I believe the default format used is called an
+"mxfile", which looks a lot like an XML file with a particular schema.
+
+To include an image in a Madoko document, PNG format is a reasonable
+choice.  To create a PNG file of a drawing, select the menu item
+
++ File -> Export As -> PNG...
+
+Another window appears when you choose that item.  It includes several
+options, one of which is "Include a copy of my diagram" with a check
+box before it.  I have found that at least on an Ubuntu 20.04 Linux
+system with Madoko and TeX software installed using the
+`setup-for-ubuntu-linux.sh` script, if you create a PNG file with that
+box checked, running TeX will fail with an error message.