Difference between revisions of "VPP/API Concepts"
From fd.io
< VPP
(→Proposed changes / Open questsions) |
(→Examples) |
||
| (4 intermediate revisions by 3 users not shown) | |||
| Line 10: | Line 10: | ||
; Events | ; Events | ||
| − | : The client can register for getting asynchronous notifications from the server. This is useful for getting interface state changes, periodic counters and so on. The method name for requesting notifications is conventionally prefixed with "want_". E.g. " | + | : The client can register for getting asynchronous notifications from the server. This is useful for getting interface state changes, periodic counters 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 not defined in the API 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. | 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. | ||
| Line 22: | Line 22: | ||
=== Types === | === Types === | ||
| − | The API supports any C type including compound data types. Conventionally the API is restricted to the basic C types (u8, u16, u32, u64, i8, i16, i32, i64). | + | The API supports any C type including compound data types. Conventionally the API is restricted to the basic C types (bool, u8, u16, u32, u64, i8, i16, i32, i64). |
| − | Currently strings are represented as u8[]. | + | Currently strings are represented as u8[] as well as an string typedef. |
==== Type issues ==== | ==== Type issues ==== | ||
| − | * Both binary arrays and strings are represented as u8[]. For example u8 mac_address[6] and u8 build_directory[256]. | + | * Both binary arrays and strings are represented as u8[]. For example u8 mac_address[6] and u8 build_directory[256]. A separate type for strings has been added. |
| − | * | + | * Historically, type checking by language wrappers has been difficult because explicit types weren't used. E.g. an IPv6 address was represented as u8 ip6_prefix[16]. Migration to a dedicated type is underway. |
| − | * Variable length arrays don't include type as in u8 char[0] and the ''count'' field is message specific, making it hard to auto-generate code for these message types. | + | * Variable length arrays don't include type as in u8 char[0] and the ''count'' field is message specific, making it hard to auto-generate code for these message types. The string typedef illustrates the use of a consistent structure. |
* Use of pointers to shared memory e.g. get_node_graph_reply. | * Use of pointers to shared memory e.g. get_node_graph_reply. | ||
| Line 51: | Line 51: | ||
u32 context; | u32 context; | ||
i32 retval; | i32 retval; | ||
| − | + | string program[limit=32]; | |
| − | + | string version[limit=32]; | |
| − | + | string build_date[limit=32]; | |
| − | + | string build_directory[limit=256]; | |
}; | }; | ||
</nowiki> | </nowiki> | ||
| Line 68: | Line 68: | ||
}; | }; | ||
| − | define map_domain_details { | + | define map_domain_details |
| + | { | ||
u32 context; | u32 context; | ||
u32 domain_index; | u32 domain_index; | ||
| − | + | vl_api_ip6_prefix_t ip6_prefix; | |
| − | + | vl_api_ip4_prefix_t ip4_prefix; | |
| − | + | vl_api_ip6_prefix_t ip6_src; | |
| − | + | ||
| − | + | ||
| − | + | ||
u8 ea_bits_len; | u8 ea_bits_len; | ||
u8 psid_offset; | u8 psid_offset; | ||
| Line 82: | Line 80: | ||
u8 flags; | u8 flags; | ||
u16 mtu; | u16 mtu; | ||
| − | + | string tag; | |
}; | }; | ||
</nowiki> | </nowiki> | ||
| Line 89: | Line 87: | ||
# Make a common message header containing length, context and client_index | # Make a common message header containing length, context and client_index | ||
# Remove manual_java tags(??) | # Remove manual_java tags(??) | ||
| − | |||
| − | |||
# Use compound data types where possible | # Use compound data types where possible | ||
# Define new syntax to explicitly list valid reply messages types for events and _dump calls | # Define new syntax to explicitly list valid reply messages types for events and _dump calls | ||
# Replace pointers to shared memory by adding content to message | # Replace pointers to shared memory by adding content to message | ||
Latest revision as of 10:10, 24 May 2019
Contents
API Conventions
The VPP binary API is a message passing API. It supports the following API method types.
- 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, periodic counters 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 not defined in the API 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.
Naming
- Reply/Request method. Request: name Reply: name+_reply
- Dump/Detail method. Request: name+_dump Reply: name+_details
- Event registration: Request: want_+name Reply: want_+name+_reply
Types
The API supports any C type including compound data types. Conventionally the API is restricted to the basic C types (bool, u8, u16, u32, u64, i8, i16, i32, i64). Currently strings are represented as u8[] as well as an string typedef.
Type issues
- Both binary arrays and strings are represented as u8[]. For example u8 mac_address[6] and u8 build_directory[256]. A separate type for strings has been added.
- Historically, type checking by language wrappers has been difficult because explicit types weren't used. E.g. an IPv6 address was represented as u8 ip6_prefix[16]. Migration to a dedicated type is underway.
- Variable length arrays don't include type as in u8 char[0] and the count field is message specific, making it hard to auto-generate code for these message types. The string typedef illustrates the use of a consistent structure.
- Use of pointers to shared memory e.g. get_node_graph_reply.
Method issues
- Dump/Details do not have an explicit definition of which message types can be returned.
- Event methods do not have an explicit definition of which messages types can be returned.
- Dump/Details calls have no way of returning failure to the client.
Examples
A request/reply call is structured as follows:
define show_version {
u32 client_index;
u32 context;
};
define show_version_reply {
u32 context;
i32 retval;
string program[limit=32];
string version[limit=32];
string build_date[limit=32];
string build_directory[limit=256];
};
With the reply message having the API method name concatenated with the string "_reply".
A Dump/Details call is structured as follows:
define map_domain_dump {
u32 client_index;
u32 context;
};
define map_domain_details
{
u32 context;
u32 domain_index;
vl_api_ip6_prefix_t ip6_prefix;
vl_api_ip4_prefix_t ip4_prefix;
vl_api_ip6_prefix_t ip6_src;
u8 ea_bits_len;
u8 psid_offset;
u8 psid_length;
u8 flags;
u16 mtu;
string tag;
};
Proposed changes / Open questions
- Make a common message header containing length, context and client_index
- Remove manual_java tags(??)
- Use compound data types where possible
- Define new syntax to explicitly list valid reply messages types for events and _dump calls
- Replace pointers to shared memory by adding content to message
