src/tools/vppapigen/VPPAPI.md

   1 # VPP API Language    {#api_lang_doc}
   2
   3 The VPP binary API is a message passing API.
   4 The VPP API language is used to define a RPC interface between VPP and its
   5 control plane. The API messages supports shared memory transport and
   6 Unix domain sockets (SOCK_STREAM).
   7
   8 The wire format is essentially that of a network formatted (big-endian) packed C struct.
   9
  10 The VPP API compiler is located in *src/tools/vppapigen* and can currently
  11 compile to JSON or C (used by the VPP binary itself).
  12
  13 ## Language definition
  14
  15 ### Defining a messages
  16
  17 There are 3 types of message exchanges:
  18
  19 * Request/Reply
  20 The client sends a request message and the server replies with a
  21 single reply message. The convention is that the reply message is
  22 named as method_name + \_reply.
  23
  24 * Dump/Detail
  25 The client sends a "bulk" request message to the server, and the
  26 server replies with a set of detail messages. These messages may be of
  27 different type. A dump/detail call must be enclosed in a control ping
  28 block (Otherwise the client will not know the end of the bulk
  29 transmission). The method name must end with method + "\_dump", the
  30 reply message should be named method + "\_details". The exception here
  31 is for the methods that return multiple message types
  32 (e.g. sw_interface_dump). The Dump/Detail methods are typically used
  33 for acquiring bulk information, like the complete FIB table.
  34
  35 * Events
  36 The client can register for getting asynchronous notifications from
  37 the server. This is useful for getting interface state changes, and so
  38 on. The method name for requesting notifications is conventionally
  39 prefixed with "want_". E.g. "want_interface_events". Which
  40 notification types results from an event registration is defined in
  41 the service definition.
  42
  43 A message from a client must include the 'client_index', an opaque
  44 cookie identifying the sender, and a 'context' field to let the client
  45 match request with reply.
  46
  47 An example of a message definition. The client sends the show_version request,
  48 the server replies with the show_version_reply.
  49
  50 The *client_index* and *context* fields are required in all requests.
  51 The *context* is returned by the server and is used by the client to
  52 match up request and reply messages.
  53
  54 ```
  55 define show_version
  56 {
  57   u32 client_index;
  58   u32 context;
  59 };
  60 define show_version_reply
  61 {
  62   u32 context;
  63   i32 retval;
  64   string program [32];
  65   string version [32];
  66   string build_date [32];
  67   /* The final field can be a variable length argument */
  68   string build_directory [];
  69 };
  70
  71 ```
  72
  73 The flags are not used by the clients, but have special meaning
  74 for some of the tracing and debugging of the API.
  75 The *autoreply* flag is a shorthand for a reply message with just a
  76 *retval* field.
  77
  78 ```
  79     define : DEFINE ID '{' block_statements_opt '}' ';'
  80     define : flist DEFINE ID '{' block_statements_opt '}' ';'
  81     flist : flag
  82           | flist flag
  83     flag : MANUAL_PRINT
  84          | MANUAL_ENDIAN
  85          | DONT_TRACE
  86          | AUTOREPLY
  87
  88     block_statements_opt : block_statements
  89     block_statements : block_statement
  90                      | block_statements block_statement
  91     block_statement : declaration
  92                     | option
  93     declaration : type_specifier ID ';'
  94                 | type_specifier ID '[' ID '=' assignee ']' ';'
  95     declaration : type_specifier ID '[' NUM ']' ';'
  96                 | type_specifier ID '[' ID ']' ';'
  97     type_specifier : U8
  98                    | U16
  99                    | U32
 100                    | U64
 101                    | I8
 102                    | I16
 103                    | I32
 104                    | I64
 105                    | F64
 106                    | BOOL
 107                    | STRING
 108     type_specifier : ID
 109 ```
 110
 111
 112 ### Options
 113 The *option* word is used to specify meta information.
 114 The only current use is to specify a semantic version of the .api file itself.
 115
 116 Example:
 117 ```
 118 option version = "1.0.0";
 119 ```
 120
 121 ```
 122
 123     option : OPTION ID '=' assignee ';'
 124     assignee : NUM
 125              | TRUE
 126              | FALSE
 127              | STRING_LITERAL
 128 ```
 129
 130 ### Defining new types
 131
 132 New user defined types are defined just like messages.
 133 A typedef has two forms. It can either define an alias for a
 134 different type (or array).
 135
 136 Example:
 137
 138 ```
 139 typedef u8 ip4_address[4];
 140 typedef u8 ip6_address[16];
 141 ```
 142
 143 Where the above defines two new types *vl_api_ip4_address_t* and
 144 *vl_api_ip6_address_t*. These are aliases for the underlying
 145 u8 array.
 146
 147 In the other form, it is used to specify an abstract data type.
 148
 149 ```
 150 enum address_family {
 151   ADDRESS_IP4 = 0,
 152   ADDRESS_IP6,
 153 };
 154
 155 union address_union {
 156   vl_api_ip4_address_t ip4;
 157   vl_api_ip6_address_t ip6;
 158 };
 159
 160 typedef address {
 161   vl_api_address_family_t af;
 162   vl_api_address_union_t un;
 163 };
 164 ```
 165
 166 Where the new type *vl_api_address_t*
 167
 168 ```
 169     typedef : TYPEDEF ID '{' block_statements_opt '}' ';'
 170     typedef : TYPEDEF declaration
 171 ```
 172
 173
 174 ### Importing Definitions
 175 You can use definitions from other .api files by importing them.
 176 To import another .api's definitions, you add an import statement
 177 to the top of your file:
 178
 179 import "vnet/ip/ip_types.api";
 180
 181 By default you can only use definitions from directly imported .api files.
 182
 183 The API compiler searches for imported files in a set of directories
 184 specified on the API compiler command line using the --includedir flag.
 185 ```
 186 import : IMPORT STRING_LITERAL ';'
 187 ```
 188
 189 ### Comments
 190
 191 The API language uses C style comments.
 192 ```
 193 /* */
 194 //
 195 ```
 196
 197 ### Enumerations
 198 Enums are similar to enums in C.
 199
 200 Every enum definition must contain a constant that maps to zero
 201 as its first element. This is because:
 202
 203 There must be a zero value, so that we can use 0 as a numeric default value.
 204 The zero value needs to be the first element.
 205
 206 As in C, enums can be used as flags or just as numbers.
 207 The on-wire, and in memory representation size of an enum can be specified.
 208 Not all language bindings will support that. The default size is 4 (u32).
 209
 210 Example
 211 ```
 212 enum ip_neighbor_flags
 213 {
 214   IP_API_NEIGHBOR_FLAG_NONE = 0,
 215   IP_API_NEIGHBOR_FLAG_STATIC = 0x1,
 216   IP_API_NEIGHBOR_FLAG_NO_FIB_ENTRY = 0x2,
 217 };
 218 ```
 219
 220 Which generates the vl_api_ip_neighbor_flags_t in the C binding.
 221 In Python that is represented as an IntFlag object
 222 VppEnum.vl_api_ip_neighbor_flags_t.
 223
 224 ```
 225     enum : ENUM ID '{' enum_statements '}' ';'
 226     enum : ENUM ID ':' enum_size '{' enum_statements '}' ';'
 227     enum_size : U8
 228               | U16
 229               | U32
 230     enum_statements : enum_statement
 231                     | enum_statements enum_statement
 232     enum_statement : ID '=' NUM ','
 233                    | ID ','
 234 ```
 235
 236 ### Services
 237 The service statement defines the relationship between messages.
 238 For request/response and dump/details messages it ties the
 239 request with the reply. For events, it specifies which events
 240 that can be received for a given want_* call.
 241
 242 Example:
 243 ```
 244 service {
 245   rpc want_interface_events returns want_interface_events_reply
 246     events sw_interface_event;
 247 };
 248
 249 ```
 250
 251 Which states that the request want_interface_events returns a
 252 want_interface_events_reply and if enabled the client will
 253 receive sw_interface_event messages whenever interface states changes.
 254
 255 ```
 256     service : SERVICE '{' service_statements '}' ';'
 257     service_statements : service_statement
 258                     | service_statements service_statement
 259     service_statement : RPC ID RETURNS NULL ';'
 260                          | RPC ID RETURNS ID ';'
 261                          | RPC ID RETURNS STREAM ID ';'
 262                          | RPC ID RETURNS ID EVENTS event_list ';'
 263     event_list : events
 264                | event_list events
 265     events : ID
 266            | ID ','
 267 ```
 268
 269
 270 ## Types
 271 ### Scalar Value Types
 272
 273 .api type|size|C type|Python type
 274 ---------|----|------|-----------
 275 i8       |   1|i8    |int
 276 u8       |   1|u8    |int
 277 i16      |   2|i16   |int
 278 u16      |   2|u16   |int
 279 i32      |   4|i32   |int
 280 u32      |   4|u32   |int
 281 i64      |   8|i64   |int
 282 u64      |   8|u64   |int
 283 f64      |   8|f64   |float
 284 bool     |   1|bool  |boolean
 285 string   |variable|vl_api_string_t|str
 286
 287 ### User Defined Types
 288 #### vnet/ip/ip_types.api
 289
 290 .api type|size|C type|Python type
 291 ---------|----|------|-----------
 292 vl_api_address_t|20|vl_api_address_t|`<class 'ipaddress.IPv4Address'> or <class 'ipaddress.IPv6Address'>`
 293 vl_api_ip4_address_t|4|vl_api_ip4_address_t|`<class 'ipaddress.IPv4Address'>`
 294 vl_api_ip6_address_t|16|vl_api_ip6_address_t|`<class 'ipaddress.IPv6Address'>`
 295 vl_api_prefix_t|21|vl_api_prefix_t|`<class 'ipaddress.IPv4Network'> or <class 'ipaddress.IPv6Network'>`
 296 vl_api_ip4_prefix_t|5|vl_api_ip4_prefix_t|`<class 'ipaddress.IPv4Network'>`
 297 vl_api_ip6_prefix_t|17|vl_api_ip6_prefix_t|`<class 'ipaddress.IPv6Network'>`
 298 vl_api_ip4_address_with_prefix_t|5|vl_api_ip4_address_with_prefix_t|`<class 'ipaddress.IPv4Interface'>`
 299 vl_api_ip6_address_with_prefix_t|17|vl_api_ip6_address_with_prefix_t|`<class 'ipaddress.IPv6Interface'>`
 300
 301 #### vnet/ethernet/ethernet_types.api
 302 .api type|size|C type|Python type
 303 ---------|----|------|-----------
 304 vl_api_mac_address_t|6|vl_api_mac_address_t|`class 'vpp_papi.MACAddress'>`
 305
 306 #### vnet/interface_types.api
 307 .api type|size|C type|Python type
 308 ---------|----|------|-----------
 309 vl_api_interface_index_t|4|vl_api_interface_index_t|int
 310
 311 ### New explicit types
 312
 313 #### String versus bytes
 314 A byte string with a maximum length of 64:
 315 ```
 316 u8 name[64];
 317 ```
 318 Before the "string" type was added, text string were defined like this.
 319 The implications of that was the user would have to know if the field
 320 represented a \0 ended C-string or a fixed length byte string.
 321 The wire format of the 'string' type is a u32 length
 322
 323 An IPv4 or IPv6 address was previously defined like:
 324 ```
 325 u8 is_ip6;
 326 u8 address[16];
 327 ```
 328
 329 Which made it hard for language bindings to represent the
 330 address as anything but a byte string.
 331 The new explicit address types are shown above.
 332
 333 ## Language generators
 334
 335 The VPP API compiler currently has two output modules. One generating JSON
 336 and one generating C header files that are directly used by the VPP
 337 infrastructure and plugins.
 338
 339 The C/C++, Python, Go Lua, and Java language bindings are generated based
 340 on the JSON files.
 341
 342 ### Future considerations
 343 - [ ] Generate C/C++ (vapi) client code directly from vppapigen
 344 - [ ] Embed JSON definitions into the API server, so dynamic languages
 345   can download them directly without going via the filesystem and JSON
 346   files.