aboutsummaryrefslogtreecommitdiffstats
path: root/src/examples
diff options
context:
space:
mode:
authorNathan Skrzypczak <nathan.skrzypczak@gmail.com>2021-10-08 14:05:58 +0200
committerDave Wallace <dwallacelf@gmail.com>2021-10-13 15:32:22 +0000
commita2c9509a4ab22380937a2b613fcc518da22f5166 (patch)
tree93e0629de82c99ca4b1f9802083cf9362f1dc325 /src/examples
parent8acc5ee9079d0b03229a72e72a5308e7de0a359a (diff)
docs: convert extras doc md->rst
Type: improvement Change-Id: Ie3b25a86b99098d2b3a21a11fc73234c8ed589d6 Signed-off-by: Nathan Skrzypczak <nathan.skrzypczak@gmail.com>
Diffstat (limited to 'src/examples')
-rw-r--r--src/examples/handoffdemo/README.md186
-rw-r--r--src/examples/handoffdemo/handoffdemo.rst194
-rw-r--r--src/examples/sample-plugin/sample_plugin_doc.md66
-rw-r--r--src/examples/sample-plugin/sample_plugin_doc.rst97
-rw-r--r--src/examples/srv6-sample-localsid/srv6_sample_localsid_doc.md30
-rw-r--r--src/examples/srv6-sample-localsid/srv6_sample_localsid_doc.rst66
6 files changed, 357 insertions, 282 deletions
diff --git a/src/examples/handoffdemo/README.md b/src/examples/handoffdemo/README.md
deleted file mode 100644
index e38c7b3cca0..00000000000
--- a/src/examples/handoffdemo/README.md
+++ /dev/null
@@ -1,186 +0,0 @@
-# Handoff queue demo plugin {#handoff_queue_demo_plugin}
-
-This plugin provides a simplified example of how to hand off
-packets between threads. I used it to debug packet-tracer handoff
-tracing support.
-
-# Packet generator input script
-
-```
- packet-generator new {
- name x
- limit 5
- size 128-128
- interface local0
- node handoffdemo-1
- data {
- incrementing 30
- }
- }
-```
-# Start vpp with 2 worker threads
-
-The demo plugin hands packets from worker 1 to worker 2.
-
-# Enable tracing, and start the packet generator
-
-```
- trace add pg-input 100
- packet-generator enable
-```
-
-# Sample Run
-
-```
- DBGvpp# ex /tmp/pg_input_script
- DBGvpp# pa en
- DBGvpp# sh err
- Count Node Reason
- 5 handoffdemo-1 packets handed off processed
- 5 handoffdemo-2 completed packets
- DBGvpp# show run
- Thread 1 vpp_wk_0 (lcore 0)
- Time 133.9, average vectors/node 5.00, last 128 main loops 0.00 per node 0.00
- vector rates in 3.7331e-2, out 0.0000e0, drop 0.0000e0, punt 0.0000e0
- Name State Calls Vectors Suspends Clocks Vectors/Call
- handoffdemo-1 active 1 5 0 4.76e3 5.00
- pg-input disabled 2 5 0 5.58e4 2.50
- unix-epoll-input polling 22760 0 0 2.14e7 0.00
- ---------------
- Thread 2 vpp_wk_1 (lcore 2)
- Time 133.9, average vectors/node 5.00, last 128 main loops 0.00 per node 0.00
- vector rates in 0.0000e0, out 0.0000e0, drop 3.7331e-2, punt 0.0000e0
- Name State Calls Vectors Suspends Clocks Vectors/Call
- drop active 1 5 0 1.35e4 5.00
- error-drop active 1 5 0 2.52e4 5.00
- handoffdemo-2 active 1 5 0 2.56e4 5.00
- unix-epoll-input polling 22406 0 0 2.18e7 0.00
-```
-
-Enable the packet tracer and run it again...
-
-```
- DBGvpp# trace add pg-input 100
- DBGvpp# pa en
- DBGvpp# sh trace
- sh trace
- ------------------- Start of thread 0 vpp_main -------------------
- No packets in trace buffer
- ------------------- Start of thread 1 vpp_wk_0 -------------------
- Packet 1
-
- 00:06:50:520688: pg-input
- stream x, 128 bytes, 0 sw_if_index
- current data 0, length 128, buffer-pool 0, ref-count 1, trace handle 0x1000000
- 00000000: 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d0000
- 00000020: 0000000000000000000000000000000000000000000000000000000000000000
- 00000040: 0000000000000000000000000000000000000000000000000000000000000000
- 00000060: 0000000000000000000000000000000000000000000000000000000000000000
- 00:06:50:520762: handoffdemo-1
- HANDOFFDEMO: current thread 1
-
- Packet 2
-
- 00:06:50:520688: pg-input
- stream x, 128 bytes, 0 sw_if_index
- current data 0, length 128, buffer-pool 0, ref-count 1, trace handle 0x1000001
- 00000000: 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d0000
- 00000020: 0000000000000000000000000000000000000000000000000000000000000000
- 00000040: 0000000000000000000000000000000000000000000000000000000000000000
- 00000060: 0000000000000000000000000000000000000000000000000000000000000000
- 00:06:50:520762: handoffdemo-1
- HANDOFFDEMO: current thread 1
-
- Packet 3
-
- 00:06:50:520688: pg-input
- stream x, 128 bytes, 0 sw_if_index
- current data 0, length 128, buffer-pool 0, ref-count 1, trace handle 0x1000002
- 00000000: 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d0000
- 00000020: 0000000000000000000000000000000000000000000000000000000000000000
- 00000040: 0000000000000000000000000000000000000000000000000000000000000000
- 00000060: 0000000000000000000000000000000000000000000000000000000000000000
- 00:06:50:520762: handoffdemo-1
- HANDOFFDEMO: current thread 1
-
- Packet 4
-
- 00:06:50:520688: pg-input
- stream x, 128 bytes, 0 sw_if_index
- current data 0, length 128, buffer-pool 0, ref-count 1, trace handle 0x1000003
- 00000000: 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d0000
- 00000020: 0000000000000000000000000000000000000000000000000000000000000000
- 00000040: 0000000000000000000000000000000000000000000000000000000000000000
- 00000060: 0000000000000000000000000000000000000000000000000000000000000000
- 00:06:50:520762: handoffdemo-1
- HANDOFFDEMO: current thread 1
-
- Packet 5
-
- 00:06:50:520688: pg-input
- stream x, 128 bytes, 0 sw_if_index
- current data 0, length 128, buffer-pool 0, ref-count 1, trace handle 0x1000004
- 00000000: 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d0000
- 00000020: 0000000000000000000000000000000000000000000000000000000000000000
- 00000040: 0000000000000000000000000000000000000000000000000000000000000000
- 00000060: 0000000000000000000000000000000000000000000000000000000000000000
- 00:06:50:520762: handoffdemo-1
- HANDOFFDEMO: current thread 1
-
- ------------------- Start of thread 2 vpp_wk_1 -------------------
- Packet 1
-
- 00:06:50:520796: handoff_trace
- HANDED-OFF: from thread 1 trace index 0
- 00:06:50:520796: handoffdemo-2
- HANDOFFDEMO: current thread 2
- 00:06:50:520867: error-drop
- rx:local0
- 00:06:50:520914: drop
- handoffdemo-2: completed packets
-
- Packet 2
-
- 00:06:50:520796: handoff_trace
- HANDED-OFF: from thread 1 trace index 1
- 00:06:50:520796: handoffdemo-2
- HANDOFFDEMO: current thread 2
- 00:06:50:520867: error-drop
- rx:local0
- 00:06:50:520914: drop
- handoffdemo-2: completed packets
-
- Packet 3
-
- 00:06:50:520796: handoff_trace
- HANDED-OFF: from thread 1 trace index 2
- 00:06:50:520796: handoffdemo-2
- HANDOFFDEMO: current thread 2
- 00:06:50:520867: error-drop
- rx:local0
- 00:06:50:520914: drop
- handoffdemo-2: completed packets
-
- Packet 4
-
- 00:06:50:520796: handoff_trace
- HANDED-OFF: from thread 1 trace index 3
- 00:06:50:520796: handoffdemo-2
- HANDOFFDEMO: current thread 2
- 00:06:50:520867: error-drop
- rx:local0
- 00:06:50:520914: drop
- handoffdemo-2: completed packets
-
- Packet 5
-
- 00:06:50:520796: handoff_trace
- HANDED-OFF: from thread 1 trace index 4
- 00:06:50:520796: handoffdemo-2
- HANDOFFDEMO: current thread 2
- 00:06:50:520867: error-drop
- rx:local0
- 00:06:50:520914: drop
- handoffdemo-2: completed packets
- DBGvpp#
-```
diff --git a/src/examples/handoffdemo/handoffdemo.rst b/src/examples/handoffdemo/handoffdemo.rst
new file mode 100644
index 00000000000..d44854cc5cc
--- /dev/null
+++ b/src/examples/handoffdemo/handoffdemo.rst
@@ -0,0 +1,194 @@
+.. _handoff_queue_demo_plugin:
+
+Handoff queue in a plugin
+=========================
+
+This plugin provides a simplified example of how to hand off packets
+between threads. I used it to debug packet-tracer handoff tracing
+support.
+
+Packet generator input script
+-----------------------------
+
+::
+
+ packet-generator new {
+ name x
+ limit 5
+ size 128-128
+ interface local0
+ node handoffdemo-1
+ data {
+ incrementing 30
+ }
+ }
+
+Start vpp with 2 worker threads
+-------------------------------
+
+The demo plugin hands packets from worker 1 to worker 2.
+
+Enable tracing, and start the packet generator
+----------------------------------------------
+
+::
+
+ trace add pg-input 100
+ packet-generator enable
+
+Sample Run
+----------
+
+::
+
+ DBGvpp# ex /tmp/pg_input_script
+ DBGvpp# pa en
+ DBGvpp# sh err
+ Count Node Reason
+ 5 handoffdemo-1 packets handed off processed
+ 5 handoffdemo-2 completed packets
+ DBGvpp# show run
+ Thread 1 vpp_wk_0 (lcore 0)
+ Time 133.9, average vectors/node 5.00, last 128 main loops 0.00 per node 0.00
+ vector rates in 3.7331e-2, out 0.0000e0, drop 0.0000e0, punt 0.0000e0
+ Name State Calls Vectors Suspends Clocks Vectors/Call
+ handoffdemo-1 active 1 5 0 4.76e3 5.00
+ pg-input disabled 2 5 0 5.58e4 2.50
+ unix-epoll-input polling 22760 0 0 2.14e7 0.00
+ ---------------
+ Thread 2 vpp_wk_1 (lcore 2)
+ Time 133.9, average vectors/node 5.00, last 128 main loops 0.00 per node 0.00
+ vector rates in 0.0000e0, out 0.0000e0, drop 3.7331e-2, punt 0.0000e0
+ Name State Calls Vectors Suspends Clocks Vectors/Call
+ drop active 1 5 0 1.35e4 5.00
+ error-drop active 1 5 0 2.52e4 5.00
+ handoffdemo-2 active 1 5 0 2.56e4 5.00
+ unix-epoll-input polling 22406 0 0 2.18e7 0.00
+
+Enable the packet tracer and run it again…
+
+::
+
+ DBGvpp# trace add pg-input 100
+ DBGvpp# pa en
+ DBGvpp# sh trace
+ sh trace
+ ------------------- Start of thread 0 vpp_main -------------------
+ No packets in trace buffer
+ ------------------- Start of thread 1 vpp_wk_0 -------------------
+ Packet 1
+
+ 00:06:50:520688: pg-input
+ stream x, 128 bytes, 0 sw_if_index
+ current data 0, length 128, buffer-pool 0, ref-count 1, trace handle 0x1000000
+ 00000000: 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d0000
+ 00000020: 0000000000000000000000000000000000000000000000000000000000000000
+ 00000040: 0000000000000000000000000000000000000000000000000000000000000000
+ 00000060: 0000000000000000000000000000000000000000000000000000000000000000
+ 00:06:50:520762: handoffdemo-1
+ HANDOFFDEMO: current thread 1
+
+ Packet 2
+
+ 00:06:50:520688: pg-input
+ stream x, 128 bytes, 0 sw_if_index
+ current data 0, length 128, buffer-pool 0, ref-count 1, trace handle 0x1000001
+ 00000000: 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d0000
+ 00000020: 0000000000000000000000000000000000000000000000000000000000000000
+ 00000040: 0000000000000000000000000000000000000000000000000000000000000000
+ 00000060: 0000000000000000000000000000000000000000000000000000000000000000
+ 00:06:50:520762: handoffdemo-1
+ HANDOFFDEMO: current thread 1
+
+ Packet 3
+
+ 00:06:50:520688: pg-input
+ stream x, 128 bytes, 0 sw_if_index
+ current data 0, length 128, buffer-pool 0, ref-count 1, trace handle 0x1000002
+ 00000000: 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d0000
+ 00000020: 0000000000000000000000000000000000000000000000000000000000000000
+ 00000040: 0000000000000000000000000000000000000000000000000000000000000000
+ 00000060: 0000000000000000000000000000000000000000000000000000000000000000
+ 00:06:50:520762: handoffdemo-1
+ HANDOFFDEMO: current thread 1
+
+ Packet 4
+
+ 00:06:50:520688: pg-input
+ stream x, 128 bytes, 0 sw_if_index
+ current data 0, length 128, buffer-pool 0, ref-count 1, trace handle 0x1000003
+ 00000000: 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d0000
+ 00000020: 0000000000000000000000000000000000000000000000000000000000000000
+ 00000040: 0000000000000000000000000000000000000000000000000000000000000000
+ 00000060: 0000000000000000000000000000000000000000000000000000000000000000
+ 00:06:50:520762: handoffdemo-1
+ HANDOFFDEMO: current thread 1
+
+ Packet 5
+
+ 00:06:50:520688: pg-input
+ stream x, 128 bytes, 0 sw_if_index
+ current data 0, length 128, buffer-pool 0, ref-count 1, trace handle 0x1000004
+ 00000000: 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d0000
+ 00000020: 0000000000000000000000000000000000000000000000000000000000000000
+ 00000040: 0000000000000000000000000000000000000000000000000000000000000000
+ 00000060: 0000000000000000000000000000000000000000000000000000000000000000
+ 00:06:50:520762: handoffdemo-1
+ HANDOFFDEMO: current thread 1
+
+ ------------------- Start of thread 2 vpp_wk_1 -------------------
+ Packet 1
+
+ 00:06:50:520796: handoff_trace
+ HANDED-OFF: from thread 1 trace index 0
+ 00:06:50:520796: handoffdemo-2
+ HANDOFFDEMO: current thread 2
+ 00:06:50:520867: error-drop
+ rx:local0
+ 00:06:50:520914: drop
+ handoffdemo-2: completed packets
+
+ Packet 2
+
+ 00:06:50:520796: handoff_trace
+ HANDED-OFF: from thread 1 trace index 1
+ 00:06:50:520796: handoffdemo-2
+ HANDOFFDEMO: current thread 2
+ 00:06:50:520867: error-drop
+ rx:local0
+ 00:06:50:520914: drop
+ handoffdemo-2: completed packets
+
+ Packet 3
+
+ 00:06:50:520796: handoff_trace
+ HANDED-OFF: from thread 1 trace index 2
+ 00:06:50:520796: handoffdemo-2
+ HANDOFFDEMO: current thread 2
+ 00:06:50:520867: error-drop
+ rx:local0
+ 00:06:50:520914: drop
+ handoffdemo-2: completed packets
+
+ Packet 4
+
+ 00:06:50:520796: handoff_trace
+ HANDED-OFF: from thread 1 trace index 3
+ 00:06:50:520796: handoffdemo-2
+ HANDOFFDEMO: current thread 2
+ 00:06:50:520867: error-drop
+ rx:local0
+ 00:06:50:520914: drop
+ handoffdemo-2: completed packets
+
+ Packet 5
+
+ 00:06:50:520796: handoff_trace
+ HANDED-OFF: from thread 1 trace index 4
+ 00:06:50:520796: handoffdemo-2
+ HANDOFFDEMO: current thread 2
+ 00:06:50:520867: error-drop
+ rx:local0
+ 00:06:50:520914: drop
+ handoffdemo-2: completed packets
+ DBGvpp#
diff --git a/src/examples/sample-plugin/sample_plugin_doc.md b/src/examples/sample-plugin/sample_plugin_doc.md
deleted file mode 100644
index 9aaaefa0061..00000000000
--- a/src/examples/sample-plugin/sample_plugin_doc.md
+++ /dev/null
@@ -1,66 +0,0 @@
-# Sample plugin for VPP {#sample_plugin_doc}
-
-## Overview
-
-This is the VPP sample plugin demonstrates how to create a new plugin that integrates
-with VPP. The sample code implements a trival macswap algorithim that demonstrates plugin
-runtime integration with the VPP graph hierachy, api and cli.
-
-For deeper dive information see the annotations in the sample code itself. See [sample.c](@ref sample.c)
-
-## How to build and run the sample plugin.
-
-Now (re)build VPP.
-
- $ make wipe
-
-Define environmental variable 'SAMPLE_PLUGIN=yes' with a process scope
-
- $ SAMPLE_PLUGIN=yes make build
-
-or a session scope, and build VPP.
-
- $ export SAMPLE_PLUGIN=yes
- $ make build
-
-Now run VPP and make sure the plugin is loaded.
-
- $ make run
- ...
- load_one_plugin:184: Loaded plugin: memif_plugin.so (Packet Memory Interface (experimetal))
- load_one_plugin:184: Loaded plugin: sample_plugin.so (Sample of VPP Plugin)
- load_one_plugin:184: Loaded plugin: nat_plugin.so (Network Address Translation)
- ...
- DBGvpp#
-
-## How to create a new plugin
-
-To create a new plugin based on the sample plugin, copy and rename the sample plugin directory and automake config.
-
- cp -r src/examples/sample-plugin/sample src/plugins/newplugin
- cp src/examples/sample-plugin/sample.am src/plugins/newplugin.am
-
-Add the following entry to the plugins section of `src/configure.ac`.
-
- PLUGIN_ENABLED(newplugin)
-
-Add the following entry to the plugins section of `src/plugins/Makefile.am`
-
- if ENABLE_NEWPLUGIN
- include newplugin.am
- endif
-
-Now (re)build VPP.
-
- $ make wipe
- $ make build
-
-## Configuration
-
-To enable the sample plugin
-
- sample macswap <interface name>
-
-To disable the sample plugin
-
- sample macswap <interface name> disable
diff --git a/src/examples/sample-plugin/sample_plugin_doc.rst b/src/examples/sample-plugin/sample_plugin_doc.rst
new file mode 100644
index 00000000000..23023e21bfb
--- /dev/null
+++ b/src/examples/sample-plugin/sample_plugin_doc.rst
@@ -0,0 +1,97 @@
+.. _sample_plugin_doc:
+
+Sample plugin for VPP
+=====================
+
+Overview
+--------
+
+This is the VPP sample plugin demonstrates how to create a new plugin
+that integrates with VPP. The sample code implements a trivial macswap
+algorithm that demonstrates plugin runtime integration with the VPP
+graph hierarchy, api and cli.
+
+For deeper dive information see the annotations in the sample code
+itself. See `sample.c <@ref%20sample.c>`__
+
+How to build and run the sample plugin.
+---------------------------------------
+
+Now (re)build VPP.
+
+::
+
+ $ make wipe
+
+Define environmental variable ‘SAMPLE_PLUGIN=yes’ with a process scope
+
+::
+
+ $ SAMPLE_PLUGIN=yes make build
+
+or a session scope, and build VPP.
+
+::
+
+ $ export SAMPLE_PLUGIN=yes
+ $ make build
+
+Now run VPP and make sure the plugin is loaded.
+
+::
+
+ $ make run
+ ...
+ load_one_plugin:184: Loaded plugin: memif_plugin.so (Packet Memory Interface (experimetal))
+ load_one_plugin:184: Loaded plugin: sample_plugin.so (Sample of VPP Plugin)
+ load_one_plugin:184: Loaded plugin: nat_plugin.so (Network Address Translation)
+ ...
+ DBGvpp#
+
+How to create a new plugin
+--------------------------
+
+To create a new plugin based on the sample plugin, copy and rename the
+sample plugin directory and automake config.
+
+::
+
+ cp -r src/examples/sample-plugin/sample src/plugins/newplugin
+ cp src/examples/sample-plugin/sample.am src/plugins/newplugin.am
+
+Add the following entry to the plugins section of ``src/configure.ac``.
+
+::
+
+ PLUGIN_ENABLED(newplugin)
+
+Add the following entry to the plugins section of
+``src/plugins/Makefile.am``
+
+::
+
+ if ENABLE_NEWPLUGIN
+ include newplugin.am
+ endif
+
+Now (re)build VPP.
+
+::
+
+ $ make wipe
+ $ make build
+
+Configuration
+-------------
+
+To enable the sample plugin
+
+::
+
+ sample macswap <interface name>
+
+To disable the sample plugin
+
+::
+
+ sample macswap <interface name> disable
diff --git a/src/examples/srv6-sample-localsid/srv6_sample_localsid_doc.md b/src/examples/srv6-sample-localsid/srv6_sample_localsid_doc.md
deleted file mode 100644
index cd717db8135..00000000000
--- a/src/examples/srv6-sample-localsid/srv6_sample_localsid_doc.md
+++ /dev/null
@@ -1,30 +0,0 @@
-# Sample SRv6 LocalSID documentation {#srv6_plugin_doc}
-
-## Introduction
-
-This plugin is an example of how an user can create a new SRv6 LocalSID behavior by using VPP plugins with the appropiate API calls to the existing SR code.
-
-This **example** plugin registers a new localsid behavior, with cli keyword 'new_srv6_localsid' which only takes one parameter, a fib-table. Upon recival of a packet, this plugin will enforce the next IP6 lookup in the specific fib-table specified by the user. (Indeed it will do the lookup in the fib_table n+1 (since for the shake of the example we increment the fib-table.)
-
-Notice that the plugin only 'defines' a new SRv6 LocalSID behavior, but the existing SR code in VNET is the one actually instantiating new LocalSIDs. Notice that there are callback functions such that when you create or remove a LocalSID you can actually setup specific parameters through the functions in this plugin.
-
-## Variables to watch for
-
-* srv6_localsid_name: This variable is the name (used as a unique key) identifying this SR LocalSID plugin.
-* keyword_str: This is the CLI keyword to be used for the plugin. In this example 'new_srv6_localsid'. (i.e. sr localsid address cafe::1 behavior new_srv6_localsid <parameters>)
-* def_str: This is a definition of this SR behavior. This is printed when you do 'show sr localsid behaviors'.
-* params_str: This is a definition of the parameters of this localsid. This is printed when you do 'show sr localsid behaviors'.
-
-## Functions to watch for
-
-* srv6_localsid_creation_fn: This function will be called every time a new SR LocalSID is instantiated with the behavior defined in this plugin.
-* srv6_localsid_removal_fn: This function will be called every time a new SR LocalSID is removed with the behavior defined in this plugin. This function tends to be used for freeing up all the memory created in the previous function.
-* format_srv6_localsid_sample: This function prints nicely the parameters of every SR LocalSID using this behavior.
-* unformat_srv6_localsid_sample: This function parses the CLI command when initialising a new SR LocalSID using this behavior. It parses all the parameters and ensures that the parameters are correct.
-* format_srv6_localsid_sample_dpo: This function formats the 'show ip6 fib' message for the SR LocalSIDs created with this plugin behavior.
-
-## Graph node
-
-The current graph node uses the function 'end_srh_processing' to do the Segment Routing Endpoint behavior. Notice that it does not allow the cleanup of a Segment Routing header (as per the SRv6 behavior specs).
-This function is identical to the one found in /src/vnet/srv6/sr_localsid.c
-In case that by some other reason you want to do decapsulation, or SRH clean_up you can use the functions 'end_decaps_srh_processing' or 'end_psp_srh_processing' respectively.
diff --git a/src/examples/srv6-sample-localsid/srv6_sample_localsid_doc.rst b/src/examples/srv6-sample-localsid/srv6_sample_localsid_doc.rst
new file mode 100644
index 00000000000..a076cd2a6c7
--- /dev/null
+++ b/src/examples/srv6-sample-localsid/srv6_sample_localsid_doc.rst
@@ -0,0 +1,66 @@
+.. _srv6_plugin_doc:
+
+Sample SRv6 LocalSID documentation
+==================================
+
+Introduction
+------------
+
+This plugin is an example of how an user can create a new SRv6 LocalSID
+behavior by using VPP plugins with the appropriate API calls to the
+existing SR code.
+
+This **example** plugin registers a new localsid behavior, with cli
+keyword ‘new_srv6_localsid’ which only takes one parameter, a fib-table.
+Upon receival of a packet, this plugin will enforce the next IP6 lookup
+in the specific fib-table specified by the user. (Indeed it will do the
+lookup in the fib_table n+1 (since for the shake of the example we
+increment the fib-table.)
+
+Notice that the plugin only ‘defines’ a new SRv6 LocalSID behavior, but
+the existing SR code in VNET is the one actually instantiating new
+LocalSIDs. Notice that there are callback functions such that when you
+create or remove a LocalSID you can actually setup specific parameters
+through the functions in this plugin.
+
+Variables to watch for
+----------------------
+
+- srv6_localsid_name: This variable is the name (used as a unique key)
+ identifying this SR LocalSID plugin.
+- keyword_str: This is the CLI keyword to be used for the plugin. In
+ this example ‘new_srv6_localsid’. (i.e. sr localsid address cafe::1
+ behavior new_srv6_localsid )
+- def_str: This is a definition of this SR behavior. This is printed
+ when you do ‘show sr localsid behaviors’.
+- params_str: This is a definition of the parameters of this localsid.
+ This is printed when you do ‘show sr localsid behaviors’.
+
+Functions to watch for
+----------------------
+
+- srv6_localsid_creation_fn: This function will be called every time a
+ new SR LocalSID is instantiated with the behavior defined in this
+ plugin.
+- srv6_localsid_removal_fn: This function will be called every time a
+ new SR LocalSID is removed with the behavior defined in this plugin.
+ This function tends to be used for freeing up all the memory created
+ in the previous function.
+- format_srv6_localsid_sample: This function prints nicely the
+ parameters of every SR LocalSID using this behavior.
+- unformat_srv6_localsid_sample: This function parses the CLI command
+ when initializing a new SR LocalSID using this behavior. It parses
+ all the parameters and ensures that the parameters are correct.
+- format_srv6_localsid_sample_dpo: This function formats the ‘show ip6
+ fib’ message for the SR LocalSIDs created with this plugin behavior.
+
+Graph node
+----------
+
+The current graph node uses the function ‘end_srh_processing’ to do the
+Segment Routing Endpoint behavior. Notice that it does not allow the
+cleanup of a Segment Routing header (as per the SRv6 behavior specs).
+This function is identical to the one found in
+/src/vnet/srv6/sr_localsid.c In case that by some other reason you want
+to do decapsulation, or SRH clean_up you can use the functions
+‘end_decaps_srh_processing’ or ‘end_psp_srh_processing’ respectively.