docs/developer-guide/p4plugin-developer-guide.rst

   1 .. _p4plugin-dev-guide:
   2
   3 P4 Plugin Developer Guide
   4 =========================
   5
   6 P4 Plugin Architecture
   7 ----------------------
   8
   9 -  **Netconf-Adapter**
  10
  11    -  Responsible for device connection, interface resource collection, and
  12       providing gRPC server information to P4Runtime client.
  13
  14 -  **Runtime**
  15
  16    -  Implements a gRPC client, more precisely a P4Runtime client, that provides
  17       several RPCs for users at runtime.
  18    -  Supports setting and retrieving forwarding pipeline configuration
  19       dynamically; adding or removing multiple devices; setting up a controller
  20       cluster; adding, modifying, or deleting table entries; adding, modifying,
  21       or deleting action profile members, adding, modifying, or deleting action
  22       profile groups, and setting packet-in/packet-out.
  23
  24
  25 APIs in P4 Plugin
  26 -----------------
  27
  28 The sections below give details about the configuration settings for
  29 the components that can be configured.
  30
  31 Netconf Adapter
  32 ~~~~~~~~~~~~~~~
  33
  34 API Description
  35 ^^^^^^^^^^^^^^^
  36
  37 -  p4plugin/adapter/netconf-adapter/api/src/main/yang/p4plugin-netconf-adapter-api.yang
  38
  39    -  **write-inventory**
  40
  41       -  Write the collecting interface resource to inventory data store.
  42
  43    -  **read-inventory**
  44
  45       -  Acquire the interface resource from inventory data store.
  46
  47
  48 Runtime
  49 ~~~~~~~
  50
  51 API Description
  52 ^^^^^^^^^^^^^^^
  53
  54 -  p4plugin/runtime/api/src/main/yang/p4plugin-device.yang
  55
  56    -  **add-device**
  57
  58       -  Add a P4 device. Users need to provide node ID, device ID, gRPC server
  59          address, configuration file path, and runtime file path as input.
  60
  61          In the following scenario, users must catch and handle the exception:
  62          If node ID or P4 target address (device ID and gRPC server address)
  63          already exists, parsing the configuration file and runtime file causes
  64          an exception, such as IOException.
  65
  66    -  **remove-device**
  67
  68       -  Remove a P4 device from local list.
  69
  70    -  **query-devices**
  71
  72       -  Query how many devices are there currently, and return a list that
  73          contains node IDs.
  74
  75    -  **connect-to-device**
  76
  77       -  Open the stream channel, which is for packet-in and packet-out, and
  78          send master arbitration update message right after the stream
  79          channel is created. The returned value is the connection state.
  80
  81    -  **set-pipeline-config**
  82
  83       -  Set forwarding pipeline configuration to a specific device through the
  84          gRPC channel, and input the node ID associated with the device.
  85
  86    -  **get-pipeline-config**
  87
  88       -  Get forwarding pipeline configuration, input the node ID associated,
  89          and return a string that is the content of the runtime file.
  90
  91
  92 -  p4plugin/core/api/src/main/yang/p4plugin-runtime.yang
  93
  94    -  **add-table-entry**
  95
  96       -  Add entry to a specific device. Users must provide parameters such as
  97          table name; action name and action parameters; match field name and
  98          match field value; and so on. The node ID must also be provided.
  99
 100    -  **modify-table-entry**
 101
 102       -  Modify an existing entry to a specific device. The parameters are
 103          the same as the ``add-table-entry`` method.
 104
 105    -  **delete-table-entry**
 106
 107       -  Delete an existing entry from a specific device. When deleting entries,
 108          users only need to provide table name and match field information;
 109          no action information is required.
 110
 111    -  **add-action-profile-member**
 112
 113       -  Add a member to a profile. User must provide member ID.
 114
 115    -  **modify-action-profile-member**
 116
 117       -  Modify a member that already exists in a profile.
 118
 119    -  **delete-action-profile-member**
 120
 121       -  Delete a member that already exists in a profile.
 122
 123    -  **add-action-profile-group**
 124
 125       -  Add a group to a profile.
 126
 127    -  **modify-action-profile-group**
 128
 129       -  Modify a group that already exists in a profile.
 130
 131    -  **delete-action-profile-group**
 132
 133       -  Delete a group that already exists in a profile.
 134
 135    -  **read-table-entry**
 136
 137       -  Read an entry from a specific device, input node ID, and table name;
 138          and output a JSON string. The returned value is Base64 encoded.
 139
 140    -  **read-action-profile-member**
 141
 142       -  Read the members of an action profile, input node ID, and action
 143          profile name; and output a JSON string. The returned value is Base64
 144          encoded.
 145
 146    -  **read-action-profile-group**
 147
 148       -  Read the action profile groups of an action profile, input node ID
 149          and action profile name; and output a JSON string. The returned value
 150          is Base64 encoded.
 151
 152
 153 -  p4plugin/core/api/src/main/yang/p4plugin-packet.yang
 154
 155    -  **p4-transmit-packet**
 156
 157       -  Transmit a packet to a specific P4 device.
 158
 159    -  **p4-packet-received**
 160
 161       -  Receive a packet from P4 device.
 162
 163
 164 -  p4plugin/core/api/src/main/yang/p4plugin-cluster.yang
 165
 166    -  **set-election-id**
 167
 168       -  Set the election ID. For more information about the election IDs and
 169          and their meaning, refer to the following URL:
 170          https://github.com/p4lang/PI/blob/dc2f4c6cce86e310055677c8b18831fd8f6d1f2c/proto/docs/arbitration.md
 171
 172          When a new election ID is set, it sends master arbitration update
 173          messages to all devices it connected.
 174
 175    -  **get-election-id**
 176
 177       -  Get current election ID.
 178
 179
 180 Sample Configurations
 181 ---------------------
 182
 183 1. Write Inventory
 184 ~~~~~~~~~~~~~~~~~~
 185
 186 **REST API** : *POST /restconf/operations/p4plugin-netconf-adapter-api:write-inventory*
 187
 188 **Sample JSON Data**
 189
 190 .. code:: json
 191
 192     {
 193          "input": {
 194
 195         }
 196     }
 197
 198
 199 2. Add device
 200 ~~~~~~~~~~~~~
 201
 202 **REST API** : *POST /restconf/operations/p4plugin-device:add-device*
 203
 204 **Sample JSON Data**
 205
 206 .. code:: json
 207
 208     {
 209         "input": {
 210             "nid": "node0",
 211              "config-file-path": "/home/opendaylight/p4lang/behavioral-model/mininet/simple_router.json",
 212              "runtime-file-path": "/home/opendaylight/p4lang/behavioral-model/mininet/simple_router.proto.txt",
 213              "did": "0",
 214              "ip": "10.42.94.144",
 215              "port": "50051"
 216         }
 217     }
 218
 219
 220 3. Connect to device
 221 ~~~~~~~~~~~~~~~~~~~~
 222
 223 **REST API** : *POST /restconf/operations/p4plugin-device:connect-to-device*
 224
 225 **Sample JSON Data**
 226
 227 .. code:: json
 228
 229     {
 230         "input": {
 231              "nid": "node0"
 232          }
 233     }
 234
 235
 236 4. Set pipeline config
 237 ~~~~~~~~~~~~~~~~~~~~~~
 238
 239 **REST API** : *POST /restconf/operations/p4plugin-device:set-pipeline-config*
 240
 241 **Sample JSON Data**
 242
 243 .. code:: json
 244
 245     {
 246         "input": {
 247             "nid": "node0"
 248         }
 249     }
 250
 251 5. Add table entry
 252 ~~~~~~~~~~~~~~~~~~
 253
 254 **REST API** : *POST /restconf/operations/p4plugin-runtime:add-table-entry*
 255
 256 **Sample JSON Data**
 257
 258 .. code:: json
 259
 260     {
 261         "input": {
 262             "action-name": "set_nhop",
 263              "action-param": [
 264                  {
 265                      "param-name": "nhop_ipv4",
 266                      "param-value": "10.0.0.10"
 267                  },
 268                  {
 269                        "param-name": "port",
 270                      "param-value": "1"
 271                  }
 272              ],
 273              "priority": "0",
 274              "controller-metadata": "0",
 275              "table-name": "ipv4_lpm",
 276              "field": [
 277                  {
 278                      "field-name": "ipv4.dstAddr",
 279                      "lpm-value": "10.0.0.0",
 280                      "prefix-len": "24"
 281                  }
 282              ],
 283              "nid": "node0"
 284         }
 285     }
 286
 287 6. Read table entry
 288 ~~~~~~~~~~~~~~~~~~~
 289
 290 **REST API** : *POST /restconf/operations/p4plugin-runtime:read-table-entry*
 291
 292 **Sample JSON Data**
 293
 294 .. code:: json
 295
 296     {
 297         "input": {
 298             "table-name": "ipv4_lpm",
 299              "nid": "node0"
 300         }
 301     }