VPP/API Concepts

General considerations

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.

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;
   u8 program[32];
   u8 version[32];
   u8 build_date[32];
   u8 build_directory[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;
  u8 ip6_prefix[16];
  u8 ip4_prefix[4];
  u8 ip6_src[16];
  u8 ip6_prefix_len;
  u8 ip4_prefix_len;
  u8 ip6_src_len;
  u8 ea_bits_len;
  u8 psid_offset;
  u8 psid_length;
  u8 flags;
  u16 mtu;
  u8 is_translation;
};

Issues

1. Use of variable length arrays
2. Pointers to shared memory blocks
3. String versus binary arrrays
4. Dump/Details calls where multiple message types are sent in return, not only the _details message. E.g. sw_interface_dump()

Open questions

1. Make a common message header containing length, context and client_index
2. Can manual_java tags be removed?
3. Fix calls with unconventional structures
4. Make compound datatypes ipv4 address, ipv6 prefix...?
5. Fix u8 data[0] (ensure it has a compound type)
6. Dump/Details calls have no way of returning failure to the client.
7. Make it explicit which message types are valid from an event registration (and also from a dump/details method)

unconventional_naming_rep_req = {
                                'cli_reply': 'cli_request',
                                'vnet_summary_stats_reply': 'vnet_get_summary_stats',
                                # This below is actually a sub-details callback. We cannot derive the mapping of dump request
                                # belonging to this sub-details from naming conventions. We need special mapping
                                'bridge_domain_sw_if_details': 'bridge_domain',
                                # This is standard dump call + details reply. However it's not called details but entry
                                'l2_fib_table_entry': 'l2_fib_table'
                                }

notifications_message_suffixes = ("event", "counters")
notification_messages = ["from_netconf_client", "from_netconf_server", "to_netconf_client", "to_netconf_server"]

ignored_messages = ["is_address_reachable"]