src/vpp-api/vapi/vapi_doc.md

   1 # VPP API module    {#vapi_doc}
   2
   3 ## Overview
   4
   5 VPP API module allows communicating with VPP over shared memory interface.
   6 The API consists of 3 parts:
   7
   8 * common code - low-level API
   9 * generated code - high-level API
  10 * code generator - to generate your own high-level API e.g. for custom plugins
  11
  12 ### Common code
  13
  14 #### C common code
  15
  16 C common code represents the basic, low-level API, providing functions to
  17 connect/disconnect, perform message discovery and send/receive messages.
  18 The C variant is in vapi.h.
  19
  20 #### C++ common code
  21
  22 C++ is provided by vapi.hpp and contains high-level API templates,
  23 which are specialized by generated code.
  24
  25 ### Generated code
  26
  27 Each API file present in the source tree is automatically translated to JSON
  28 file, which the code generator parses and generates either C (`vapi_c_gen.py`)
  29 or C++ (`vapi_cpp_gen.py`) code.
  30
  31 This can then be included in the client application and provides convenient way
  32 to interact with VPP. This includes:
  33
  34 * automatic byte-swapping
  35 * automatic request-response matching based on context
  36 * automatic casts to appropriate types (type-safety) when calling callbacks
  37 * automatic sending of control-pings for dump messages
  38
  39 The API supports two modes of operation:
  40
  41 * blocking
  42 * non-blocking
  43
  44 In blocking mode, whenever an operation is initiated, the code waits until it
  45 can finish. This means that when sending a message, the call blocks until
  46 the message can be written to shared memory. Similarly, receiving a message
  47 blocks until a message becomes available. On higher level, this also means that
  48 when doing a request (e.g. `show_version`), the call blocks until a response
  49 comes back (e.g. `show_version_reply`).
  50
  51 In non-blocking mode, these are decoupled, the API returns VAPI_EAGAIN whenever
  52 an operation cannot be performed and after sending a request, it's up to
  53 the client to wait for and process a response.
  54
  55 ### Code generator
  56
  57 Python code generator comes in two flavors - C and C++ and generates high-level
  58 API headers. All the code is stored in the headers.
  59
  60 ## Usage
  61
  62 ### Low-level API
  63
  64 Refer to inline API documentation in doxygen format in `vapi.h` header
  65 for description of functions. It's recommened to use the safer, high-level
  66 API provided by specialized headers (e.g. `vpe.api.vapi.h`
  67 or `vpe.api.vapi.hpp`).
  68
  69 #### C high-level API
  70
  71 ##### Callbacks
  72
  73 The C high-level API is strictly callback-based for maximum efficiency.
  74 Whenever an operation is initiated a callback with a callback context is part
  75 of that operation. The callback is then invoked when the response (or multiple
  76 responses) arrive which are tied to the request. Also, callbacks are invoked
  77 whenever an event arrives, if such callback is registered. All the pointers
  78 to responses/events point to shared memory and are immediately freed after
  79 callback finishes so the client needs to extract/copy any data in which it
  80 is interested in.
  81
  82 #### Blocking mode
  83
  84 In simple blocking mode, the whole operation (being a simple request or a dump)
  85 is finished and it's callback is called (potentially multiple times for dumps)
  86 during function call.
  87
  88 Example pseudo-code for a simple request in this mode:
  89
  90 `
  91 vapi_show_version(message, callback, callback_context)
  92
  93 1. generate unique internal context and assign it to message.header.context
  94 2. byteswap the message to network byte order
  95 3. send message to vpp (message is now consumed and vpp will free it)
  96 4. create internal "outstanding request context" which stores the callback,
  97    callback context and the internal context value
  98 5. call dispatch, which in this mode receives and processes responses until
  99    the internal "outstanding requests" queue is empty. In blocking mode, this
 100    queue always contains at most one item.
 101 `
 102
 103 **Note**: it's possible for different - unrelated callbacks to be called before
 104 the response callbacks is called in cases where e.g. events are stored
 105 in shared memory queue.
 106
 107 #### Non-blocking mode
 108
 109 In non-blocking mode, all the requests are only byte-swapped and the context
 110 information along with callbacks is stored locally (so in the above example,
 111 only steps 1-4 are executed and step 5 is skipped). Calling dispatch is up to
 112 the client application. This allows to alternate between sending/receiving
 113 messages or have a dedicated thread which calls dispatch.
 114
 115 ### C++ high level API
 116
 117 #### Callbacks
 118
 119 In C++ API, the response is automatically tied to the corresponding `Request`,
 120 `Dump` or `Event_registration` object. Optionally a callback might be specified,
 121 which then gets called when the response is received.
 122
 123 **Note**: responses take up shared memory space and should be freed either
 124 manually (in case of result sets) or automatically (by destroying the object
 125 owning them) when no longer needed. Once a Request or Dump object was executed,
 126 it cannot be re-sent, since the request itself (stores in shared memory)
 127 is consumed by vpp and inaccessible (set to nullptr) anymore.
 128
 129 #### Usage
 130
 131 #### Requests & dumps
 132
 133 0. Create on object of `Connection` type and call `connect()` to connect to vpp.
 134 1. Create an object of `Request` or `Dump` type using it's typedef (e.g.
 135    `Show_version`)
 136 2. Use `get_request()` to obtain and manipulate the underlying request if
 137    required.
 138 3. Issue `execute()` to send the request.
 139 4. Use either `wait_for_response()` or `dispatch()` to wait for the response.
 140 5. Use `get_response_state()` to get the state and `get_response()` to read
 141    the response.
 142
 143 #### Events
 144
 145 0. Create a `Connection` and execute the appropriate `Request` to subscribe to
 146    events (e.g. `Want_stats`)
 147 1. Create an `Event_registration` with a template argument being the type of
 148    event you are insterested in.
 149 2. Call `dispatch()` or `wait_for_response()` to wait for the event. A callback
 150    will be called when an event occurs (if passed to `Event_registration()`
 151    constructor). Alternatively, read the result set.
 152
 153 **Note**: events stored in the result set take up space in shared memory
 154 and should be freed regularly (e.g. in the callback, once the event is
 155 processed).