User Extern Declaration - 2022.2 English

Vitis Networking P4 User Guide (UG1308)

Document ID
UG1308
Version
2022.2 English
Revision

The Vitis Networking P4 Architecture definition file (xsa.p4) provides the following declaration:

    extern UserExtern<I, O> {
        UserExtern(bit<16> fixed_latency_in_cycles);
        void apply(in I data_in, out O result);
    }
This is the declaration of an extern object named UserExtern, which Vitis Networking P4 supports as a user customizable extern. In P4, extern object declarations resemble simplified C++ classes:
  • The declaration contains a method with the same name as the declaration itself, such as a constructor.
    • This method is used to instantiate the extern object in the P4 program.
    • It is used to specify the hardware latency of the functionality implemented by the user extern.
  • The declaration contains a method named apply().
    • This method is invoked by the P4 program to pass data between the P4 program and the custom functionality.
  • The declaration uses type specialization, which is similar to C++ template support.
    • When instantiating the extern, the user specifies the type of data shared between the P4 program and the custom functionality.

As mentioned briefly above, a P4 program utilizes this declaration to interact with custom functionality by first creating an instance of UserExtern and then later in the program, invoking the apply() method of the instance.

The following statement shows a sample instantiation of a UserExtern object:

UserExtern<bit<12>,bit<12>>(16) minimal_user_extern_example;

This instantiation describes an interface to some custom functionality that has been named "minimal_user_extern_example," which accepts a 12-bit wide input, produces a 12-bit wide output and executes in hardware with a fixed latency of 16 clock cycles.

The following statement illustrates how the interface to the custom functionality described above is used by the P4 program:

minimal_user_extern_example.apply(input, output);

This statement shows the apply() method of minimal_user_extern_example being invoked. The effect of this statement in the generated Vitis Networking P4 IP is that the value stored in the variable input is presented to the 12-bit wide input of the custom functionality implemented by the user. 16 clock cycles later, the 12-bit result produced by the custom functionality is propagated to the output variable.