JSON Description of User Externs - 2022.2 English - UG1308

The P4 and C++ source files are a matched pair, that is, the P4 file defines an instance of UserExtern and the C++ file defines a software model for this instance. The two files are connected via the JSON file emitted by the P4 compiler. It is important to understand this portion of the compiler's output and how it is used by the behavioral model for correctly implementing the custom extensions needed to describe the behavior of a UserExtern instance.

When compiled, the JSON file will contain two sections relating to each UserExtern present in the P4 design. The first is an entry in the "extern_instances" JSON array, which describes the declaration of the instance as follows:

  "extern_instances" : [
    {
      "name" : "Pipeline.minimal_user_extern_example",
      "type" : "minimal_user_extern_example",
      "id" : 0,
      "source_info" : {
        "filename" : "user_externs.p4",
        "line" : 90,
        "column" : 36,
        "source_fragment" : "minimal_user_extern_example"
      },
      "fixed_latency" : 16,
      "input_width" : 12,
      "output_width" : 12
    }
  ]

The second is an entry in the "actions" JSON array describing the invocation of the instance's apply() method as follows:

    {
      "name" : "act_1",
      "id" : 2,
      "runtime_data" : [],
      "primitives" : [
        {
          "op" : "_minimal_user_extern_example_apply",
          "parameters" : [
            {
              "type" : "extern",
              "value" : "Pipeline.minimal_user_extern_example"
            },
            {
              "type" : "field",
              "value" : ["switch_metadata_t", "input"]
            },
            {
              "type" : "field",
              "value" : ["scalars", "output"]
            }
          ],
          "source_info" : {
            "filename" : "user_externs.p4",
            "line" : 111,
            "column" : 5,
            "source_fragment" : "minimal_user_extern_example.apply(input, output)"
          }
        }
      ]
    }

The behavioral model uses these definitions to locate the C++ modeling code to execute. The first section is used by the model to identify the C++ class which models a given instance of UserExtern. After finding the correct class, the model allocates an instance of it. The second section is used by the model to simulate the behavior of the apply() method. It tells the model how to locate the instance of the C++ class mentioned previously and what parameters its apply() method accepts.

Of these outputs, the description of the data types of the parameters to the apply() method (indicated with bold text in the code) are the most important to be aware of, because the C++ model of the apply() method needs to use corresponding data types.