From fdc62abdc113ea63dc867375bd49ef3043dcd290 Mon Sep 17 00:00:00 2001 From: Chris Luke Date: Wed, 28 Dec 2016 09:44:47 -0500 Subject: Repair Doxygen build infrastructure After Gerrit 4430 much of the documentation failed to build, but silently so it was easily missed; equally missing that several paths have been missing for a while. - Correct paths after directory tree changes. - Doxygen now bails when input paths don't exist. - Fix up some of the less deranged entries in the documentation index. - Exclude the LUA tree, its documentation is a mess. Change-Id: I35e6b433feee5e05bca772d93aa1635c724db734 Signed-off-by: Chris Luke --- README.md | 30 +++++++++++----------- doxygen/Makefile | 38 +++++++++++++++++++-------- doxygen/user_doc.md | 2 ++ src/vnet/bfd/bfd_doc.md | 4 ++- src/vnet/span/span.md | 65 ----------------------------------------------- src/vnet/span/span_doc.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 112 insertions(+), 92 deletions(-) delete mode 100644 src/vnet/span/span.md create mode 100644 src/vnet/span/span_doc.md diff --git a/README.md b/README.md index cf43a4df..8520b395 100644 --- a/README.md +++ b/README.md @@ -30,22 +30,22 @@ Directory name | Description build-root | Build output directory doxygen | Documentation generator configuration dpdk | DPDK patches and build infrastructure - g2 | Event log visualization tool - perftool | Performance tool -@ref plugins | VPP bundled plugins directory -@ref svm | Shared virtual memory allocation library +@ref plugins | Not-yet-relocated VPP bundled plugins directory +@ref src | VPP source code +@ref src/plugins | VPP bundled plugins directory +@ref src/svm | Shared virtual memory allocation library + src/tests | Unit tests + src/vat | VPP API test program +@ref src/vlib | VPP application library +@ref src/vlibapi | VPP API library +@ref src/vlibmemory | VPP Memory management +@ref src/vlibsocket | VPP Socket I/O +@ref src/vnet | VPP networking +@ref src/vpp | VPP application +@ref src/vpp-api | VPP application API bindings +@ref src/vppinfra | VPP core library test | Unit tests -@ref vlib | VPP application library source -@ref vlib-api | VPP API library source -@ref vnet | VPP networking source -@ref vpp | VPP application source -@ref vpp-api | VPP application API source - vppapigen | VPP API generator source - vpp-api-test | VPP API test program source -@ref vppinfra | VPP core library source - -(If the page you are viewing is not generated by Doxygen then -ignore any @@ref labels in the above table.) +@ref vpp-api | Not-yet-relocated API bindings ## Getting started diff --git a/doxygen/Makefile b/doxygen/Makefile index 92fa3635..ffce3c13 100644 --- a/doxygen/Makefile +++ b/doxygen/Makefile @@ -42,13 +42,17 @@ DOC_MAC_PY_DEPENDS = pyparsing jinja2 DOXY_DIR ?= $(WS_ROOT)/doxygen # Primary source directories +DOXY_SRC ?= src DOXY_SRC_DIRECTORIES = \ - vppinfra \ - svm \ - vlib \ - vlib-api \ - vnet \ - vpp \ + $(DOXY_SRC)/vppinfra \ + $(DOXY_SRC)/svm \ + $(DOXY_SRC)/vlib \ + $(DOXY_SRC)/vlibapi \ + $(DOXY_SRC)/vlibmemory \ + $(DOXY_SRC)/vlibsocket \ + $(DOXY_SRC)/vnet \ + $(DOXY_SRC)/vpp \ + $(DOXY_SRC)/vpp-api \ vpp-api # Input directories and files @@ -56,6 +60,7 @@ DOXY_INPUT ?= \ $(wildcard $(WS_ROOT)/*.md) \ $(wildcard $(DOXY_DIR)/*.md) \ $(DOXY_SRC_DIRECTORIES) \ + $(DOXY_SRC)/plugins \ plugins # Strip leading workspace path from input names @@ -67,9 +72,10 @@ DOXY_INPUT := $(subst $(WS_ROOT)/,,$(DOXY_INPUT)) # there's a DPDK equivalent that conflicts. # These must be left-anchored paths for the regexp below to work. DOXY_EXCLUDE ?= \ - vlib/vlib/buffer.c \ - vlib/example \ - plugins/sample-plugin + $(DOXY_SRC)/vlib/vlib/buffer.c \ + $(DOXY_SRC)/vlib/example \ + plugins/sample-plugin \ + vpp-api/lua # Generate a regexp for filenames to exclude DOXY_EXCLUDE_REGEXP = ($(subst .,\.,$(shell echo '$(strip $(DOXY_EXCLUDE))' | sed -e 's/ /|/g'))) @@ -164,9 +170,11 @@ endif bootstrap-doxygen: $(BR)/.doxygen-bootstrap.ok .DELETE_ON_ERROR: $(BR)/.doxygen-siphon.dep -$(BR)/.doxygen-siphon.dep: Makefile +$(BR)/.doxygen-siphon.dep: Makefile \ + $(addprefix,$(WSROOT),$(DOXY_INPUT)) @echo "Building siphon dependencies..." - @set -e; rm -f "$@"; for input in $(DOXY_INPUT); do \ + @rm -f "$@"; for input in $(DOXY_INPUT); do \ + [ -e "$(WS_ROOT)/$$input" ] && \ find "$(WS_ROOT)/$$input" -type f \ \( -name '*.[ch]' -or -name '*.dox' \) -print \ | grep -v -E '^$(WS_ROOT)/$(DOXY_EXCLUDE_REGEXP)' \ @@ -182,7 +190,15 @@ $(BR)/.doxygen-siphon.dep: Makefile .NOTPARALLEL: $(SIPHON_FILES) $(SIPHON_FILES): $(BR)/.doxygen-bootstrap.ok \ $(DOXY_DIR)/siphon-generate \ + $(addprefix,$(WSROOT),$(DOXY_INPUT)) \ $(wildcard $(DOXY_DIR)/siphon/*.py) + @echo "Validating source tree..." + @set -e; for input in $(DOXY_INPUT); do \ + if [ ! -e "$(WS_ROOT)/$$input" ]; then \ + echo "ERROR: Input path '$$input' does not exist." >&2; \ + exit 1; \ + fi; \ + done @rm -rf "$(SIPHON_INPUT)" "$(SIPHON_OUTPUT)" @mkdir -p "$(SIPHON_INPUT)" "$(SIPHON_OUTPUT)" @touch $(SIPHON_INPUT)/files diff --git a/doxygen/user_doc.md b/doxygen/user_doc.md index 2e87c877..40303439 100644 --- a/doxygen/user_doc.md +++ b/doxygen/user_doc.md @@ -12,3 +12,5 @@ Several modules provide operational, dataplane-user focused documentation. - @subpage ioam_plugin_doc - @subpage lb_plugin_doc - @subpage flowperpkt_plugin_doc +- @subpage span_doc +- @subpage bfd_doc diff --git a/src/vnet/bfd/bfd_doc.md b/src/vnet/bfd/bfd_doc.md index 1333ed77..3e86b178 100644 --- a/src/vnet/bfd/bfd_doc.md +++ b/src/vnet/bfd/bfd_doc.md @@ -1 +1,3 @@ -TODO +# BFD Notes {#bfd_doc} + +@todo Someone needs to produce this or remove the stub file. diff --git a/src/vnet/span/span.md b/src/vnet/span/span.md deleted file mode 100644 index ee3f814f..00000000 --- a/src/vnet/span/span.md +++ /dev/null @@ -1,65 +0,0 @@ -# VPP SPAN implementation - -This is a memo intended to contain documentation of the VPP SPAN implementation. -Everything that is not directly obvious should come here. - - -## Switched Port Analyzer (SPAN) -Port mirroring is used on a network switch to send a copy of network packets seen on one switch port to a network monitoring connection on another switch port. -Can be used by network engineers or administrators to measure performnce, analyze and debug data or diagnose errors on a network. - -### RX traffic node -There is one static node to mirror incomming packets. -* span-input: Creates a copy of incomming buffer due to incomming buffers can be reused internally. - -Chaining: dpdk-input -> span-input -> -* original buffer is sent to ethernet-input for processing -* buffer copy is sent to interface-output - -### Configuration -SPAN supports the following CLI configuration commands: - -#### Enable/Disable SPAN (CLI) - set interface span [disable | destination ] - -: mirrored interface name -destination : monitoring interface name -disable: delete mirroring - -#### Enable/Disabl SPAN (API) -SPAN supports the following API configuration command: - sw_interface_span_enable_disable src GigabitEthernet0/8/0 dst GigabitEthernet0/9/0 - sw_interface_span_enable_disable src_sw_if_index 1 dst_sw_if_index 2 - -src/src_sw_if_index: mirrored interface name -dst/dst_sw_if_index: monitoring interface name - -#### Remove SPAN entry (API) -SPAN supports the following API configuration command: - sw_interface_span_enable_disable src_sw_if_index 1 dst_sw_if_index 2 disable - -src_sw_if_index: mirrored interface name -dst_sw_if_index: monitoring interface name - -### Configuration example - -Mirror all packets on interface GigabitEthernet0/10/0 to interface GigabitEthernet0/11/0. - -Configure IPv4 addresses on mirrored interface: -set interface ip address GigabitEthernet0/10/0 192.168.1.13/24 -set interface state GigabitEthernet0/10/0 up - -Configure IPv4 addresses on monitoring interface: -set interface ip address GigabitEthernet0/11/0 192.168.2.13/24 -set interface state GigabitEthernet0/11/0 up - -Configure SPAN -set span src GigabitEthernet0/10/0 dst GigabitEthernet0/11/0 - -### Operational data - -Active SPAN mirroring CLI show command: - show interfaces span - -Active SPAN mirroring API dump command: - sw_interface_span_dump diff --git a/src/vnet/span/span_doc.md b/src/vnet/span/span_doc.md new file mode 100644 index 00000000..46480b28 --- /dev/null +++ b/src/vnet/span/span_doc.md @@ -0,0 +1,65 @@ +# VPP SPAN implementation {#span_doc} + +This is a memo intended to contain documentation of the VPP SPAN implementation. +Everything that is not directly obvious should come here. + + +## Switched Port Analyzer (SPAN) +Port mirroring is used on a network switch to send a copy of network packets seen on one switch port to a network monitoring connection on another switch port. +Can be used by network engineers or administrators to measure performnce, analyze and debug data or diagnose errors on a network. + +### RX traffic node +There is one static node to mirror incomming packets. +* span-input: Creates a copy of incomming buffer due to incomming buffers can be reused internally. + +Chaining: dpdk-input -> span-input -> +* original buffer is sent to ethernet-input for processing +* buffer copy is sent to interface-output + +### Configuration +SPAN supports the following CLI configuration commands: + +#### Enable/Disable SPAN (CLI) + set interface span [disable | destination ] + +: mirrored interface name +destination : monitoring interface name +disable: delete mirroring + +#### Enable/Disabl SPAN (API) +SPAN supports the following API configuration command: + sw_interface_span_enable_disable src GigabitEthernet0/8/0 dst GigabitEthernet0/9/0 + sw_interface_span_enable_disable src_sw_if_index 1 dst_sw_if_index 2 + +src/src_sw_if_index: mirrored interface name +dst/dst_sw_if_index: monitoring interface name + +#### Remove SPAN entry (API) +SPAN supports the following API configuration command: + sw_interface_span_enable_disable src_sw_if_index 1 dst_sw_if_index 2 disable + +src_sw_if_index: mirrored interface name +dst_sw_if_index: monitoring interface name + +### Configuration example + +Mirror all packets on interface GigabitEthernet0/10/0 to interface GigabitEthernet0/11/0. + +Configure IPv4 addresses on mirrored interface: +set interface ip address GigabitEthernet0/10/0 192.168.1.13/24 +set interface state GigabitEthernet0/10/0 up + +Configure IPv4 addresses on monitoring interface: +set interface ip address GigabitEthernet0/11/0 192.168.2.13/24 +set interface state GigabitEthernet0/11/0 up + +Configure SPAN +set span src GigabitEthernet0/10/0 dst GigabitEthernet0/11/0 + +### Operational data + +Active SPAN mirroring CLI show command: + show interfaces span + +Active SPAN mirroring API dump command: + sw_interface_span_dump -- cgit 1.2.3-korg