+
+
A PSA data plane may support multiple control plane APIs. Some of the
notes in this section apply specifically to the case of the P4Runtime
-API when used to control a PSA device. If you are using
+API when used to control a PSA device. If you are using
a different control plane API to control a PSA device, you should
consult the documentation for that control plane API to learn exactly
-what API it provides to configure your PSA device.
-
-
A PSA data plane implementation that supports the P4Runtime
-API includes software called a “P4Runtime Server” that
+what API it provides to configure your PSA device.
+
+
+
A PSA data plane implementation that supports the P4Runtime
+API includes software called a "P4Runtime Server" that
enables runtime programming of the PSA device from one or more
-“P4Runtime Clients”. For brevity, here we will call a P4Runtime Server
-an “agent”, and a P4Runtime Client a “controller”. A controller may
-control multiple devices with different PSA implementations.
-
-
As mentioned in section 4.1, different PSA
+"P4Runtime Clients". For brevity, here we will call a P4Runtime Server
+an "agent", and a P4Runtime Client a "controller". A controller may
+control multiple devices with different PSA implementations.
+
+
+
As mentioned in Section 4.1, different PSA
implementations are expected to customize the size of the data types
that refer directly to those objects in the data plane, i.e. ports,
-multicast group ids, etc.
-
-
Some PSA implementations are expected to use noticeably fewer
+multicast group ids, etc.
+
+
+
Some PSA implementations are expected to use noticeably fewer
resources for things like table keys and action parameters if the data
plane stores only the fewest number of bits required for values of
these types, for that implementation. For example, an implementation
-that defines PortId_t as bit<6> instead of bit<16>, and can take
+that defines PortId_t as bit<6> instead of bit<16>, and can take
advantage of this difference, could save 10 Mbits of storage in a
-table with a million entries.
-
-
The P4Runtime API uses quantities with bit widths independent
+table with a million entries.
+
+
+
The P4Runtime API uses quantities with bit widths independent
of the target device to hold values of the types
-listed in section 4.1, to simplify the
+listed in Section 4.1, to simplify the
manipulation of these values in the controller and agent software.
For control plane
operations on tables, any trimming or padding of values will be
performed in the agent (usually trimming in the direction from
controller to device, and padding in the direction from device
-to controller).
-
-
There are multiple channels of communication over which such values
+to controller).
+
+
+
There are multiple channels of communication over which such values
might be carried between the controller and the data plane. These
-channels of communication include:
-
-
-- Control plane operations on tables, where values of these types may
-be included as part of the key, or as an action parameter.
+channels of communication include:
+
+
+
+-
+
Control plane operations on tables, where values of these types may
+be included as part of the key, or as an action parameter.
-- Control plane operations on parser value sets, where values of these
-types may be included as part of the key.
+
-
+
Control plane operations on parser value sets, where values of these
+types may be included as part of the key.
-- Packets sent to the CPU (“packet in” from the controller's
-perspective), or received from the CPU (“packet out” from the
-controller's perspective).
+
-
+
Packets sent to the CPU ("packet in" from the controller’s
+perspective), or received from the CPU ("packet out" from the
+controller’s perspective).
-- Fields in a
Digest extern notification message (section
-7.14).
+ -
+
Fields in a Digest extern notification message
+(Section 8.14).
-- Fields in the data contents of a
Register array (section
-7.9).
-
-
-
Note: There may be other channels not listed above.
-
-
For packets between the control plane and the PSA device, there is the
+
+Fields in the data contents of a Register array
+(Section 8.9).
+
+
+
+
+
+
+|
+ Note
+ |
+
+There may be other channels not listed above.
+ |
+
+
+
+
+
For packets between the control plane and the PSA device, there is the
issue that many PSA implementations are expected to restrict P4
programs to have headers with fields with a total length that is a
multiple of 8 bits. To make it possible to define P4 header types
that meet this restriction, and contain values of fields with these
PSA-specific types, and be source-compatible across multiple PSA
-implementations, additional types are defined that contain InHeader in
-their name. For example, PortIdInHeader_t is the same as PortId_t,
+implementations, additional types are defined that contain InHeader in
+their name. For example, PortIdInHeader_t is the same as PortId_t,
except it must be a multiple of 8 bits long, and contain at least as
-many bits as PortId_t does.
-
-
Because these InHeader types are guaranteed to be a multiple of 8 bits long,
+many bits as PortId_t does.
+
+
+
Because these InHeader types are guaranteed to be a multiple of 8 bits long,
you may include any combination of them in a P4 header type
definition, as long as the other fields in the header satisfy the
multiple of 8 bits restriction. The controller or P4 program
generating packets with such headers should fill in any most
-significant “padding” bits with 0. You may do this with a normal
+significant "padding" bits with 0. You may do this with a normal
assignment statement in your P4 program, where the value on the
-right hand side is cast to the wider InHeader type. Similarly,
-casting a value of a wider type such as PortIdInHeader_t to the
-corresponding narrower type PortId_t truncates the excess most
-significant bits as part of the cast.
-
-
Values of type PortId_t have an unusual property in PSA
+right hand side is cast to the wider InHeader type. Similarly,
+casting a value of a wider type such as PortIdInHeader_t to the
+corresponding narrower type PortId_t truncates the excess most
+significant bits as part of the cast.
+
+
+
Values of type PortId_t have an unusual property in PSA
implementations. Because it can make some hardware implementations
more straightforward, the numerical values of fields with type
-PortId_t in the P4 data plane might not be a simple range of values
+PortId_t in the P4 data plane might not be a simple range of values
such as 0 through 31, as one might choose when writing control plane
software for a 32-port device. The agent is expected to implement
numerical translation between controller port id values and data plane
port id values, for each of the channels of communication between the
-controller and data plane described above.
-
-
The file psa.p4 contains an annotation p4runtime_translation on
-the type definition of types PortId_t and PortIdInHeader_t.
+controller and data plane described above.
+
+
+
The file psa.p4 contains an annotation p4runtime_translation on
+the type definition of types PortId_t and PortIdInHeader_t.
This enables the compiler to mark all uses of values of these types
that are accessible from the P4Runtime API, so the agent software
knows that it must translate them, and what kind of translation to
perform. The benefit is that you do not need to put any special
markings on your uses of values of these types throughout your P4
-program.
-
-
The cost of this approach is: if you want to do arithmetic on values
-of these types, you must explicitly cast them to a bit<W>
-type. The psa.p4 include file defines PortIdUint_t as a typedef
-with exactly the same width in bits as type PortId_t, so you can
-cast values of type PortId_t to type PortIdUint_t, and then you
+program.
+
+
+
The cost of this approach is: if you want to do arithmetic on values
+of these types, you must explicitly cast them to a bit<W>
+type. The psa.p4 include file defines PortIdUint_t as a typedef
+with exactly the same width in bits as type PortId_t, so you can
+cast values of type PortId_t to type PortIdUint_t, and then you
can perform all P4 arithmetic operations on the value. The result
-must be explicitly cast back to type PortId_t if you wish to assign
+must be explicitly cast back to type PortId_t if you wish to assign
it to a metadata field with that type. Corresponding types with
-Uint in their name are defined for all PSA types.
-
-
Because of this translation, we recommend that values of type
-PortId_t be treated similarly to values of an enum type.
-Comparing two values of this type for equality or “not equal to” is
+Uint in their name are defined for all PSA types.
+
+
+
Because of this translation, we recommend that values of type
+PortId_t be treated similarly to values of an enum type.
+Comparing two values of this type for equality or "not equal to" is
reasonable, as well as assigning the values to other variables or
parameters of the same type, but nearly any other operations are prone
-to error. When matching values of type PortId_t as part of a table
+to error. When matching values of type PortId_t as part of a table
key, always match a complete value exactly, or wildcard every bit of
-the value (i.e. a ternary match kind with all bits wildcard, or an
-lpm match kind with prefix length 0). If you attempt to do any of
-the following things on a value with type PortId_t or
-PortIdInHeader_t, the numerical translation performed may lead to
-functional errors in your program:
-
-
-- Do a table key match on a subset of the bits, or a range match.
-
-- Compare port values with relational operators like
< or >.
-
-- Compare port values to specific numeric literal values like 0 or
+the value (i.e. a
ternary match kind with all bits wildcard, or an
+lpm match kind with prefix length 0). If you attempt to do any of
+the following things on a value with type PortId_t or
+PortIdInHeader_t, the numerical translation performed may lead to
+functional errors in your program:
+
+
+
+-
+
Do a table key match on a subset of the bits, or a range match.
+
+-
+
Compare port values with relational operators like < or >.
+
+-
+
Compare port values to specific numeric literal values like 0 or
0xff. It is recommended instead to compare their values by using
them as table key fields, or parser value set key fields, against
values installed by the control plane (which have been translated to
the corresponding device-specific value as determined by the
-device's agent software). It is also reasonable to compare port
+device’s agent software). It is also reasonable to compare port
values for equality against the symbolic constant values
-PSA_PORT_CPU or PSA_PORT_RECIRCULATE, which have target-specific
-numeric values.
+PSA_PORT_CPU or PSA_PORT_RECIRCULATE, which have target-specific
+numeric values.
-- Perform arithmetic on the value, and expect to get a value that
+
-
+
Perform arithmetic on the value, and expect to get a value that
corresponds to another port of the device. Some numerical values
may not correspond to any port of the device, and the values
-corresponding to ports need not be consecutive.
-
-
-
The list above is not intended to be exhaustive.
-
-
All of the comments above apply to all types where numerical
+corresponding to ports need not be consecutive.
+
+
+
+
+
The list above is not intended to be exhaustive.
+
+
+
All of the comments above apply to all types where numerical
translation occurs between the controller and the data plane. Below
is a complete list of numeric types planned for numerical translation
-by default in PSA:
-
-
-PortId_t or PortIdInHeader_t
-ClassOfService_t or ClassOfServiceInHeader_t
-
-
-
For the types listed below, no numerical translation occurs by
-default. A PSA
+by default in PSA:
+
+
+
+
For the types listed below, no numerical translation occurs by
+default. A PSA
data plane must support all numerical values from 0 up to the maximum
-value that it supports. Except for Timestamp_t values, the number
+value that it supports. Except for Timestamp_t values, the number
of values supported by the data plane need not be a power of 2.
-Controllers must have a way to discover each PSA device's maximum
-supported value for each of these types.
-
-
-MulticastGroup_t - 0 is a special value that indicates no
+Controllers must have a way to discover each PSA device’s maximum
+supported value for each of these types.
+
+
+
-
-
-
-
TBD: Values of type Timestamp_t are being considered for numerical
-translation in the agent software, between target-specific values, and
-a value with a common unit and 0 value reference across all targets.
-
Note that all of these types have a p4runtime_translation annotation
-in the psa.p4 include file. This is to ensure that when the
+
+Timestamp_t
+
+
+
+
+
+
+|
+ Note
+ |
+
+TBD: Values of type Timestamp_t are being considered for numerical translation in the agent software, between target-specific values, and a value with a common unit and 0 value reference across all targets.
+ |
+
+
+
+
+
Note that all of these types have a p4runtime_translation annotation
+in the psa.p4 include file. This is to ensure that when the
compiler generates a P4Runtime P4Info file from source programs, it
will include in the P4Info file the type specified by the
-p4runtime_translation rather than the target-specific bit width.
+p4runtime_translation rather than the target-specific bit width.
For the same P4 source program, the P4Info file contents are intended
-to be identical for all targets.
-
-
If the type bitwidth specified as the second parameter to the
-p4runtime_translation is different from the device-specific bitwidth
+to be identical for all targets.
+
+
+
If the type bitwidth specified as the second parameter to the
+p4runtime_translation is different from the device-specific bitwidth
(of the underlying type), we expect the P4Runtime server to perform
the appropriate casting. Additionally, more advanced numerical
translation can be enabled at runtime for any type annotated with
-p4runtime_translation, although arbitrary numerical translation is
-only mandated for PortId_t, ClassOfService_t, and their Inheader
+p4runtime_translation, although arbitrary numerical translation is
+only mandated for PortId_t, ClassOfService_t, and their Inheader
variants. To request arbitrary numerical translation for a give type,
the P4Runtime system will expect the URI (first parameter to the
-p4runtime_translation) and the desired mapping.
-
5. Programmable blocks
-
The following declarations provide a template for the programmable
+p4runtime_translation) and the desired mapping.
+
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
while 
.
-
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
,
-and the type 
-
+
-
+
until timestamp 
using the expression 
-(if more than 
bits in size,
-
, and 
, then 
. There is thus no need for
-conditional execution to calculate such elapsed times.
-