VPP-221 CLI auto-documentation infrastructure
[Note: This is an amalgamation of several patches cherry-picked from master all related to introducing auto-CLI documentation. See commitsd4024f58ee4743ad16bcf7d8e0d802bc54ccf226] As a step before Doxygen, extract CLI-related struct initializers from the code and parse that into a summary of the CLI commands available with the provided help text, such as it is. At the moment this only renders this into an indexed Markdown file that Doxygen then picks up but later we can use this information to enrich the existing VLIB_CLI_COMMAND macro documentor as well as provide runtime documentation to VPP that is stored on disk outside the binary image. Additionally support a comment block immediately prior to VLIB_CLI_COMMAND CLI command definitions in the form /*? ... ?*/ that can be used to include long-form documentation without having it compiled into VPP. Examples of documenting CLI commands can be found in vlib/vlib/unix/cli.c which, whilst not perfect, should provide a starting point. Screen captures of sample output can be seen at https://chrisy.flirble.org/vpp/doxy-cli-example.png and https://chrisy.flirble.org/vpp/doxy-cli-index.png . Next, shift the Doxygen root makefile targets to their own Makefile. The primary reason for this is that the siphon targets do dependency tracking which means it needs to generate those dependencies whenever make is run; that is pointless if we're not going to generate any documentation. This includes the package dependencies since they since they sometimes unnecessarily interfere with the code build in some cases at the moment; later we will look to building a Python venv to host the Python modules we use. One final remark: In future we may consider deprecating .long_help in the VLIB_CLI_COMMAND structure entirely but add perhaps .usage_help. .short_help would be reserved for a summary of the command function and .usage_help provide the syntax of that command. These changes would provide great semantic value to the automaticly generated CLI documentation. I could also see having .long_help replaced by a mechanism that reads it from disk at runtime with a rudimentary Markdown/Doxygen filter so that we can use the same text that is used in the published documentation. Change-Id: I8afccfd7fe2096411d8064ac954ca5a2cbca9ae7 Signed-off-by: Chris Luke <chrisy@flirble.org>
This commit is contained in:
Chris Luke
3
.gitignore
vendored
3
.gitignore
vendored
@ -1,4 +1,5 @@
|
||||
*~
|
||||
*.sw[op]
|
||||
|
||||
/build-root/.ccache
|
||||
/build-root/build-*/
|
||||
@ -66,6 +67,8 @@ GTAGS
|
||||
|
||||
# Generated documentation
|
||||
/build-root/docs
|
||||
/build-root/.doxygen-bootstrap.ok
|
||||
/build-root/.doxygen-siphon.dep
|
||||
|
||||
# indent backup files
|
||||
*.BAK
|
||||
|
||||
38
Makefile
38
Makefile
@ -30,7 +30,7 @@ OS_VERSION_ID= $(shell grep '^VERSION_ID=' /etc/os-release | cut -f2- -d= | sed
|
||||
DEB_DEPENDS = curl build-essential autoconf automake bison libssl-dev ccache
|
||||
DEB_DEPENDS += debhelper dkms git libtool libganglia1-dev libapr1-dev dh-systemd
|
||||
DEB_DEPENDS += libconfuse-dev git-review exuberant-ctags cscope
|
||||
DEB_DEPENDS += doxygen graphviz
|
||||
DEB_DEPENDS += python-dev
|
||||
ifeq ($(OS_VERSION_ID),14.04)
|
||||
DEB_DEPENDS += openjdk-8-jdk-headless
|
||||
else
|
||||
@ -40,7 +40,7 @@ endif
|
||||
RPM_DEPENDS_GROUPS = 'Development Tools'
|
||||
RPM_DEPENDS = redhat-lsb glibc-static java-1.8.0-openjdk-devel yum-utils
|
||||
RPM_DEPENDS += openssl-devel https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm apr-devel
|
||||
RPM_DEPENDS += doxygen graphviz
|
||||
RPM_DEPENDS += python-devel
|
||||
EPEL_DEPENDS = libconfuse-devel ganglia-devel
|
||||
|
||||
ifneq ($(wildcard $(STARTUP_DIR)/startup.conf),)
|
||||
@ -54,7 +54,7 @@ endif
|
||||
|
||||
.PHONY: help bootstrap wipe wipe-release build build-release rebuild rebuild-release
|
||||
.PHONY: run run-release debug debug-release build-vat run-vat pkg-deb pkg-rpm
|
||||
.PHONY: ctags cscope doxygen wipe-doxygen plugins plugins-release
|
||||
.PHONY: ctags cscope plugins plugins-release build-vpp-api
|
||||
|
||||
help:
|
||||
@echo "Make Targets:"
|
||||
@ -80,6 +80,7 @@ help:
|
||||
@echo " gtags - (re)generate gtags database"
|
||||
@echo " cscope - (re)generate cscope database"
|
||||
@echo " doxygen - (re)generate documentation"
|
||||
@echo " bootstrap-doxygen - setup Doxygen dependencies"
|
||||
@echo " wipe-doxygen - wipe all generated documentation"
|
||||
@echo ""
|
||||
@echo "Make Arguments:"
|
||||
@ -233,24 +234,21 @@ cscope: cscope.files
|
||||
# Build the documentation
|
||||
#
|
||||
|
||||
DOXY_INPUT ?= \
|
||||
README.md \
|
||||
vppinfra \
|
||||
svm \
|
||||
vlib \
|
||||
vlib-api \
|
||||
vnet \
|
||||
vpp \
|
||||
vpp-api
|
||||
# Doxygen configuration and our utility scripts
|
||||
export DOXY_DIR ?= $(WS_ROOT)/doxygen
|
||||
|
||||
define make-doxy
|
||||
@OS_ID="$(OS_ID)" WS_ROOT="$(WS_ROOT)" BR="$(BR)" make -C $(DOXY_DIR) $@
|
||||
endef
|
||||
|
||||
.PHONY: bootstrap-doxygen doxygen wipe-doxygen
|
||||
|
||||
bootstrap-doxygen:
|
||||
$(call make-doxy)
|
||||
|
||||
doxygen:
|
||||
@mkdir -p "$(BR)/docs"
|
||||
ROOT="$(WS_ROOT)" \
|
||||
BUILD_ROOT="$(BR)" \
|
||||
INPUT="$(addprefix $(WS_ROOT)/,$(DOXY_INPUT))" \
|
||||
HTML=YES \
|
||||
VERSION="`git describe --tags --dirty`" \
|
||||
doxygen doxygen/doxygen.cfg
|
||||
$(call make-doxy)
|
||||
|
||||
wipe-doxygen:
|
||||
rm -rf "$(BR)/docs"
|
||||
$(call make-doxy)
|
||||
|
||||
|
||||
154
doxygen/Makefile
Normal file
154
doxygen/Makefile
Normal file
@ -0,0 +1,154 @@
|
||||
# Copyright (c) 2016 Comcast Cable Communications Management, LLC.
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at:
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
|
||||
#
|
||||
# Build the documentation
|
||||
#
|
||||
|
||||
# These should be passed in by the root Makefile
|
||||
WS_ROOT ?= $(CURDIR)/..
|
||||
BR ?= $(WS_ROOT)/build-root
|
||||
OS_ID ?= $(shell grep '^ID=' /etc/os-release | cut -f2- -d= | sed -e 's/\"//g')
|
||||
|
||||
# Package dependencies
|
||||
DOC_DEB_DEPENDS = doxygen graphviz python-pyparsing
|
||||
DOC_RPM_DEPENDS = doxygen graphviz pyparsing
|
||||
|
||||
# Doxygen configuration and our utility scripts
|
||||
DOXY_DIR ?= $(WS_ROOT)/doxygen
|
||||
|
||||
# Input directories and files
|
||||
DOXY_INPUT ?= \
|
||||
README.md \
|
||||
vppinfra \
|
||||
svm \
|
||||
vlib \
|
||||
vlib-api \
|
||||
vnet \
|
||||
vpp \
|
||||
vpp-api \
|
||||
plugins
|
||||
|
||||
# Files to exclude, from pre-Doxygen steps, eg because they're
|
||||
# selectively compiled.
|
||||
# Examples would be to exclude non-DPDK related sources when
|
||||
# there's a DPDK equivalent that conflicts.
|
||||
# This is specifically for the pre-Doxygen steps; Doxygen uses
|
||||
# @cond for this instead.
|
||||
DOXY_PRE_EXCLUDE ?= \
|
||||
vlib/vlib/buffer.c
|
||||
|
||||
# Generate a regexp for filenames to exclude
|
||||
DOXY_PRE_EXCLUDE_REGEXP = ($(subst .,\.,$(shell echo '$(strip $(DOXY_PRE_EXCLUDE))' | sed -e 's/ /|/g')))
|
||||
|
||||
# Discover all the directories we might, possibly, maybe, have include files in
|
||||
DOXY_INCLUDE_PATH = $(shell set -e; cd $(WS_ROOT); for item in $(DOXY_INPUT); do find $$item -type d; done)
|
||||
|
||||
# Discover if we have CPP available
|
||||
CPP ?= $(shell which cpp)
|
||||
ifneq ($(strip $(CPP)),)
|
||||
# Add whatever directories CPP normally includes
|
||||
DOXY_INCLUDE_PATH += $(shell set -e; $(CPP) -v </dev/null 2>&1 | grep -A 1000 '\#include' | awk '/^ /{print $$1}')
|
||||
endif
|
||||
|
||||
# Target directory for doxygen output
|
||||
DOXY_OUTPUT ?= $(BR)/docs
|
||||
|
||||
# Siphoned fragments end up in here
|
||||
SIPHON_INPUT ?= $(DOXY_OUTPUT)/siphon_fragments
|
||||
|
||||
# Siphoned fragements are processed into here
|
||||
SIPHON_OUTPUT ?= $(DOXY_OUTPUT)/siphon_docs
|
||||
|
||||
# Extra document inputs that are processed in addition to DOXY_INPUT
|
||||
EXTRA_DOXY_INPUT += $(SIPHON_OUTPUT)
|
||||
|
||||
# All the siphon types we know about
|
||||
SIPHONS ?= clicmd
|
||||
|
||||
SIPHON_FILES = $(addprefix $(SIPHON_INPUT)/,$(addsuffix .siphon,$(SIPHONS)))
|
||||
SIPHON_DOCS = $(addprefix $(SIPHON_OUTPUT)/,$(addsuffix .md,$(SIPHONS)))
|
||||
|
||||
$(BR)/.doxygen-bootstrap.ok:
|
||||
ifeq ($(OS_ID),ubuntu)
|
||||
@set -e; inst=; \
|
||||
for i in $(DOC_DEB_DEPENDS); do \
|
||||
dpkg-query --show $$i >/dev/null 2>&1 || inst="$$inst $$i"; \
|
||||
done; \
|
||||
if [ "$$inst" ]; then sudo apt-get $(CONFIRM) $(FORCE) install $$inst; fi
|
||||
else ifneq ("$(wildcard /etc/redhat-release)","")
|
||||
@sudo yum install $(CONFIRM) $(DOC_RPM_DEPENDS)
|
||||
else
|
||||
$(error "This option currently works only on Ubuntu or Centos systems")
|
||||
endif
|
||||
@touch $@
|
||||
|
||||
.PHONY: bootstrap-doxygen
|
||||
bootstrap-doxygen: $(BR)/.doxygen-bootstrap.ok
|
||||
|
||||
.DELETE_ON_ERROR: $(BR)/.doxygen-siphon.dep
|
||||
$(BR)/.doxygen-siphon.dep: Makefile
|
||||
set -e; rm -f "$@"; for input in $(DOXY_INPUT); do \
|
||||
find "$(WS_ROOT)/$$input" -type f \
|
||||
\( -name '*.[ch]' -or -name '*.dox' \) -print \
|
||||
| grep -v -E '^$(WS_ROOT)/$(DOXY_PRE_EXCLUDE_REGEXP)$$' \
|
||||
| sed -e "s/^/\$$(SIPHON_FILES): /" \
|
||||
>> $@; \
|
||||
done
|
||||
|
||||
# Include the source -> siphon dependencies
|
||||
-include $(BR)/.doxygen-siphon.dep
|
||||
|
||||
.NOTPARALLEL: $(SIPHON_FILES)
|
||||
$(SIPHON_FILES): $(DOXY_DIR)/siphon_generate.py $(BR)/.doxygen-bootstrap.ok
|
||||
@rm -rf "$(SIPHON_INPUT)" "$(SIPHON_OUTPUT)"
|
||||
@mkdir -p "$(SIPHON_INPUT)" "$(SIPHON_OUTPUT)"
|
||||
@touch $(SIPHON_INPUT)/files
|
||||
for input in $(DOXY_INPUT); do \
|
||||
cd "$(WS_ROOT)"; \
|
||||
find "$$input" -type f \
|
||||
\( -name '*.[ch]' -or -name '*.dox' \) -print \
|
||||
| grep -v -E '^$(DOXY_PRE_EXCLUDE_REGEXP)$$' \
|
||||
>> $(SIPHON_INPUT)/files; \
|
||||
done
|
||||
set -e; cd "$(WS_ROOT)"; $(DOXY_DIR)/siphon_generate.py \
|
||||
--output="$(SIPHON_INPUT)" \
|
||||
"@$(SIPHON_INPUT)/files"
|
||||
|
||||
|
||||
.DELETE_ON_ERROR: $(SIPHON_DOCS)
|
||||
$(SIPHON_OUTPUT)/%.md: $(SIPHON_INPUT)/%.siphon $(DOXY_DIR)/siphon_process.py
|
||||
set -e; cd "$(WS_ROOT)"; \
|
||||
$(DOXY_DIR)/siphon_process.py --type=$(basename $(notdir $<)) \
|
||||
--output="$(SIPHON_OUTPUT)" $< > $@
|
||||
|
||||
# This target can be used just to generate the siphoned docs
|
||||
.PHONY: doxygen-siphon
|
||||
doxygen-siphon: $(SIPHON_DOCS)
|
||||
|
||||
# Generate the doxygen docs
|
||||
doxygen: $(SIPHON_DOCS)
|
||||
@mkdir -p "$(DOXY_OUTPUT)"
|
||||
set -e; cd "$(WS_ROOT)"; \
|
||||
ROOT="$(WS_ROOT)" \
|
||||
BUILD_ROOT="$(BR)" \
|
||||
INPUT="$(addprefix $(WS_ROOT)/,$(DOXY_INPUT)) $(EXTRA_DOXY_INPUT)" \
|
||||
INCLUDE_PATH="$(DOXY_INCLUDE_PATH)" \
|
||||
HTML=YES \
|
||||
VERSION="`git describe --tags --dirty`" \
|
||||
doxygen $(DOXY_DIR)/doxygen.cfg
|
||||
|
||||
wipe-doxygen:
|
||||
rm -rf "$(BR)/docs" "$(BR)/.doxygen-siphon.d"
|
||||
|
||||
@ -18,7 +18,7 @@
|
||||
|
||||
/**
|
||||
@dir
|
||||
@brief Someone please fix this description
|
||||
@brief Someone please fix this description.
|
||||
@todo This directory needs a description.
|
||||
|
||||
This is where you would document the contents of a directory.
|
||||
@ -26,3 +26,4 @@ This is where you would document the contents of a directory.
|
||||
This looks like a C file but it is not part of the build; it is purely
|
||||
for documentation.
|
||||
*/
|
||||
/*? %%clicmd:group_label CLI section description%% ?*/
|
||||
|
||||
@ -229,8 +229,22 @@ TAB_SIZE = 8
|
||||
# newlines.
|
||||
|
||||
ALIASES =
|
||||
|
||||
## Indexes VPP graph nodes
|
||||
ALIASES += "node=@xrefitem nodes \"Node Identifier\" \"Node Identifiers\" @c "
|
||||
|
||||
## Formatting for CLI commands and output
|
||||
ALIASES += "cli{1}=<code><pre>\1</code></pre>"
|
||||
ALIASES += "clistart=<code><pre>"
|
||||
ALIASES += "cliend=</pre></code>"
|
||||
|
||||
## Formatting for CLI example paragraphs
|
||||
ALIASES += "cliexpar=@par Example usage"
|
||||
ALIASES += "cliexcmd{1}=@clistart<b>vpp# <em>\1</em></b>@cliend"
|
||||
ALIASES += "cliexstart{1}=@cliexcmd{\1}@clistart"
|
||||
ALIASES += "cliexend=@cliend"
|
||||
|
||||
|
||||
# This tag can be used to specify a number of word-keyword mappings (TCL only).
|
||||
# A mapping has the form "name=value". For example adding "class=itcl::class"
|
||||
# will allow you to use the command class in the itcl::class meaning.
|
||||
@ -630,7 +644,7 @@ GENERATE_DEPRECATEDLIST= YES
|
||||
# sections, marked by \if <section_label> ... \endif and \cond <section_label>
|
||||
# ... \endcond blocks.
|
||||
|
||||
ENABLED_SECTIONS =
|
||||
ENABLED_SECTIONS = DPDK
|
||||
|
||||
# The MAX_INITIALIZER_LINES tag determines the maximum number of lines that the
|
||||
# initial value of a variable or macro / define can have for it to appear in the
|
||||
@ -901,6 +915,7 @@ INPUT_FILTER =
|
||||
|
||||
FILTER_PATTERNS = \
|
||||
*.c=$(ROOT)/doxygen/filter_c.py \
|
||||
*.h=$(ROOT)/doxygen/filter_h.py \
|
||||
*.api=$(ROOT)/doxygen/filter_api.py
|
||||
|
||||
# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using
|
||||
@ -2022,7 +2037,7 @@ SEARCH_INCLUDES = YES
|
||||
# preprocessor.
|
||||
# This tag requires that the tag SEARCH_INCLUDES is set to YES.
|
||||
|
||||
INCLUDE_PATH = $(INPUT)
|
||||
INCLUDE_PATH = $(INCLUDE_PATH)
|
||||
|
||||
# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
|
||||
# patterns (like *.h and *.hpp) to filter out the header-files in the
|
||||
@ -2046,7 +2061,8 @@ PREDEFINED = \
|
||||
__ORDER_LITTLE_ENDIAN__=1234 \
|
||||
__BYTE_ORDER__=1234 \
|
||||
__FLOAT_WORD_ORDER__=1234 \
|
||||
DPDK=1
|
||||
DPDK=1 \
|
||||
always_inline:="static inline"
|
||||
|
||||
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
|
||||
# tag can be used to specify a list of macro names that should be expanded. The
|
||||
|
||||
@ -15,38 +15,73 @@
|
||||
|
||||
# Filter for .c files to make various preprocessor tricks Doxygenish
|
||||
|
||||
import sys, re
|
||||
import os, sys, re
|
||||
|
||||
if len(sys.argv) < 2:
|
||||
sys.stderr.write("Usage: %s <filename>\n" % (sys.argv[0]))
|
||||
sys.exit(1)
|
||||
|
||||
patterns = [
|
||||
# Search for VLIB_CLI_COMMAND, extract its parameter and add a docblock for it
|
||||
( re.compile("(?P<m>VLIB_CLI_COMMAND)\s*[(](?P<name>[a-zA-Z0-9_]+)(,[^)]*)?[)]"), r"/** @brief (@em constructor) \g<m> (\g<name>) */ vlib_cli_command_t \g<name>"),
|
||||
replace_patterns = [
|
||||
# Search for VLIB_CLI_COMMAND, extract its parameters and add a docblock for it
|
||||
( re.compile("(?P<m>VLIB_CLI_COMMAND)\s*[(](?P<name>[a-zA-Z0-9_]+)[)]"),
|
||||
r"/** @brief (@em constructor) \g<m> (\g<name>) */ vlib_cli_command_t \g<name>"),
|
||||
( re.compile("(?P<m>VLIB_CLI_COMMAND)\s*[(](?P<name>[a-zA-Z0-9_]+),\s*(?P<qual>[^)]*)[)]"),
|
||||
r"/** @brief (@em constructor) \g<m> (\g<name>) */ \g<qual> vlib_cli_command_t \g<name>"),
|
||||
|
||||
# Search for VLIB_REGISTER_NODE, extract its parameter and add a docblock for it
|
||||
( re.compile("(?P<m>VLIB_REGISTER_NODE)\s*[(](?P<name>[a-zA-Z0-9_]+)(,[^)]*)?[)]"), r"/** @brief (@em constructor) \g<m> (\g<name>) */ vlib_node_registration_t \g<name>"),
|
||||
# Search for VLIB_REGISTER_NODE, extract its parameters and add a docblock for it
|
||||
( re.compile("(?P<m>VLIB_REGISTER_NODE)\s*[(](?P<name>[a-zA-Z0-9_]+)[)]"),
|
||||
r"/** @brief (@em constructor) \g<m> (\g<name>) */ vlib_node_registration_t \g<name>"),
|
||||
( re.compile("(?P<m>VLIB_REGISTER_NODE)\s*[(](?P<name>[a-zA-Z0-9_]+),\s*(?P<qual>[^)]*)[)]"),
|
||||
r"/** @brief (@em constructor) \g<m> (\g<name>) */ \g<qual> vlib_node_registration_t \g<name>"),
|
||||
|
||||
# Search for VLIB_INIT_FUNCTION, extract its parameter and add a docblock for it
|
||||
( re.compile("(?P<m>VLIB_INIT_FUNCTION)\s*[(](?P<name>[a-zA-Z0-9_]+)[)]"), r"/** @brief (@em constructor) \g<m> (@ref \g<name>) */ vlib_init_function_t * _vlib_init_function_\g<name>"),
|
||||
( re.compile("(?P<m>VLIB_DECLARE_INIT_FUNCTION)\s*[(](?P<name>[a-zA-Z0-9_]+)[)]"), r"/** @brief (@em constructor) \g<m> (@ref \g<name>) */ vlib_init_function_t * _vlib_init_function_\g<name>"),
|
||||
( re.compile("(?P<m>VLIB_INIT_FUNCTION)\s*[(](?P<name>[a-zA-Z0-9_]+)[)]"),
|
||||
r"/** @brief (@em constructor) \g<m> (@ref \g<name>) */ vlib_init_function_t * _vlib_init_function_\g<name>"),
|
||||
( re.compile("(?P<m>VLIB_DECLARE_INIT_FUNCTION)\s*[(](?P<name>[a-zA-Z0-9_]+)[)]"),
|
||||
r"/** @brief (@em constructor) \g<m> (@ref \g<name>) */ vlib_init_function_t * _vlib_init_function_\g<name>"),
|
||||
|
||||
# Search for VLIB_LOOP_ENTER_FUNCTION, extract the 1st parameter (ignore any others) and add a docblock for it
|
||||
( re.compile("(?P<m>VLIB_MAIN_LOOP_ENTER_FUNCTION)\s*[(](?P<name>[a-zA-Z0-9_]+)(,[^)]*)?[)]"), r"/** @brief (@em constructor) \g<m> (@ref \g<name>) */ _vlib_main_loop_enter_\g<name>"),
|
||||
( re.compile("(?P<m>VLIB_MAIN_LOOP_EXIT_FUNCTION)\s*[(](?P<name>[a-zA-Z0-9_]+)(,[^)]*)?[)]"), r"/** @brief (@em constructor) \g<m> (@ref \g<name>) */ _vlib_main_loop_exit_\g<name>"),
|
||||
# Search for VLIB_LOOP_ENTER_FUNCTION, extract the parameters and add a docblock for it
|
||||
( re.compile("(?P<m>VLIB_MAIN_LOOP_ENTER_FUNCTION)\s*[(](?P<name>[a-zA-Z0-9_]+)(,[^)]*)?[)]"),
|
||||
r"/** @brief (@em constructor) \g<m> (@ref \g<name>) */ _vlib_main_loop_enter_\g<name>"),
|
||||
( re.compile("(?P<m>VLIB_MAIN_LOOP_EXIT_FUNCTION)\s*[(](?P<name>[a-zA-Z0-9_]+)(,[^)]*)?[)]"),
|
||||
r"/** @brief (@em constructor) \g<m> (@ref \g<name>) */ _vlib_main_loop_exit_\g<name>"),
|
||||
|
||||
# Search for VLIB_CONFIG_FUNCTION, extract the 1st parameter (ignore any others) and add a docblock for it
|
||||
( re.compile("(?P<m>VLIB_CONFIG_FUNCTION)\s*[(](?P<name>[a-zA-Z0-9_]+),\s*(?P<n>\"[^\"]+\")(,[^)]*)?[)]"), r"/** @brief (@em constructor) \g<m> (\g<name>, \g<n>) */ vlib_config_function_runtime_t _vlib_config_function_\g<name>"),
|
||||
( re.compile("(?P<m>VLIB_EARLY_CONFIG_FUNCTION)\s*[(](?P<name>[a-zA-Z0-9_]+),\s*(?P<n>\"[^\"]+\")(,[^)]*)?[)]"), r"/** @brief (@em constructor) \g<m> (\g<name>, \g<n>) */ vlib_config_function_runtime_t _vlib_config_function_\g<name>"),
|
||||
# Search for VLIB_CONFIG_FUNCTION, extract the parameters and add a docblock for it
|
||||
( re.compile("(?P<m>VLIB_CONFIG_FUNCTION)\s*[(](?P<name>[a-zA-Z0-9_]+),\s*(?P<n>\"[^\"]+\")(,[^)]*)?[)]"),
|
||||
r"/** @brief (@em constructor) \g<m> (\g<name>, \g<n>) */ vlib_config_function_runtime_t _vlib_config_function_\g<name>"),
|
||||
( re.compile("(?P<m>VLIB_EARLY_CONFIG_FUNCTION)\s*[(](?P<name>[a-zA-Z0-9_]+),\s*(?P<n>\"[^\"]+\")(,[^)]*)?[)]"),
|
||||
r"/** @brief (@em constructor) \g<m> (\g<name>, \g<n>) */ vlib_config_function_runtime_t _vlib_config_function_\g<name>"),
|
||||
|
||||
# Search for "format_thing" and "unformat_thing" when used as a function pointer and add parens
|
||||
( re.compile("(?P<pre>(^|,)\s*)(?P<name>(un)?format_[a-zA-Z0-9_]+)(?P<post>\s*(,|$))") , r"\g<pre>\g<name>()\g<post>" ),
|
||||
( re.compile("(?P<pre>(^|,)\s*)(?P<name>(un)?format_[a-zA-Z0-9_]+)(?P<post>\s*(,|$))"),
|
||||
r"\g<pre>\g<name>()\g<post>" ),
|
||||
|
||||
# Search for CLIB_PAD_FROM_TO(...); and replace with padding
|
||||
# #define CLIB_PAD_FROM_TO(from,to) u8 pad_##from[(to) - (from)]
|
||||
( re.compile("(?P<m>CLIB_PAD_FROM_TO)\s*[(](?P<from>[^,]+),\s*(?P<to>[^)]+)[)]"),
|
||||
r"/** Padding. */ u8 pad_\g<from>[(\g<to>) - (\g<from>)]" ),
|
||||
|
||||
]
|
||||
|
||||
with open(sys.argv[1]) as fd:
|
||||
|
||||
filename = sys.argv[1]
|
||||
cwd = os.getcwd()
|
||||
if filename[0:len(cwd)] == cwd:
|
||||
filename = filename[len(cwd):]
|
||||
if filename[0] == "/":
|
||||
filename = filename[1:]
|
||||
|
||||
with open(filename) as fd:
|
||||
line_num = 0
|
||||
|
||||
for line in fd:
|
||||
line_num += 1
|
||||
str = line[:-1] # filter \n
|
||||
for p in patterns:
|
||||
|
||||
# Look for search/replace patterns
|
||||
for p in replace_patterns:
|
||||
str = p[0].sub(p[1], str)
|
||||
|
||||
sys.stdout.write(str+"\n")
|
||||
|
||||
# All done
|
||||
|
||||
53
doxygen/filter_h.py
Executable file
53
doxygen/filter_h.py
Executable file
@ -0,0 +1,53 @@
|
||||
#!/usr/bin/env python
|
||||
# Copyright (c) 2016 Comcast Cable Communications Management, LLC.
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at:
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
|
||||
# Filter for .c files to make various preprocessor tricks Doxygenish
|
||||
|
||||
import os, sys, re
|
||||
|
||||
if len(sys.argv) < 2:
|
||||
sys.stderr.write("Usage: %s <filename>\n" % (sys.argv[0]))
|
||||
sys.exit(1)
|
||||
|
||||
replace_patterns = [
|
||||
# Search for CLIB_PAD_FROM_TO(...); and replace with padding
|
||||
# #define CLIB_PAD_FROM_TO(from,to) u8 pad_##from[(to) - (from)]
|
||||
( re.compile("(?P<m>CLIB_PAD_FROM_TO)\s*[(](?P<from>[^,]+),\s*(?P<to>[^)]+)[)]"),
|
||||
r"/** Padding. */ u8 pad_\g<from>[(\g<to>) - (\g<from>)]" ),
|
||||
|
||||
]
|
||||
|
||||
|
||||
filename = sys.argv[1]
|
||||
cwd = os.getcwd()
|
||||
if filename[0:len(cwd)] == cwd:
|
||||
filename = filename[len(cwd):]
|
||||
if filename[0] == "/":
|
||||
filename = filename[1:]
|
||||
|
||||
with open(filename) as fd:
|
||||
line_num = 0
|
||||
|
||||
for line in fd:
|
||||
line_num += 1
|
||||
str = line[:-1] # filter \n
|
||||
|
||||
# Look for search/replace patterns
|
||||
for p in replace_patterns:
|
||||
str = p[0].sub(p[1], str)
|
||||
|
||||
sys.stdout.write(str+"\n")
|
||||
|
||||
# All done
|
||||
322
doxygen/siphon_generate.py
Executable file
322
doxygen/siphon_generate.py
Executable file
File diff suppressed because it is too large
Load Diff
323
doxygen/siphon_process.py
Executable file
323
doxygen/siphon_process.py
Executable file
File diff suppressed because it is too large
Load Diff
@ -19,3 +19,5 @@
|
||||
@dir
|
||||
@brief VLIB application library source.
|
||||
*/
|
||||
/*? %%clicmd:group_label VLIB application library%% ?*/
|
||||
|
||||
|
||||
@ -42,6 +42,7 @@
|
||||
* Provides a command line interface so humans can interact with VPP.
|
||||
* This is predominantly a debugging and testing mechanism.
|
||||
*/
|
||||
/*? %%clicmd:group_label Debug CLI %% ?*/
|
||||
|
||||
#include <vlib/vlib.h>
|
||||
#include <vlib/unix/unix.h>
|
||||
@ -146,9 +147,13 @@ typedef struct
|
||||
CLI process. */
|
||||
u8 *input_vector;
|
||||
|
||||
/** This session has command history. */
|
||||
u8 has_history;
|
||||
/** Array of vectors of commands in the history. */
|
||||
u8 **command_history;
|
||||
/** The command currently pointed at by the history cursor. */
|
||||
u8 *current_command;
|
||||
/** How far from the end of the history array the user has browsed. */
|
||||
i32 excursion;
|
||||
|
||||
/** Maximum number of history entries this session will store. */
|
||||
@ -157,7 +162,12 @@ typedef struct
|
||||
/** Current command line counter */
|
||||
u32 command_number;
|
||||
|
||||
/** The string being searched for in the history. */
|
||||
u8 *search_key;
|
||||
/** If non-zero then the CLI is searching in the history array.
|
||||
* - @c -1 means search backwards.
|
||||
* - @c 1 means search forwards.
|
||||
*/
|
||||
int search_mode;
|
||||
|
||||
/** Position of the insert cursor on the current input line */
|
||||
@ -239,34 +249,34 @@ typedef enum
|
||||
UNIX_CLI_PARSE_ACTION_ERASERIGHT, /**< Erase cursor right */
|
||||
UNIX_CLI_PARSE_ACTION_UP, /**< Up arrow */
|
||||
UNIX_CLI_PARSE_ACTION_DOWN, /**< Down arrow */
|
||||
UNIX_CLI_PARSE_ACTION_LEFT,
|
||||
UNIX_CLI_PARSE_ACTION_RIGHT,
|
||||
UNIX_CLI_PARSE_ACTION_HOME,
|
||||
UNIX_CLI_PARSE_ACTION_END,
|
||||
UNIX_CLI_PARSE_ACTION_WORDLEFT,
|
||||
UNIX_CLI_PARSE_ACTION_WORDRIGHT,
|
||||
UNIX_CLI_PARSE_ACTION_ERASELINELEFT,
|
||||
UNIX_CLI_PARSE_ACTION_ERASELINERIGHT,
|
||||
UNIX_CLI_PARSE_ACTION_CLEAR,
|
||||
UNIX_CLI_PARSE_ACTION_REVSEARCH,
|
||||
UNIX_CLI_PARSE_ACTION_FWDSEARCH,
|
||||
UNIX_CLI_PARSE_ACTION_YANK,
|
||||
UNIX_CLI_PARSE_ACTION_TELNETIAC,
|
||||
UNIX_CLI_PARSE_ACTION_LEFT, /**< Left arrow */
|
||||
UNIX_CLI_PARSE_ACTION_RIGHT, /**< Right arrow */
|
||||
UNIX_CLI_PARSE_ACTION_HOME, /**< Home key (jump to start of line) */
|
||||
UNIX_CLI_PARSE_ACTION_END, /**< End key (jump to end of line) */
|
||||
UNIX_CLI_PARSE_ACTION_WORDLEFT, /**< Jump cursor to start of left word */
|
||||
UNIX_CLI_PARSE_ACTION_WORDRIGHT, /**< Jump cursor to start of right word */
|
||||
UNIX_CLI_PARSE_ACTION_ERASELINELEFT, /**< Erase line to left of cursor */
|
||||
UNIX_CLI_PARSE_ACTION_ERASELINERIGHT, /**< Erase line to right & including cursor */
|
||||
UNIX_CLI_PARSE_ACTION_CLEAR, /**< Clear the terminal */
|
||||
UNIX_CLI_PARSE_ACTION_REVSEARCH, /**< Search backwards in command history */
|
||||
UNIX_CLI_PARSE_ACTION_FWDSEARCH, /**< Search forwards in command history */
|
||||
UNIX_CLI_PARSE_ACTION_YANK, /**< Undo last erase action */
|
||||
UNIX_CLI_PARSE_ACTION_TELNETIAC, /**< Telnet control code */
|
||||
|
||||
UNIX_CLI_PARSE_ACTION_PAGER_CRLF,
|
||||
UNIX_CLI_PARSE_ACTION_PAGER_QUIT,
|
||||
UNIX_CLI_PARSE_ACTION_PAGER_NEXT,
|
||||
UNIX_CLI_PARSE_ACTION_PAGER_DN,
|
||||
UNIX_CLI_PARSE_ACTION_PAGER_UP,
|
||||
UNIX_CLI_PARSE_ACTION_PAGER_TOP,
|
||||
UNIX_CLI_PARSE_ACTION_PAGER_BOTTOM,
|
||||
UNIX_CLI_PARSE_ACTION_PAGER_PGDN,
|
||||
UNIX_CLI_PARSE_ACTION_PAGER_PGUP,
|
||||
UNIX_CLI_PARSE_ACTION_PAGER_REDRAW,
|
||||
UNIX_CLI_PARSE_ACTION_PAGER_SEARCH,
|
||||
UNIX_CLI_PARSE_ACTION_PAGER_CRLF, /**< Enter pressed (CR, CRLF, LF, etc) */
|
||||
UNIX_CLI_PARSE_ACTION_PAGER_QUIT, /**< Exit the pager session */
|
||||
UNIX_CLI_PARSE_ACTION_PAGER_NEXT, /**< Scroll to next page */
|
||||
UNIX_CLI_PARSE_ACTION_PAGER_DN, /**< Scroll to next line */
|
||||
UNIX_CLI_PARSE_ACTION_PAGER_UP, /**< Scroll to previous line */
|
||||
UNIX_CLI_PARSE_ACTION_PAGER_TOP, /**< Scroll to first line */
|
||||
UNIX_CLI_PARSE_ACTION_PAGER_BOTTOM, /**< Scroll to last line */
|
||||
UNIX_CLI_PARSE_ACTION_PAGER_PGDN, /**< Scroll to next page */
|
||||
UNIX_CLI_PARSE_ACTION_PAGER_PGUP, /**< Scroll to previous page */
|
||||
UNIX_CLI_PARSE_ACTION_PAGER_REDRAW, /**< Clear and redraw the page on the terminal */
|
||||
UNIX_CLI_PARSE_ACTION_PAGER_SEARCH, /**< Search the pager buffer */
|
||||
|
||||
UNIX_CLI_PARSE_ACTION_PARTIALMATCH,
|
||||
UNIX_CLI_PARSE_ACTION_NOMATCH
|
||||
UNIX_CLI_PARSE_ACTION_PARTIALMATCH, /**< Action parser found a partial match */
|
||||
UNIX_CLI_PARSE_ACTION_NOMATCH /**< Action parser did not find any match */
|
||||
} unix_cli_parse_action_t;
|
||||
|
||||
/** @brief Mapping of input buffer strings to action values.
|
||||
@ -485,6 +495,9 @@ unix_cli_match_action (unix_cli_parse_actions_t * a,
|
||||
}
|
||||
|
||||
|
||||
/** Add bytes to the output vector and then flagg the I/O system that bytes
|
||||
* are available to be sent.
|
||||
*/
|
||||
static void
|
||||
unix_cli_add_pending_output (unix_file_t * uf,
|
||||
unix_cli_file_t * cf,
|
||||
@ -502,6 +515,9 @@ unix_cli_add_pending_output (unix_file_t * uf,
|
||||
}
|
||||
}
|
||||
|
||||
/** Delete all bytes from the output vector and flag the I/O system
|
||||
* that no more bytes are available to be sent.
|
||||
*/
|
||||
static void
|
||||
unix_cli_del_pending_output (unix_file_t * uf,
|
||||
unix_cli_file_t * cf, uword n_bytes)
|
||||
@ -983,13 +999,13 @@ unix_vlib_cli_output (uword cli_file_index, u8 * buffer, uword buffer_bytes)
|
||||
|
||||
/** Identify whether a terminal type is ANSI capable.
|
||||
*
|
||||
* Compares the string given in @term with a list of terminal types known
|
||||
* Compares the string given in @c term with a list of terminal types known
|
||||
* to support ANSI escape sequences.
|
||||
*
|
||||
* This list contains, for example, @c xterm, @c screen and @c ansi.
|
||||
*
|
||||
* @param term A string with a terminal type in it.
|
||||
* @param len The length of the string in @term.
|
||||
* @param len The length of the string in @c term.
|
||||
*
|
||||
* @return @c 1 if the terminal type is recognized as supporting ANSI
|
||||
* terminal sequences; @c 0 otherwise.
|
||||
@ -2059,6 +2075,10 @@ done:
|
||||
goto more;
|
||||
}
|
||||
|
||||
/** Destroy a CLI session.
|
||||
* @note If we destroy the @c stdin session this additionally signals
|
||||
* the shutdown of VPP.
|
||||
*/
|
||||
static void
|
||||
unix_cli_kill (unix_cli_main_t * cm, uword cli_file_index)
|
||||
{
|
||||
@ -2088,6 +2108,7 @@ unix_cli_kill (unix_cli_main_t * cm, uword cli_file_index)
|
||||
pool_put (cm->cli_file_pool, cf);
|
||||
}
|
||||
|
||||
/** Handle system events. */
|
||||
static uword
|
||||
unix_cli_process (vlib_main_t * vm,
|
||||
vlib_node_runtime_t * rt, vlib_frame_t * f)
|
||||
@ -2130,6 +2151,8 @@ done:
|
||||
return 0;
|
||||
}
|
||||
|
||||
/** Called when a CLI session file descriptor can be written to without
|
||||
* blocking. */
|
||||
static clib_error_t *
|
||||
unix_cli_write_ready (unix_file_t * uf)
|
||||
{
|
||||
@ -2152,6 +2175,7 @@ unix_cli_write_ready (unix_file_t * uf)
|
||||
return /* no error */ 0;
|
||||
}
|
||||
|
||||
/** Called when a CLI session file descriptor has data to be read. */
|
||||
static clib_error_t *
|
||||
unix_cli_read_ready (unix_file_t * uf)
|
||||
{
|
||||
@ -2482,8 +2506,8 @@ unix_cli_config (vlib_main_t * vm, unformat_input_t * input)
|
||||
|
||||
VLIB_CONFIG_FUNCTION (unix_cli_config, "unix-cli");
|
||||
|
||||
/** Called when VPP is shutting down, this resets the system
|
||||
* terminal state, if previously saved.
|
||||
/** Called when VPP is shutting down, this restores the system
|
||||
* terminal state if previously saved.
|
||||
*/
|
||||
static clib_error_t *
|
||||
unix_cli_exit (vlib_main_t * vm)
|
||||
@ -2500,7 +2524,7 @@ unix_cli_exit (vlib_main_t * vm)
|
||||
VLIB_MAIN_LOOP_EXIT_FUNCTION (unix_cli_exit);
|
||||
|
||||
/** Set the CLI prompt.
|
||||
* @param The C string to set the prompt to.
|
||||
* @param prompt The C string to set the prompt to.
|
||||
* @note This setting is global; it impacts all current
|
||||
* and future CLI sessions.
|
||||
*/
|
||||
@ -2531,6 +2555,12 @@ unix_cli_quit (vlib_main_t * vm,
|
||||
return 0;
|
||||
}
|
||||
|
||||
/*?
|
||||
* Terminates the current CLI session.
|
||||
*
|
||||
* If VPP is running in @em interactive mode and this is the console session
|
||||
* (that is, the session on @c stdin) then this will also terminate VPP.
|
||||
?*/
|
||||
/* *INDENT-OFF* */
|
||||
VLIB_CLI_COMMAND (unix_cli_quit_command, static) = {
|
||||
.path = "quit",
|
||||
@ -2597,6 +2627,13 @@ done:
|
||||
return error;
|
||||
}
|
||||
|
||||
/*?
|
||||
* Executes a sequence of CLI commands which are read from a file.
|
||||
*
|
||||
* If a command is unrecognised or otherwise invalid then the usual CLI
|
||||
* feedback will be generated, however execution of subsequent commands
|
||||
* from the file will continue.
|
||||
?*/
|
||||
/* *INDENT-OFF* */
|
||||
VLIB_CLI_COMMAND (cli_exec, static) = {
|
||||
.path = "exec",
|
||||
@ -2706,6 +2743,9 @@ unix_cli_show_history (vlib_main_t * vm,
|
||||
return 0;
|
||||
}
|
||||
|
||||
/*?
|
||||
* Displays the command history for the current session, if any.
|
||||
?*/
|
||||
/* *INDENT-OFF* */
|
||||
VLIB_CLI_COMMAND (cli_unix_cli_show_history, static) = {
|
||||
.path = "history",
|
||||
@ -2755,6 +2795,24 @@ unix_cli_show_terminal (vlib_main_t * vm,
|
||||
return 0;
|
||||
}
|
||||
|
||||
/*?
|
||||
* Displays various information about the state of the current terminal
|
||||
* session.
|
||||
*
|
||||
* @cliexpar
|
||||
* @cliexstart{show terminal}
|
||||
* Terminal name: unix-cli-stdin
|
||||
* Terminal mode: char-by-char
|
||||
* Terminal width: 123
|
||||
* Terminal height: 48
|
||||
* ANSI capable: yes
|
||||
* History enabled: yes
|
||||
* History limit: 50
|
||||
* Pager enabled: yes
|
||||
* Pager limit: 100000
|
||||
* CRLF mode: LF
|
||||
* @cliexend
|
||||
?*/
|
||||
/* *INDENT-OFF* */
|
||||
VLIB_CLI_COMMAND (cli_unix_cli_show_terminal, static) = {
|
||||
.path = "show terminal",
|
||||
@ -2799,6 +2857,13 @@ unix_cli_set_terminal_pager (vlib_main_t * vm,
|
||||
return 0;
|
||||
}
|
||||
|
||||
/*?
|
||||
* Enables or disables the terminal pager for this session. Generally
|
||||
* this defaults to enabled.
|
||||
*
|
||||
* Additionally allows the pager buffer size to be set; though note that
|
||||
* this value is set globally and not per session.
|
||||
?*/
|
||||
/* *INDENT-OFF* */
|
||||
VLIB_CLI_COMMAND (cli_unix_cli_set_terminal_pager, static) = {
|
||||
.path = "set terminal pager",
|
||||
@ -2850,6 +2915,13 @@ unix_cli_set_terminal_history (vlib_main_t * vm,
|
||||
return 0;
|
||||
}
|
||||
|
||||
/*?
|
||||
* Enables or disables the command history function of the current
|
||||
* terminal. Generally this defaults to enabled.
|
||||
*
|
||||
* This command also allows the maximum size of the history buffer for
|
||||
* this session to be altered.
|
||||
?*/
|
||||
/* *INDENT-OFF* */
|
||||
VLIB_CLI_COMMAND (cli_unix_cli_set_terminal_history, static) = {
|
||||
.path = "set terminal history",
|
||||
@ -2880,6 +2952,14 @@ unix_cli_set_terminal_ansi (vlib_main_t * vm,
|
||||
return 0;
|
||||
}
|
||||
|
||||
/*?
|
||||
* Enables or disables the use of ANSI control sequences by this terminal.
|
||||
* The default will vary based on terminal detection at the start of the
|
||||
* session.
|
||||
*
|
||||
* ANSI control sequences are used in a small number of places to provide,
|
||||
* for example, color text output and to control the cursor in the pager.
|
||||
?*/
|
||||
/* *INDENT-OFF* */
|
||||
VLIB_CLI_COMMAND (cli_unix_cli_set_terminal_ansi, static) = {
|
||||
.path = "set terminal ansi",
|
||||
|
||||
27
vlib/vlib/unix/dir.dox
Normal file
27
vlib/vlib/unix/dir.dox
Normal file
@ -0,0 +1,27 @@
|
||||
/*
|
||||
* Copyright (c) 2016 Comcast Cable Communications Management, LLC.
|
||||
*
|
||||
* Licensed under the Apache License, Version 2.0 (the "License");
|
||||
* you may not use this file except in compliance with the License.
|
||||
* You may obtain a copy of the License at:
|
||||
*
|
||||
* http://www.apache.org/licenses/LICENSE-2.0
|
||||
*
|
||||
* Unless required by applicable law or agreed to in writing, software
|
||||
* distributed under the License is distributed on an "AS IS" BASIS,
|
||||
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
* See the License for the specific language governing permissions and
|
||||
* limitations under the License.
|
||||
*/
|
||||
|
||||
/* Doxygen directory documentation */
|
||||
|
||||
/**
|
||||
@dir
|
||||
@brief VLIB Unix interface
|
||||
|
||||
VLIB application library Unix interface layer.
|
||||
|
||||
*/
|
||||
/*? %%clicmd:group_label VLIB Unix stuff%% ?*/
|
||||
|
||||
Reference in New Issue
Block a user