diff options
| -rw-r--r-- | docs/gettingstarted/developers/binary_api_support.rst | 88 |
1 files changed, 81 insertions, 7 deletions
diff --git a/docs/gettingstarted/developers/binary_api_support.rst b/docs/gettingstarted/developers/binary_api_support.rst index a99bf3faa98..9c17a734e44 100644 --- a/docs/gettingstarted/developers/binary_api_support.rst +++ b/docs/gettingstarted/developers/binary_api_support.rst @@ -40,20 +40,20 @@ as follows: #ifdef vl_msg_id vl_msg_id(VL_API_SW_INTERFACE_SET_FLAGS, vl_api_sw_interface_set_flags_t_handler) vl_msg_id(VL_API_SW_INTERFACE_SET_FLAGS_REPLY, vl_api_sw_interface_set_flags_reply_t_handler) - #endif + #endif /****** Message names ******/ #ifdef vl_msg_name vl_msg_name(vl_api_sw_interface_set_flags_t, 1) vl_msg_name(vl_api_sw_interface_set_flags_reply_t, 1) - #endif + #endif /****** Message name, crc list ******/ #ifdef vl_msg_name_crc_list #define foreach_vl_msg_name_crc_interface \ _(VL_API_SW_INTERFACE_SET_FLAGS, sw_interface_set_flags, f890584a) \ _(VL_API_SW_INTERFACE_SET_FLAGS_REPLY, sw_interface_set_flags_reply, dfbf3afa) \ - #endif + #endif /****** Typedefs *****/ #ifdef vl_typedefs @@ -182,6 +182,80 @@ and `src/vlibapi/api_shared.c <https://docs.fd.io/vpp/18.11/d6/dd1/api__shared_8c.html>`_. See also the debug CLI command "api trace" +API trace replay caveats +________________________ + +The vpp instance which replays a binary API trace must have the same +message-ID numbering space as the vpp instance which captured the +trace. The replay instance **must** load the same set of plugins as +the capture instance. Otherwise, API messages will be processed by the +**wrong** API message handlers! + +Always start vpp with command-line arguments which include an +"api-trace on" stanza, so vpp will start tracing binary API messages +from the beginning: + +.. code-block:: console + + api-trace { + on + } + +Given a binary api trace in /tmp/api_trace, do the following to work +out the set of plugins: + +.. code-block:: console + + DBGvpp# api trace custom-dump /tmp/api_trace + vl_api_trace_plugin_msg_ids: abf_54307ba2 first 846 last 855 + vl_api_trace_plugin_msg_ids: acl_0d7265b0 first 856 last 893 + vl_api_trace_plugin_msg_ids: cdp_8f707b96 first 894 last 895 + vl_api_trace_plugin_msg_ids: flowprobe_f2f0286c first 898 last 901 + <etc> + +Here, we see the "abf," "acl," "cdp," and "flowprobe" plugins. Use the +list of plugins to construct a matching "plugins" command-line argument +stanza: + +.. code-block:: console + + plugins { + ## Disable all plugins, selectively enable specific plugins + plugin default { disable } + plugin abf_plugin.so { enable } + plugin acl_plugin.so { enable } + plugin cdp_plugin.so { enable } + plugin flowprobe_plugin.so { enable } + } + +To begin with, use the same vpp image that captured a trace to replay +it. It's perfectly fair to rebuild the vpp replay instance, to add +scaffolding to facilitate setting gdb breakpoints on complex +conditions or similar. + +API trace interface issues +__________________________ + +Along the same lines, it may be necessary to manufacture [simulated] +physical interfaces so that an API trace will replay correctly. "show +interface" on the trace origin system can help. An API trace +"custom-dump" as shown above may make it obvious how many loopback +interfaces to create. If you see vhost interfaces being created and +then configured, the first such configuration message in the trace +will tell you how many physical interfaces were involved. + +.. code-block:: console + + SCRIPT: create_vhost_user_if socket /tmp/foosock server + SCRIPT: sw_interface_set_flags sw_if_index 3 admin-up + +In this case, it's fair to guess that one needs to create two loopback +interfaces to "help" the trace replay correctly. + +These issues can be mitigated to a certain extent by replaying the +trace on the system which created it, but in a field debug case that's +not a realistic. + Client connection details _________________________ @@ -194,7 +268,7 @@ Establishing a binary API connection to VPP from a C-language client is easy: { vat_main_t *vam = &vat_main; api_main_t *am = &api_main; - if (vl_client_connect_to_vlib ("/vpe-api", client_name, + if (vl_client_connect_to_vlib ("/vpe-api", client_name, client_message_queue_length) < 0) return -1; /* Memorize vpp's binary API message input queue address */ @@ -202,7 +276,7 @@ Establishing a binary API connection to VPP from a C-language client is easy: /* And our client index */ vam->my_client_index = am->my_client_index; return 0; - } + } 32 is a typical value for client_message_queue_length. VPP *cannot* block when it needs to send an API message to a binary API client. The @@ -337,7 +411,7 @@ Set up message handlers about as follows: #undef vl_printfun /* Define a list of all message that the client handles */ #define foreach_vpe_api_reply_msg \ - _(SW_INTERFACE_SET_FLAGS_REPLY, sw_interface_set_flags_reply) + _(SW_INTERFACE_SET_FLAGS_REPLY, sw_interface_set_flags_reply) static clib_error_t * my_api_hookup (vlib_main_t * vm) { @@ -374,7 +448,7 @@ followed by minor adjustments of this form: API message numbering in plugins -------------------------------- -Binary API message numbering in plugins relies on vpp to issue a block +Binary API message numbering in plugins relies on vpp to issue a block of message-ID's for the plugin to use: .. code-block:: C |