aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorNathan Skrzypczak <nathan.skrzypczak@gmail.com>2020-09-04 18:31:23 +0200
committerAndrew Yourtchenko <ayourtch@gmail.com>2020-09-09 20:44:08 +0000
commitc4781a32df89c6c29b5f4bbea5440cddbede19a0 (patch)
tree64c9ce6450b7754056cfe507a87595c77c00f5e4 /docs
parentf681e9f736d34a6fdb7e596f63dfa1f51025a98c (diff)
docs: Improve new plugin doc & add govpp API doc
Type: docs Change-Id: I5f20ac0232c5cdc3cf64015185b0d0fc5c4a3100 Signed-off-by: Nathan Skrzypczak <nathan.skrzypczak@gmail.com>
Diffstat (limited to 'docs')
l---------docs/gettingstarted/developers/VPPAPI.md1
-rw-r--r--docs/gettingstarted/developers/add_plugin.rst84
-rw-r--r--docs/gettingstarted/developers/add_plugin_goapi.rst83
-rw-r--r--docs/gettingstarted/developers/index.rst2
4 files changed, 142 insertions, 28 deletions
diff --git a/docs/gettingstarted/developers/VPPAPI.md b/docs/gettingstarted/developers/VPPAPI.md
new file mode 120000
index 00000000000..a5404c116ee
--- /dev/null
+++ b/docs/gettingstarted/developers/VPPAPI.md
@@ -0,0 +1 @@
+../../../src/tools/vppapigen/VPPAPI.md \ No newline at end of file
diff --git a/docs/gettingstarted/developers/add_plugin.rst b/docs/gettingstarted/developers/add_plugin.rst
index 16952e8f036..19b935b746a 100644
--- a/docs/gettingstarted/developers/add_plugin.rst
+++ b/docs/gettingstarted/developers/add_plugin.rst
@@ -7,7 +7,7 @@ Adding a plugin
Overview
________
-
+
This section shows how a VPP developer can create a new plugin, and
add it to VPP. We assume that we are starting from the VPP <top-of-workspace>.
@@ -21,7 +21,7 @@ Create your new plugin
Change directory to **./src/plugins**, and run the plugin generator:
.. code-block:: console
-
+
$ cd ./src/plugins
$ ../../extras/emacs/make-plugin.sh
<snip>
@@ -36,7 +36,7 @@ Change directory to **./src/plugins**, and run the plugin generator:
Plugin name: myplugin
Dispatch type [dual or qs]: dual
(Shell command succeeded with no output)
-
+
OK...
The plugin generator script asks two questions: the name of the
@@ -65,9 +65,8 @@ Here are the generated files. We'll go through them in a moment.
$ cd ./myplugin
$ ls
- CMakeLists.txt myplugin.c myplugin_periodic.c setup.pg
- myplugin_all_api_h.h myplugin.h myplugin_test.c
- myplugin.api myplugin_msg_enum.h node.c
+ CMakeLists.txt myplugin.api myplugin.c myplugin.h
+ myplugin_periodic.c myplugin_test.c node.c setup.pg
Due to recent build system improvements, you **don't** need to touch
any other files to integrate your new plugin into the vpp build. Simply
@@ -92,7 +91,7 @@ As a quick sanity check, run vpp and make sure that
"myplugin_plugin.so" and "myplugin_test_plugin.so" are loaded:
.. code-block:: console
-
+
$ cd <top-of-workspace>
$ make run
<snip>
@@ -122,25 +121,21 @@ the copyright notice:
The rest of the build recipe is pretty simple:
-.. code-block:: console
+.. code-block:: CMake
add_vpp_plugin (myplugin
SOURCES
- myplugin.c
- node.c
+ myplugin.c
+ node.c
myplugin_periodic.c
myplugin.h
-
+
MULTIARCH_SOURCES
- node.c
-
+ node.c
+
API_FILES
myplugin.api
-
- INSTALL_HEADERS
- myplugin_all_api_h.h
- myplugin_msg_enum.h
-
+
API_TEST_SOURCES
myplugin_test.c
)
@@ -178,13 +173,13 @@ binary API message dispatcher, and to add its messages to vpp's global
Vpp itself uses dlsym(...) to track down the vlib_plugin_registration_t
generated by the VLIB_PLUGIN_REGISTER macro:
-.. code-block:: console
+.. code-block:: C
- VLIB_PLUGIN_REGISTER () =
+ VLIB_PLUGIN_REGISTER () =
{
.version = VPP_BUILD_VER,
.description = "myplugin plugin description goes here",
- };
+ };
Vpp only loads .so files from the plugin directory which contain an
instance of this data structure.
@@ -193,7 +188,7 @@ You can enable or disable specific vpp plugins from the command
line. By default, plugins are loaded. To change that behavior, set
default_disabled in the macro VLIB_PLUGIN_REGISTER:
-.. code-block:: console
+.. code-block:: C
VLIB_PLUGIN_REGISTER () =
{
@@ -205,14 +200,14 @@ default_disabled in the macro VLIB_PLUGIN_REGISTER:
The boilerplate generator places the graph node dispatch function
onto the "device-input" feature arc. This may or may not be useful.
-.. code-block:: console
+.. code-block:: C
VNET_FEATURE_INIT (myplugin, static) =
{
.arc_name = "device-input",
.node_name = "myplugin",
.runs_before = VNET_FEATURES ("ethernet-input"),
- };
+ };
As given by the plugin generator, myplugin.c contains the binary API
message handler for a generic "please enable my feature on such and
@@ -243,20 +238,53 @@ node.c
This is the generated graph node dispatch function. You'll need to
rewrite it to solve the problem at hand. It will save considerable
time and aggravation to retain the **structure** of the node dispatch
-function.
+function.
Even for an expert, it's a waste of time to reinvent the *loop
structure*, enqueue patterns, and so forth. Simply tear out and
replace the specimen 1x, 2x, 4x packet processing code with code
relevant to the problem you're trying to solve.
+myplugin.api
+------------
+
+This contains the API message definition. Here we only have defined
+a single one named ``myplugin_enable_disable`` and an implicit
+``myplugin_enable_disable_reply`` containing only a return value due
+to the ``autoreply`` keyword.
+
+The syntax reference for ``.api`` files can be found at VPP API Language
+
+Addressing the binary API with this message will run the handler defined
+in ``myplugin.c`` as ``vl_api_myplugin_enable_disable_t_handler``.
+It will receive a message pointer ``*mp`` which is the struct defined
+in ``myplugin.api`` and should return another message pointer ``*rmp``,
+of the reply type. That's what ``REPLY_MACRO`` does.
+
+To be noted, all API messages are in net-endian and vpp is host-endian,
+so you will need to use :
+
+* ``u32 value = ntohl(mp->value);``
+* ``rmp->value = htonl(value);``
+
+You can now use this API with :ref:`GoLang bindings <add_plugin_goapi>`
+
+myplugin_periodic.c
+-------------------
+
+This defines a VPP process, a routine that will run indefinitely and
+be woken up intermittently, here to process plugin events.
+
+To be noted, vlib_processes aren't thread-safe, and data structures
+should be locked when shared between workers.
+
Plugin "Friends with Benefits"
------------------------------
In vpp VLIB_INIT_FUNCTION functions, It's reasonably common to see a
specific init function invoke other init functions:
-.. code-block:: console
+.. code-block:: C
if ((error = vlib_call_init_function (vm, some_other_init_function))
return error;
@@ -264,7 +292,7 @@ specific init function invoke other init functions:
In the case where one plugin needs to call a init function in another
plugin, use the vlib_call_plugin_init_function macro:
-.. code-block:: console
+.. code-block:: C
if ((error = vlib_call_plugin_init_function (vm, "otherpluginname", some_init_function))
return error;
@@ -274,7 +302,7 @@ This allows sequencing between plugin init functions.
If you wish to obtain a pointer to a symbol in another plugin, use the
vlib_plugin_get_symbol(...) API:
-.. code-block:: console
+.. code-block:: C
void *p = vlib_get_plugin_symbol ("plugin_name", "symbol");
diff --git a/docs/gettingstarted/developers/add_plugin_goapi.rst b/docs/gettingstarted/developers/add_plugin_goapi.rst
new file mode 100644
index 00000000000..dce35b8f0a2
--- /dev/null
+++ b/docs/gettingstarted/developers/add_plugin_goapi.rst
@@ -0,0 +1,83 @@
+.. _add_plugin_goapi:
+
+Add a plugin's GO API
+=====================
+
+In order to use your plugin's API with GO, you will need to use
+a GO client and GO definitions of the API messages that you defined
+in ``myplugin.api`` (go bindings).
+
+These two things can be found in `govpp <https://github.com/FDio/govpp>`_
+
+* The API client lives in `./core`
+* The api-generator lives in `./binapigen`
+* A sample of its output (the go bindings) for VPP's latest version lives in `./binapi`
+
+To generate the go bindings for your plugin. Assuming :
+* ``/home/vpp`` is a VPP clone with your plugin in it.
+* ``/home/controlplane`` is a go controlplane repo
+
+.. code-block:: console
+
+ $ mkdir /home/controlplane/vpp-go-bindings
+ $ git clone https://github.com/FDio/govpp>
+ $ cd govpp
+ $ BINAPI_DIR=/home/controlplane/vpp-go-bindings VPP_DIR=/home/vpp make gen-binapi-from-code
+
+This will generate the go-bindings in ``/home/controlplane/vpp-go-bindings``
+For example ``vpp-go-bindings/myplugin/myplugin.ba.go`` will contain :
+
+.. code-block:: go
+
+ // MypluginEnableDisable defines message 'myplugin_enable_disable'.
+ type MypluginEnableDisable struct {
+ EnableDisable bool `binapi:"bool,name=enable_disable" json:"enable_disable,omitempty"`
+ SwIfIndex interface_types.InterfaceIndex `binapi:"interface_index,name=sw_if_index" json:"sw_if_index,omitempty"`
+ }
+
+
+You can then use the generated go bindings in your go code like this :
+
+.. code-block:: go
+
+ package main
+
+ import (
+ "fmt"
+ "git.fd.io/govpp.git"
+ "git.fd.io/govpp.git/binapi/interfaces"
+ "git.fd.io/govpp.git/binapi/vpe"
+
+ "myplugin.io/controlplane/vpp-go-bindings/myplugin/myplugin"
+ )
+
+ func main() {
+ // Connect to VPP
+ conn, _ := govpp.Connect("/run/vpp/api.sock")
+ defer conn.Disconnect()
+
+ // Open channel
+ ch, _ := conn.NewAPIChannel()
+ defer ch.Close()
+
+ request := &vpe.MypluginEnableDisable{
+ EnableDisable: true,
+ }
+ reply := &vpe.MypluginEnableDisableReply{}
+
+ err := ch.SendRequest(request).ReceiveReply(reply)
+ if err != nil {
+ fmt.Errorf("SendRequest: %w\n", err)
+ }
+ }
+
+As you will need to import (or ``go get "git.fd.io/govpp.git"``) to leverage the API
+client in your code, you might want to use the api-generator directly from the
+clone ``go build`` fetches for you. You can do this with :
+
+.. code-block:: console
+
+ $ export GOVPP_DIR=$(go list -f '{{.Dir}}' -m git.fd.io/govpp.git)
+ $ cd $GOVPP_DIR && go build -o /some/bin/dir ./cmd/binapi-generator
+ $ # instead of make gen-binapi-from-code you can rewrite the code to target
+ $ # your version ./binapi-generator
diff --git a/docs/gettingstarted/developers/index.rst b/docs/gettingstarted/developers/index.rst
index 378b9fb83c0..04d704319b2 100644
--- a/docs/gettingstarted/developers/index.rst
+++ b/docs/gettingstarted/developers/index.rst
@@ -22,6 +22,7 @@ The Developers section covers the following areas:
running_vpp
gdb_examples
add_plugin
+ add_plugin_goapi
gitreview
softwarearchitecture
infrastructure
@@ -42,3 +43,4 @@ The Developers section covers the following areas:
quic_plugin
cross_compile_macos.rst
cnat
+ VPPAPI.md