diff options
Diffstat (limited to 'src/tools')
| -rw-r--r-- | src/tools/vppapigen/VPPAPI.md | 346 | ||||
| -rw-r--r-- | src/tools/vppapigen/VPPAPI.rst | 404 |
2 files changed, 404 insertions, 346 deletions
diff --git a/src/tools/vppapigen/VPPAPI.md b/src/tools/vppapigen/VPPAPI.md deleted file mode 100644 index df211d866a0..00000000000 --- a/src/tools/vppapigen/VPPAPI.md +++ /dev/null @@ -1,346 +0,0 @@ -# VPP API Language {#api_lang_doc} - -The VPP binary API is a message passing API. -The VPP API language is used to define a RPC interface between VPP and its -control plane. The API messages supports shared memory transport and -Unix domain sockets (SOCK_STREAM). - -The wire format is essentially that of a network formatted (big-endian) packed C struct. - -The VPP API compiler is located in *src/tools/vppapigen* and can currently -compile to JSON or C (used by the VPP binary itself). - -## Language definition - -### Defining a messages - -There are 3 types of message exchanges: - -* Request/Reply -The client sends a request message and the server replies with a -single reply message. The convention is that the reply message is -named as method_name + \_reply. - -* Dump/Detail -The client sends a "bulk" request message to the server, and the -server replies with a set of detail messages. These messages may be of -different type. A dump/detail call must be enclosed in a control ping -block (Otherwise the client will not know the end of the bulk -transmission). The method name must end with method + "\_dump", the -reply message should be named method + "\_details". The exception here -is for the methods that return multiple message types -(e.g. sw_interface_dump). The Dump/Detail methods are typically used -for acquiring bulk information, like the complete FIB table. - -* Events -The client can register for getting asynchronous notifications from -the server. This is useful for getting interface state changes, and so -on. The method name for requesting notifications is conventionally -prefixed with "want_". E.g. "want_interface_events". Which -notification types results from an event registration is defined in -the service definition. - -A message from a client must include the 'client_index', an opaque -cookie identifying the sender, and a 'context' field to let the client -match request with reply. - -An example of a message definition. The client sends the show_version request, -the server replies with the show_version_reply. - -The *client_index* and *context* fields are required in all requests. -The *context* is returned by the server and is used by the client to -match up request and reply messages. - -``` -define show_version -{ - u32 client_index; - u32 context; -}; -define show_version_reply -{ - u32 context; - i32 retval; - string program [32]; - string version [32]; - string build_date [32]; - /* The final field can be a variable length argument */ - string build_directory []; -}; - -``` - -The flags are not used by the clients, but have special meaning -for some of the tracing and debugging of the API. -The *autoreply* flag is a shorthand for a reply message with just a -*retval* field. - -``` - define : DEFINE ID '{' block_statements_opt '}' ';' - define : flist DEFINE ID '{' block_statements_opt '}' ';' - flist : flag - | flist flag - flag : MANUAL_PRINT - | MANUAL_ENDIAN - | DONT_TRACE - | AUTOREPLY - - block_statements_opt : block_statements - block_statements : block_statement - | block_statements block_statement - block_statement : declaration - | option - declaration : type_specifier ID ';' - | type_specifier ID '[' ID '=' assignee ']' ';' - declaration : type_specifier ID '[' NUM ']' ';' - | type_specifier ID '[' ID ']' ';' - type_specifier : U8 - | U16 - | U32 - | U64 - | I8 - | I16 - | I32 - | I64 - | F64 - | BOOL - | STRING - type_specifier : ID -``` - - -### Options -The *option* word is used to specify meta information. -The only current use is to specify a semantic version of the .api file itself. - -Example: -``` -option version = "1.0.0"; -``` - -``` - - option : OPTION ID '=' assignee ';' - assignee : NUM - | TRUE - | FALSE - | STRING_LITERAL -``` - -### Defining new types - -New user defined types are defined just like messages. -A typedef has two forms. It can either define an alias for a -different type (or array). - -Example: - -``` -typedef u8 ip4_address[4]; -typedef u8 ip6_address[16]; -``` - -Where the above defines two new types *vl_api_ip4_address_t* and -*vl_api_ip6_address_t*. These are aliases for the underlying -u8 array. - -In the other form, it is used to specify an abstract data type. - -``` -enum address_family { - ADDRESS_IP4 = 0, - ADDRESS_IP6, -}; - -union address_union { - vl_api_ip4_address_t ip4; - vl_api_ip6_address_t ip6; -}; - -typedef address { - vl_api_address_family_t af; - vl_api_address_union_t un; -}; -``` - -Where the new type *vl_api_address_t* - -``` - typedef : TYPEDEF ID '{' block_statements_opt '}' ';' - typedef : TYPEDEF declaration -``` - - -### Importing Definitions -You can use definitions from other .api files by importing them. -To import another .api's definitions, you add an import statement -to the top of your file: - -import "vnet/ip/ip_types.api"; - -By default you can only use definitions from directly imported .api files. - -The API compiler searches for imported files in a set of directories -specified on the API compiler command line using the --includedir flag. -``` -import : IMPORT STRING_LITERAL ';' -``` - -### Comments - -The API language uses C style comments. -``` -/* */ -// -``` - -### Enumerations -Enums are similar to enums in C. - -Every enum definition must contain a constant that maps to zero -as its first element. This is because: - -There must be a zero value, so that we can use 0 as a numeric default value. -The zero value needs to be the first element. - -As in C, enums can be used as flags or just as numbers. -The on-wire, and in memory representation size of an enum can be specified. -Not all language bindings will support that. The default size is 4 (u32). - -Example -``` -enum ip_neighbor_flags -{ - IP_API_NEIGHBOR_FLAG_NONE = 0, - IP_API_NEIGHBOR_FLAG_STATIC = 0x1, - IP_API_NEIGHBOR_FLAG_NO_FIB_ENTRY = 0x2, -}; -``` - -Which generates the vl_api_ip_neighbor_flags_t in the C binding. -In Python that is represented as an IntFlag object -VppEnum.vl_api_ip_neighbor_flags_t. - -``` - enum : ENUM ID '{' enum_statements '}' ';' - enum : ENUM ID ':' enum_size '{' enum_statements '}' ';' - enum_size : U8 - | U16 - | U32 - enum_statements : enum_statement - | enum_statements enum_statement - enum_statement : ID '=' NUM ',' - | ID ',' -``` - -### Services -The service statement defines the relationship between messages. -For request/response and dump/details messages it ties the -request with the reply. For events, it specifies which events -that can be received for a given want_* call. - -Example: -``` -service { - rpc want_interface_events returns want_interface_events_reply - events sw_interface_event; -}; - -``` - -Which states that the request want_interface_events returns a -want_interface_events_reply and if enabled the client will -receive sw_interface_event messages whenever interface states changes. - -``` - service : SERVICE '{' service_statements '}' ';' - service_statements : service_statement - | service_statements service_statement - service_statement : RPC ID RETURNS NULL ';' - | RPC ID RETURNS ID ';' - | RPC ID RETURNS STREAM ID ';' - | RPC ID RETURNS ID EVENTS event_list ';' - event_list : events - | event_list events - events : ID - | ID ',' -``` - - -## Types -### Scalar Value Types - -.api type|size|C type|Python type ----------|----|------|----------- -i8 | 1|i8 |int -u8 | 1|u8 |int -i16 | 2|i16 |int -u16 | 2|u16 |int -i32 | 4|i32 |int -u32 | 4|u32 |int -i64 | 8|i64 |int -u64 | 8|u64 |int -f64 | 8|f64 |float -bool | 1|bool |boolean -string |variable|vl_api_string_t|str - -### User Defined Types -#### vnet/ip/ip_types.api - -.api type|size|C type|Python type ----------|----|------|----------- -vl_api_address_t|20|vl_api_address_t|`<class 'ipaddress.IPv4Address'> or <class 'ipaddress.IPv6Address'>` -vl_api_ip4_address_t|4|vl_api_ip4_address_t|`<class 'ipaddress.IPv4Address'>` -vl_api_ip6_address_t|16|vl_api_ip6_address_t|`<class 'ipaddress.IPv6Address'>` -vl_api_prefix_t|21|vl_api_prefix_t|`<class 'ipaddress.IPv4Network'> or <class 'ipaddress.IPv6Network'>` -vl_api_ip4_prefix_t|5|vl_api_ip4_prefix_t|`<class 'ipaddress.IPv4Network'>` -vl_api_ip6_prefix_t|17|vl_api_ip6_prefix_t|`<class 'ipaddress.IPv6Network'>` -vl_api_ip4_address_with_prefix_t|5|vl_api_ip4_address_with_prefix_t|`<class 'ipaddress.IPv4Interface'>` -vl_api_ip6_address_with_prefix_t|17|vl_api_ip6_address_with_prefix_t|`<class 'ipaddress.IPv6Interface'>` - -#### vnet/ethernet/ethernet_types.api -.api type|size|C type|Python type ----------|----|------|----------- -vl_api_mac_address_t|6|vl_api_mac_address_t|`class 'vpp_papi.MACAddress'>` - -#### vnet/interface_types.api -.api type|size|C type|Python type ----------|----|------|----------- -vl_api_interface_index_t|4|vl_api_interface_index_t|int - -### New explicit types - -#### String versus bytes -A byte string with a maximum length of 64: -``` -u8 name[64]; -``` -Before the "string" type was added, text string were defined like this. -The implications of that was the user would have to know if the field -represented a \0 ended C-string or a fixed length byte string. -The wire format of the 'string' type is a u32 length - -An IPv4 or IPv6 address was previously defined like: -``` -u8 is_ip6; -u8 address[16]; -``` - -Which made it hard for language bindings to represent the -address as anything but a byte string. -The new explicit address types are shown above. - -## Language generators - -The VPP API compiler currently has two output modules. One generating JSON -and one generating C header files that are directly used by the VPP -infrastructure and plugins. - -The C/C++, Python, Go Lua, and Java language bindings are generated based -on the JSON files. - -### Future considerations -- [ ] Generate C/C++ (vapi) client code directly from vppapigen -- [ ] Embed JSON definitions into the API server, so dynamic languages - can download them directly without going via the filesystem and JSON - files. diff --git a/src/tools/vppapigen/VPPAPI.rst b/src/tools/vppapigen/VPPAPI.rst new file mode 100644 index 00000000000..5b172a8c758 --- /dev/null +++ b/src/tools/vppapigen/VPPAPI.rst @@ -0,0 +1,404 @@ +VPP API Language +================ + +The VPP binary API is a message passing API. The VPP API language is +used to define a RPC interface between VPP and its control plane. The +API messages supports shared memory transport and Unix domain sockets +(SOCK_STREAM). + +The wire format is essentially that of a network formatted (big-endian) +packed C struct. + +The VPP API compiler is located in *src/tools/vppapigen* and can +currently compile to JSON or C (used by the VPP binary itself). + +Language definition +------------------- + +Defining a messages +~~~~~~~~~~~~~~~~~~~ + +There are 3 types of message exchanges: + +- Request/Reply The client sends a request message and the server + replies with a single reply message. The convention is that the reply + message is named as method_name + \_reply. + +- Dump/Detail The client sends a “bulk” request message to the server, + and the server replies with a set of detail messages. These messages + may be of different type. A dump/detail call must be enclosed in a + control ping block (Otherwise the client will not know the end of the + bulk transmission). The method name must end with method + “\_dump”, + the reply message should be named method + “\_details”. The exception + here is for the methods that return multiple message types + (e.g. sw_interface_dump). The Dump/Detail methods are typically used + for acquiring bulk information, like the complete FIB table. + +- Events The client can register for getting asynchronous notifications + from the server. This is useful for getting interface state changes, + and so on. The method name for requesting notifications is + conventionally prefixed with “want\_”. E.g. “want_interface_events”. + Which notification types results from an event registration is + defined in the service definition. + +A message from a client must include the ‘client_index’, an opaque +cookie identifying the sender, and a ‘context’ field to let the client +match request with reply. + +An example of a message definition. The client sends the show_version +request, the server replies with the show_version_reply. + +The *client_index* and *context* fields are required in all requests. +The *context* is returned by the server and is used by the client to +match up request and reply messages. + +.. code-block:: c + + define show_version + { + u32 client_index; + u32 context; + }; + define show_version_reply + { + u32 context; + i32 retval; + string program [32]; + string version [32]; + string build_date [32]; + /* The final field can be a variable length argument */ + string build_directory []; + }; + +The flags are not used by the clients, but have special meaning for some +of the tracing and debugging of the API. The *autoreply* flag is a +shorthand for a reply message with just a *retval* field. + +.. code-block:: c + + define : DEFINE ID '{' block_statements_opt '}' ';' + define : flist DEFINE ID '{' block_statements_opt '}' ';' + flist : flag + | flist flag + flag : MANUAL_PRINT + | MANUAL_ENDIAN + | DONT_TRACE + | AUTOREPLY + + block_statements_opt : block_statements + block_statements : block_statement + | block_statements block_statement + block_statement : declaration + | option + declaration : type_specifier ID ';' + | type_specifier ID '[' ID '=' assignee ']' ';' + declaration : type_specifier ID '[' NUM ']' ';' + | type_specifier ID '[' ID ']' ';' + type_specifier : U8 + | U16 + | U32 + | U64 + | I8 + | I16 + | I32 + | I64 + | F64 + | BOOL + | STRING + type_specifier : ID + +Options +~~~~~~~ + +The *option* word is used to specify meta information. The only current +use is to specify a semantic version of the .api file itself. + +Example: + +.. code-block:: c + + option version = "1.0.0"; + +.. code-block:: c + + + option : OPTION ID '=' assignee ';' + assignee : NUM + | TRUE + | FALSE + | STRING_LITERAL + +Defining new types +~~~~~~~~~~~~~~~~~~ + +New user defined types are defined just like messages. A typedef has two +forms. It can either define an alias for a different type (or array). + +Example: + +.. code-block:: c + + typedef u8 ip4_address[4]; + typedef u8 ip6_address[16]; + +Where the above defines two new types *vl_api_ip4_address_t* and +*vl_api_ip6_address_t*. These are aliases for the underlying u8 array. + +In the other form, it is used to specify an abstract data type. + +.. code-block:: c + + enum address_family { + ADDRESS_IP4 = 0, + ADDRESS_IP6, + }; + + union address_union { + vl_api_ip4_address_t ip4; + vl_api_ip6_address_t ip6; + }; + + typedef address { + vl_api_address_family_t af; + vl_api_address_union_t un; + }; + +Where the new type *vl_api_address_t* + +.. code-block:: c + + typedef : TYPEDEF ID '{' block_statements_opt '}' ';' + typedef : TYPEDEF declaration + +Importing Definitions +~~~~~~~~~~~~~~~~~~~~~ + +You can use definitions from other .api files by importing them. To +import another .api’s definitions, you add an import statement to the +top of your file: + +import “vnet/ip/ip_types.api”; + +By default you can only use definitions from directly imported .api +files. + +The API compiler searches for imported files in a set of directories +specified on the API compiler command line using the –includedir flag. + +.. code-block:: c + + import : IMPORT STRING_LITERAL ';' + +Comments +~~~~~~~~ + +The API language uses C style comments. + +.. code-block:: c + + /* */ + // + +Enumerations +~~~~~~~~~~~~ + +Enums are similar to enums in C. + +Every enum definition must contain a constant that maps to zero as its +first element. This is because: + +There must be a zero value, so that we can use 0 as a numeric default +value. The zero value needs to be the first element. + +As in C, enums can be used as flags or just as numbers. The on-wire, and +in memory representation size of an enum can be specified. Not all +language bindings will support that. The default size is 4 (u32). + +Example + +.. code-block:: c + + enum ip_neighbor_flags + { + IP_API_NEIGHBOR_FLAG_NONE = 0, + IP_API_NEIGHBOR_FLAG_STATIC = 0x1, + IP_API_NEIGHBOR_FLAG_NO_FIB_ENTRY = 0x2, + }; + +Which generates the vl_api_ip_neighbor_flags_t in the C binding. In +Python that is represented as an IntFlag object +VppEnum.vl_api_ip_neighbor_flags_t. + +.. code-block:: c + + enum : ENUM ID '{' enum_statements '}' ';' + enum : ENUM ID ':' enum_size '{' enum_statements '}' ';' + enum_size : U8 + | U16 + | U32 + enum_statements : enum_statement + | enum_statements enum_statement + enum_statement : ID '=' NUM ',' + | ID ',' + +Services +~~~~~~~~ + +The service statement defines the relationship between messages. For +request/response and dump/details messages it ties the request with the +reply. For events, it specifies which events that can be received for a +given ``want_*`` call. + +Example: + +.. code-block:: c + + service { + rpc want_interface_events returns want_interface_events_reply + events sw_interface_event; + }; + +Which states that the request want_interface_events returns a +want_interface_events_reply and if enabled the client will receive +sw_interface_event messages whenever interface states changes. + +.. code-block:: c + + service : SERVICE '{' service_statements '}' ';' + service_statements : service_statement + | service_statements service_statement + service_statement : RPC ID RETURNS NULL ';' + | RPC ID RETURNS ID ';' + | RPC ID RETURNS STREAM ID ';' + | RPC ID RETURNS ID EVENTS event_list ';' + event_list : events + | event_list events + events : ID + | ID ',' + +Types +----- + +Scalar Value Types +~~~~~~~~~~~~~~~~~~ + +========= ======== =============== =========== +.api type size C type Python type +========= ======== =============== =========== +i8 1 i8 int +u8 1 u8 int +i16 2 i16 int +u16 2 u16 int +i32 4 i32 int +u32 4 u32 int +i64 8 i64 int +u64 8 u64 int +f64 8 f64 float +bool 1 bool boolean +string variable vl_api_string_t str +========= ======== =============== =========== + +User Defined Types +~~~~~~~~~~~~~~~~~~ + +vnet/ip/ip_types.api +^^^^^^^^^^^^^^^^^^^^ + ++--------------------+--------+-------------+-------------------------+ +| .api type | size | C type | Python type | ++====================+========+=============+=========================+ +| vl_api_address_t | 20 | vl_ap | ` | +| | | i_address_t | `<class 'ipaddress.IPv4 | +| | | | Address'> or <class 'ip | +| | | | address.IPv6Address'>`` | ++--------------------+--------+-------------+-------------------------+ +| vl | 4 | vl_api_ip | ``<class 'ip | +| _api_ip4_address_t | | 4_address_t | address.IPv4Address'>`` | ++--------------------+--------+-------------+-------------------------+ +| vl | 16 | vl_api_ip | ``<class 'ip | +| _api_ip6_address_t | | 6_address_t | address.IPv6Address'>`` | ++--------------------+--------+-------------+-------------------------+ +| vl_api_prefix_t | 21 | vl_a | ` | +| | | pi_prefix_t | `<class 'ipaddress.IPv4 | +| | | | Network'> or <class 'ip | +| | | | address.IPv6Network'>`` | ++--------------------+--------+-------------+-------------------------+ +| v | 5 | vl_api_i | ``<class 'ip | +| l_api_ip4_prefix_t | | p4_prefix_t | address.IPv4Network'>`` | ++--------------------+--------+-------------+-------------------------+ +| v | 17 | vl_api_i | ``<class 'ip | +| l_api_ip6_prefix_t | | p6_prefix_t | address.IPv6Network'>`` | ++--------------------+--------+-------------+-------------------------+ +| vl_api_ip4_add | 5 | vl_api_ip4 | ``<class 'ipad | +| ress_with_prefix_t | | _address_wi | dress.IPv4Interface'>`` | +| | | th_prefix_t | | ++--------------------+--------+-------------+-------------------------+ +| vl_api_ip6_add | 17 | vl_api_ip6 | ``<class 'ipad | +| ress_with_prefix_t | | _address_wi | dress.IPv6Interface'>`` | +| | | th_prefix_t | | ++--------------------+--------+-------------+-------------------------+ + +vnet/ethernet/ethernet_types.api +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + ++---------------------+------+---------------------+-------------------+ +| .api type | size | C type | Python type | ++=====================+======+=====================+===================+ +| ``vl_ | 6 | ``vl_ | ``class 'vpp_pa | +| api_mac_address_t`` | | api_mac_address_t`` | pi.MACAddress'>`` | ++---------------------+------+---------------------+-------------------+ + +vnet/interface_types.api +^^^^^^^^^^^^^^^^^^^^^^^^ + +======================== ==== ======================== =========== +.api type size C type Python type +======================== ==== ======================== =========== +vl_api_interface_index_t 4 vl_api_interface_index_t int +======================== ==== ======================== =========== + +New explicit types +~~~~~~~~~~~~~~~~~~ + +String versus bytes +^^^^^^^^^^^^^^^^^^^ + +A byte string with a maximum length of 64: + +.. code-block:: c + + u8 name[64]; + +Before the “string” type was added, text string were defined like this. +The implications of that was the user would have to know if the field +represented a \\0 ended C-string or a fixed length byte string. The wire +format of the ‘string’ type is a u32 length + +An IPv4 or IPv6 address was previously defined like: + +.. code-block:: c + + u8 is_ip6; + u8 address[16]; + +Which made it hard for language bindings to represent the address as +anything but a byte string. The new explicit address types are shown +above. + +Language generators +------------------- + +The VPP API compiler currently has two output modules. One generating +JSON and one generating C header files that are directly used by the VPP +infrastructure and plugins. + +The C/C++, Python, Go Lua, and Java language bindings are generated +based on the JSON files. + +Future considerations +~~~~~~~~~~~~~~~~~~~~~ + +- Generate C/C++ (vapi) client code directly from vppapigen +- Embed JSON definitions into the API server, so dynamic languages + can download them directly without going via the filesystem and JSON + files. |