Overview - 2022.2 English

Vitis Networking P4 User Guide (UG1308)

Document ID
2022.2 English

The runtime drivers provide an API that allows control plane management of both P4 and IP specific elements in an instance of the Vitis™ Networking P4 IP, where P4 elements are elements described by the P4 program and IP specific elements provide additional sources of information and control for a Vitis Networking P4 IP instance.

The runtime drivers supported P4 elements are:

• tables from Match-Action control blocks of a P4 program

The runtime drivers supported IP specific elements are:

• Build Information Reader

• Interrupt Controller

• Control

The P4 table elements from Match-Action control blocks present in a P4 program are implemented using Look-up engines, where the Look-up engines are implemented by a variety of addressable tables (see the Match-Action Engine section of the Target Architecture chapter for more information). The principle operation of the Look-up engine is where a look-up value (called a key) is provided to the Look-up engine (table), which then searches its memory for a match. The Look-up engine then generates an output (called a response), the contents of which depend on whether a match was found.

The runtime drivers provide an API that allows control plane management of tables present in an instance of the Vitis Networking P4 IP. A primary responsibility of the runtime drivers is to populate the contents of the Look-up engine with entries constructed from key and response values specified in the tables of the Match-Action control blocks of a P4 program. The key can be constructed from user defined header input, metadata input and/or internally defined match-action scalars. The response is constructed from an action identifier and action parameters. The action identifier is a binary value used to select the action named in the action list of the match-action control block and the action parameters are specified in the associated action declaration.

The build information reader element allows the control plane to read settings used when configuring the instance of the Vitis Networking P4 IP plus the version of the IP instance.

The interrupt element provides control of triggering inputs to detect ECC related errors for P4 table elements plus internal FIFOs.

The control element allows setting of the packet rate limit margin, control of ECC error injection plus soft reset of Vitis Networking P4 engines within the FPGA.

The runtime drivers are organized in a layered architecture to provide different levels of access for applications. The layers are depicted in the following figure:

Figure 1. Runtime Driver Layer

Detailed information on the driver’s public interfaces can be found in the Runtime Software Driver Documentation located at <{XILINX_VIVADO}/doc/vitis_net_p4/drivers/doc. The functionality offered by the high level API is summarized as follows:

  1. Initialization/configuration
  2. Management of table contents
    1. Table entry inserts
    2. Updates
    3. Deletes
  3. Monitoring of table health (such as ECC error information)
  4. Interrupt control for ECC error information
  5. Build Information Reader to allow reading
    1. IP Version
    2. Settings used to configure the Vitis Networking P4 instance
  6. Control of
    1. Setting the packet rate limit margin
    2. ECC error injection
    3. Soft reset of Vitis Networking P4 engines
  7. Utility functions for ease of use (such as fetch a handle to a given table instance by name)

The administration layer comprises the target driver, the purpose of which is to simplify the initialization and management of all control plane accessible elements in the Vitis Networking P4 design. It achieves this by consuming a configuration data structure that is automatically generated when Vitis Networking P4 is run. The data structure describes the configuration of all control plane elements present in the Vitis Networking P4 design (such as tables). Using this information, the target driver is able to initialize a driver context structure instance for every control plane accessible element in the design. Furthermore, it provides an API that allows these structures to be retrieved by specifying the name of the corresponding control plane element. After one of these context structures has been retrieved (for example, a table), the functions offered by its associated driver can be used.

Use of these APIs is illustrated in the Runtime Driver Examples section of this chapter. The following are key points for the operation of the target driver:

  • When Vitis Networking P4 is run in Vivado Design Suite, a configuration data structure is generated that describes all tables present in the design, this structure is an input to the target driver.
  • During initialization, the target driver consumes the generated configuration structure and uses it to initialize all control plane accessible elements present (both P4 and IP specific elements).
  • During initialization the table driver internally creates an instance of the appropriate low-level CAM driver based on the provided configuration data structure.
  • The set of operations supported for a given table varies depending on the underlying CAM IP with which it was implemented.
  • The table driver functions internally concatenate the action parameters and the action identifier provided by the caller to produce a response. It is this response value that is ultimately passed down into the lower layers.

The low-level CAM drivers provide the same style of interface as the table driver, but with a lower level of abstraction. That is, these drivers require that the action parameters and the action identifier have already been concatenated into a response parameter by the caller. Also, for the Direct (DCAM), TinyBCAM and TinyTCAM tables, APIs have been included as a debug feature to handle storing last key and response values.