docs: convert vpp doc md->rst

Type: improvement

Change-Id: If453321785b04f9c16e8cea36fb1910efaeb2c59
Signed-off-by: Nathan Skrzypczak <nathan.skrzypczak@gmail.com>

1 files changed, 0 insertions, 155 deletions

diff --git a/src/vpp-api/vapi/vapi_doc.md b/src/vpp-api/vapi/vapi_doc.md
deleted file mode 100644
index 0e7e29dde01..00000000000
--- a/src/vpp-api/vapi/vapi_doc.md
+++ /dev/null
@@ -1,155 +0,0 @@
-# VPP API module    {#vapi_doc}
-
-## Overview
-
-VPP API module allows communicating with VPP over shared memory interface.
-The API consists of 3 parts:
-
-* common code - low-level API
-* generated code - high-level API
-* code generator - to generate your own high-level API e.g. for custom plugins
-
-### Common code
-
-#### C common code
-
-C common code represents the basic, low-level API, providing functions to
-connect/disconnect, perform message discovery and send/receive messages.
-The C variant is in vapi.h.
-
-#### C++ common code
-
-C++ is provided by vapi.hpp and contains high-level API templates,
-which are specialized by generated code.
-
-### Generated code
-
-Each API file present in the source tree is automatically translated to JSON
-file, which the code generator parses and generates either C (`vapi_c_gen.py`)
-or C++ (`vapi_cpp_gen.py`) code.
-
-This can then be included in the client application and provides convenient way
-to interact with VPP. This includes:
-
-* automatic byte-swapping
-* automatic request-response matching based on context
-* automatic casts to appropriate types (type-safety) when calling callbacks
-* automatic sending of control-pings for dump messages
-
-The API supports two modes of operation:
-
-* blocking
-* non-blocking
-
-In blocking mode, whenever an operation is initiated, the code waits until it
-can finish. This means that when sending a message, the call blocks until
-the message can be written to shared memory. Similarly, receiving a message
-blocks until a message becomes available. On higher level, this also means that
-when doing a request (e.g. `show_version`), the call blocks until a response
-comes back (e.g. `show_version_reply`).
-
-In non-blocking mode, these are decoupled, the API returns VAPI_EAGAIN whenever
-an operation cannot be performed and after sending a request, it's up to
-the client to wait for and process a response.
-
-### Code generator
-
-Python code generator comes in two flavors - C and C++ and generates high-level
-API headers. All the code is stored in the headers.
-
-## Usage
-
-### Low-level API
-
-Refer to inline API documentation in doxygen format in `vapi.h` header
-for description of functions. It's recommened to use the safer, high-level
-API provided by specialized headers (e.g. `vpe.api.vapi.h`
-or `vpe.api.vapi.hpp`).
-
-#### C high-level API
-
-##### Callbacks
-
-The C high-level API is strictly callback-based for maximum efficiency.
-Whenever an operation is initiated a callback with a callback context is part
-of that operation. The callback is then invoked when the response (or multiple
-responses) arrive which are tied to the request. Also, callbacks are invoked
-whenever an event arrives, if such callback is registered. All the pointers
-to responses/events point to shared memory and are immediately freed after
-callback finishes so the client needs to extract/copy any data in which it
-is interested in.
-
-#### Blocking mode
-
-In simple blocking mode, the whole operation (being a simple request or a dump)
-is finished and it's callback is called (potentially multiple times for dumps)
-during function call.
-
-Example pseudo-code for a simple request in this mode:
-
-`
-vapi_show_version(message, callback, callback_context)
-
-1. generate unique internal context and assign it to message.header.context
-2. byteswap the message to network byte order
-3. send message to vpp (message is now consumed and vpp will free it)
-4. create internal "outstanding request context" which stores the callback,
-   callback context and the internal context value
-5. call dispatch, which in this mode receives and processes responses until
-   the internal "outstanding requests" queue is empty. In blocking mode, this
-   queue always contains at most one item.
-`
-
-**Note**: it's possible for different - unrelated callbacks to be called before
-the response callbacks is called in cases where e.g. events are stored
-in shared memory queue.
-
-#### Non-blocking mode
-
-In non-blocking mode, all the requests are only byte-swapped and the context
-information along with callbacks is stored locally (so in the above example,
-only steps 1-4 are executed and step 5 is skipped). Calling dispatch is up to
-the client application. This allows to alternate between sending/receiving
-messages or have a dedicated thread which calls dispatch.
-
-### C++ high level API
-
-#### Callbacks
-
-In C++ API, the response is automatically tied to the corresponding `Request`,
-`Dump` or `Event_registration` object. Optionally a callback might be specified,
-which then gets called when the response is received.
-
-**Note**: responses take up shared memory space and should be freed either
-manually (in case of result sets) or automatically (by destroying the object
-owning them) when no longer needed. Once a Request or Dump object was executed,
-it cannot be re-sent, since the request itself (stores in shared memory)
-is consumed by vpp and inaccessible (set to nullptr) anymore.
-
-#### Usage
-
-#### Requests & dumps
-
-0. Create on object of `Connection` type and call `connect()` to connect to vpp.
-1. Create an object of `Request` or `Dump` type using it's typedef (e.g.
-   `Show_version`)
-2. Use `get_request()` to obtain and manipulate the underlying request if
-   required.
-3. Issue `execute()` to send the request.
-4. Use either `wait_for_response()` or `dispatch()` to wait for the response.
-5. Use `get_response_state()` to get the state and `get_response()` to read
-   the response.
-
-#### Events
-
-0. Create a `Connection` and execute the appropriate `Request` to subscribe to
-   events (e.g. `Want_stats`)
-1. Create an `Event_registration` with a template argument being the type of
-   event you are insterested in.
-2. Call `dispatch()` or `wait_for_response()` to wait for the event. A callback
-   will be called when an event occurs (if passed to `Event_registration()`
-   constructor). Alternatively, read the result set.
-
-**Note**: events stored in the result set take up space in shared memory
-and should be freed regularly (e.g. in the callback, once the event is
-processed).