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