From 55c68c9521d98005ce850ee54a40c7579d88928b Mon Sep 17 00:00:00 2001 From: Nathan Skrzypczak Date: Mon, 29 Jul 2019 11:18:05 +0200 Subject: docs: Small fixes and ordering * deactivtates the TODOs on doxygen (were empty) * This move punt.md to readthedocs (should be the new place for dev doc ?) * Makes Handoff queue demo plugin a child of dev doc in doxygen Type: fix Change-Id: I1f0476a911b35208212af8dd608bc76160efd22a Signed-off-by: Nathan Skrzypczak --- docs/gettingstarted/developers/index.rst | 1 + docs/gettingstarted/developers/punt.rst | 1 + docs/scripts/prepare-for-site.sh | 18 +++++++ doxygen/dev_doc.md | 1 + doxygen/doxygen.cfg | 2 +- src/examples/handoffdemo/README.md | 2 +- src/vnet/ip/punt.md | 82 -------------------------------- src/vnet/ip/punt.rst | 81 +++++++++++++++++++++++++++++++ 8 files changed, 104 insertions(+), 84 deletions(-) create mode 120000 docs/gettingstarted/developers/punt.rst create mode 100755 docs/scripts/prepare-for-site.sh delete mode 100644 src/vnet/ip/punt.md create mode 100644 src/vnet/ip/punt.rst diff --git a/docs/gettingstarted/developers/index.rst b/docs/gettingstarted/developers/index.rst index 4f2c38d130a..fe265786e24 100644 --- a/docs/gettingstarted/developers/index.rst +++ b/docs/gettingstarted/developers/index.rst @@ -38,3 +38,4 @@ The Developers section covers the following areas: eventviewer fib20/index.rst buildwireshark + punt diff --git a/docs/gettingstarted/developers/punt.rst b/docs/gettingstarted/developers/punt.rst new file mode 120000 index 00000000000..0a56632f671 --- /dev/null +++ b/docs/gettingstarted/developers/punt.rst @@ -0,0 +1 @@ +../../../src/vnet/ip/punt.rst \ No newline at end of file diff --git a/docs/scripts/prepare-for-site.sh b/docs/scripts/prepare-for-site.sh new file mode 100755 index 00000000000..15888ba6e83 --- /dev/null +++ b/docs/scripts/prepare-for-site.sh @@ -0,0 +1,18 @@ +#!/bin/bash + +if [ ! -d "docs" ]; then + echo "This script is meant to be run from the root directory" + exit 1; +fi + +for f in $(find ./docs -type l) +do + target=$(readlink $f) + rm $f + cp $(dirname $f)/$target $(dirname $f)/$(basename $target) + echo "Replaced symlink $f" +done + +echo "Cleaning doc build directory" +make docs-clean + diff --git a/doxygen/dev_doc.md b/doxygen/dev_doc.md index 2e452d0f926..00f6caedf49 100644 --- a/doxygen/dev_doc.md +++ b/doxygen/dev_doc.md @@ -16,3 +16,4 @@ Programming notes for developers. - @subpage stats_doc - @subpage if_stats_client_doc - @subpage api_lang_doc +- @subpage handoff_queue_demo_plugin \ No newline at end of file diff --git a/doxygen/doxygen.cfg b/doxygen/doxygen.cfg index 39a918f5736..08356f40bce 100644 --- a/doxygen/doxygen.cfg +++ b/doxygen/doxygen.cfg @@ -622,7 +622,7 @@ STRICT_PROTO_MATCHING = NO # list. This list is created by putting \todo commands in the documentation. # The default value is: YES. -GENERATE_TODOLIST = YES +GENERATE_TODOLIST = NO # The GENERATE_TESTLIST tag can be used to enable (YES) or disable (NO) the test # list. This list is created by putting \test commands in the documentation. diff --git a/src/examples/handoffdemo/README.md b/src/examples/handoffdemo/README.md index 3787731c73f..e38c7b3cca0 100644 --- a/src/examples/handoffdemo/README.md +++ b/src/examples/handoffdemo/README.md @@ -1,4 +1,4 @@ -# Handoff queue demo plugin +# 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 diff --git a/src/vnet/ip/punt.md b/src/vnet/ip/punt.md deleted file mode 100644 index 2bbb5f6b97e..00000000000 --- a/src/vnet/ip/punt.md +++ /dev/null @@ -1,82 +0,0 @@ -.. _punt: - -Punting Packets -=============== - -.. toctree:: - -Overview -________ - -To 'punt' can mean different things to different people. In VPP the -data-plane punts when a packet cannot be handled by any further -nodes. Punt differs from drop, in that VPP is giving other elements of -the system the opportunity to handle this packet. - -A popular meaning of punt is to send packets to the user/control-plane. -This is specific option of the more general case above, where VPP is -handing the packet to the control-plane for further prosessing. - -The Punt Infrastructe ---------------------- - -Exception packets are those that a given node cannot handle via normal -mecahnisms. -Punting of exception packets is handled via the VLIB 'punt -infra'. There are two types of nodes; sources and sinks. Sources -allocate a punt 'reason' from the infrastructre and load time. When -they encouter an exception during switch time it will tag the packet -with the reason and ship the packet of the the punt-dispatch node. A -sink will register with the punt infra at load time so it can receive -packets that were punted for that reason. If no sinks are registerd -for a given reason the packet is dropped, if multiple sinks register -the packets are replicated. - -This mechanism allows us to extend the system to deal with packets -that the source node would otherise drop. - - -Punting to the Control Plane ----------------------------- - -Active Punt ------------ - -The user/control-plane specifies that this is the type of packet I -want to receive and this is where I want it sent. - -Currently there exists 3 ways to describe how to match/classify the -packets to be punted: -... - 1) a matching UDP port - 2) a matching IP protocol (i.e. OSPF) - 3) a matching punt excpetion reason (see above) -... - -Depending on the type/classification of the packet to be punted, that -active punt will register itself into the VLIB graph to receive those -packets. For example, if it's a packet matching a UDP port then it -will hook into the UDP port dispatch functions; udp_register_port(). - -There exists only one sink for passive punt, a unix domain socket. But -more work is underway in this area. - -see the API in: vnet/ip/punt.api - - - -Passive Punt ------------- - -VPP input packet processing can be described as a series of -classifiers. For example, a sequence of input classifications could -be, is it IP? is it for-us? is it UDP? is it a known UDP-port? If at -some point in this pipline VPP has no further classifications to make, -then the packet can be punted, which means sent to ipX-punt node. This -is described as passive since the control-plane is thus receiving -every packet that VPP does not itself handle. -For passive punt the user can specify where the packets should be -sent and whether/how they should be policed/rate-limited. - -see the API in: vnet/ip/ip.api - diff --git a/src/vnet/ip/punt.rst b/src/vnet/ip/punt.rst new file mode 100644 index 00000000000..3f1a9d4a844 --- /dev/null +++ b/src/vnet/ip/punt.rst @@ -0,0 +1,81 @@ +.. _dev_punt: + +.. toctree:: + +Punting Packets +=============== + +Overview +________ + +To 'punt' can mean different things to different people. In VPP the +data-plane punts when a packet cannot be handled by any further +nodes. Punt differs from drop, in that VPP is giving other elements of +the system the opportunity to handle this packet. + +A popular meaning of punt is to send packets to the user/control-plane. +This is specific option of the more general case above, where VPP is +handing the packet to the control-plane for further prosessing. + +The Punt Infrastructure +_______________________ + +Exception packets are those that a given node cannot handle via normal +mecahnisms. +Punting of exception packets is handled via the VLIB 'punt +infra'. There are two types of nodes; sources and sinks. Sources +allocate a punt 'reason' from the infrastructre and load time. When +they encouter an exception during switch time it will tag the packet +with the reason and ship the packet of the the punt-dispatch node. A +sink will register with the punt infra at load time so it can receive +packets that were punted for that reason. If no sinks are registerd +for a given reason the packet is dropped, if multiple sinks register +the packets are replicated. + +This mechanism allows us to extend the system to deal with packets +that the source node would otherise drop. + + +Punting to the Control Plane +____________________________ + +Active Punt +----------- + +The user/control-plane specifies that this is the type of packet I +want to receive and this is where I want it sent. + +Currently there exists 3 ways to describe how to match/classify the +packets to be punted: + +1) a matching UDP port +2) a matching IP protocol (i.e. OSPF) +3) a matching punt excpetion reason (see above) + +Depending on the type/classification of the packet to be punted, that +active punt will register itself into the VLIB graph to receive those +packets. For example, if it's a packet matching a UDP port then it +will hook into the UDP port dispatch functions; udp_register_port(). + +There exists only one sink for passive punt, a unix domain socket. But +more work is underway in this area. + +see the API in: vnet/ip/punt.api + + + +Passive Punt +------------ + +VPP input packet processing can be described as a series of +classifiers. For example, a sequence of input classifications could +be, is it IP? is it for-us? is it UDP? is it a known UDP-port? If at +some point in this pipline VPP has no further classifications to make, +then the packet can be punted, which means sent to ipX-punt node. This +is described as passive since the control-plane is thus receiving +every packet that VPP does not itself handle. +For passive punt the user can specify where the packets should be +sent and whether/how they should be policed/rate-limited. + +see the API in: vnet/ip/ip.api + -- cgit 1.2.3-korg