VPP/API Concepts

General considerations

The VPP binary API is a message passing API. 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. There are three classes of methods supported by the API as outlined below.

Request/Reply

Dump/Detail

Want

Conventions

A request/reply call must be 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 must be 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?