diff options
27 files changed, 208 insertions, 112 deletions
diff --git a/doxygen/Makefile b/doxygen/Makefile index 8e916526141..df7d07d72ea 100644 --- a/doxygen/Makefile +++ b/doxygen/Makefile @@ -40,6 +40,9 @@ DOXY_INPUT ?= \ vpp-api \ plugins +DOXY_INCLUDE_PATH = $(shell set -e; cd $(WS_ROOT); for item in $(DOXY_INPUT); do find $$item -type d; done) +DOXY_INCLUDE_PATH += $(shell set -e; cpp -v </dev/null 2>&1 | grep -A 1000 '\#include' | awk '/^ /{print $$1}') + # Target directory for doxygen output DOXY_OUTPUT ?= $(BR)/docs @@ -114,6 +117,7 @@ doxygen: $(SIPHON_DOCS) 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 diff --git a/doxygen/doxygen.cfg b/doxygen/doxygen.cfg index 82687cac42c..4eb0f373049 100644 --- a/doxygen/doxygen.cfg +++ b/doxygen/doxygen.cfg @@ -234,6 +234,7 @@ ALIASES = 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>" @@ -914,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 @@ -2035,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 diff --git a/doxygen/filter_c.py b/doxygen/filter_c.py index 733fdefb3d4..30b933ba79e 100755 --- a/doxygen/filter_c.py +++ b/doxygen/filter_c.py @@ -22,26 +22,45 @@ if len(sys.argv) < 2: sys.exit(1) replace_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>"), - - # 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_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 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 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 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 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 "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>" ), - # 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 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>)]" ), - # 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>" ), ] diff --git a/doxygen/filter_h.py b/doxygen/filter_h.py new file mode 100755 index 00000000000..967388d5743 --- /dev/null +++ b/doxygen/filter_h.py @@ -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 diff --git a/vnet/vnet/interface_cli.c b/vnet/vnet/interface_cli.c index 7b9f5458eb5..654edcaa299 100644 --- a/vnet/vnet/interface_cli.c +++ b/vnet/vnet/interface_cli.c @@ -37,6 +37,11 @@ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ +/** + * @file + * Interface CLI. + */ + #include <vnet/vnet.h> #include <vnet/ip/ip.h> #include <vppinfra/bitmap.h> @@ -432,7 +437,9 @@ VLIB_CLI_COMMAND (clear_interface_counters_command, static) = { }; /* *INDENT-ON* */ -/** \detail +/** + * Parse subinterface names. + * * The following subinterface syntax is supported. The first two are for * backwards compatability: * diff --git a/vnet/vnet/ip/lookup.h b/vnet/vnet/ip/lookup.h index fcd080a4375..dcc9d25fed0 100644 --- a/vnet/vnet/ip/lookup.h +++ b/vnet/vnet/ip/lookup.h @@ -37,11 +37,15 @@ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ -/** @file Definitions for all things IP (v4|v6) unicast and multicast lookup related. - - Adjacency definitions and registration - - callbacks on route add - - callbacks on interface address change +/** + * @file + * Definitions for all things IP (v4|v6) unicast and multicast lookup related. + * + * - Adjacency definitions and registration. + * - Callbacks on route add. + * - Callbacks on interface address change. */ + #ifndef included_ip_lookup_h #define included_ip_lookup_h diff --git a/vnet/vnet/ipsec-gre/error.def b/vnet/vnet/ipsec-gre/error.def index 0d7b4686f8a..d84e8ed1759 100644 --- a/vnet/vnet/ipsec-gre/error.def +++ b/vnet/vnet/ipsec-gre/error.def @@ -13,7 +13,7 @@ * limitations under the License. */ /** - * @file error.def + * @file * @brief L2-GRE over IPSec errors. */ diff --git a/vnet/vnet/ipsec-gre/interface.c b/vnet/vnet/ipsec-gre/interface.c index 3e5d3954341..dbf9df5628a 100644 --- a/vnet/vnet/ipsec-gre/interface.c +++ b/vnet/vnet/ipsec-gre/interface.c @@ -15,7 +15,7 @@ * limitations under the License. */ /** - * @file interface.c + * @file * @brief L2-GRE over IPSec tunnel interface. * * Creates ipsec-gre tunnel interface. diff --git a/vnet/vnet/ipsec-gre/ipsec_gre.c b/vnet/vnet/ipsec-gre/ipsec_gre.c index 24ec6f4e9d6..3d1b54fc7f9 100644 --- a/vnet/vnet/ipsec-gre/ipsec_gre.c +++ b/vnet/vnet/ipsec-gre/ipsec_gre.c @@ -13,7 +13,7 @@ * limitations under the License. */ /** - * @file ipsec_gre.c + * @file * @brief L2-GRE over IPSec packet processing. * * Add GRE header to thr packet and send it to the esp-encrypt node. diff --git a/vnet/vnet/ipsec-gre/ipsec_gre.h b/vnet/vnet/ipsec-gre/ipsec_gre.h index 2b66c6a6e8a..a2ca64b6f74 100644 --- a/vnet/vnet/ipsec-gre/ipsec_gre.h +++ b/vnet/vnet/ipsec-gre/ipsec_gre.h @@ -13,7 +13,7 @@ * limitations under the License. */ /** - * @file ipsec_gre.h + * @file * @brief L2-GRE over IPSec packet processing. */ diff --git a/vnet/vnet/ipsec-gre/node.c b/vnet/vnet/ipsec-gre/node.c index 131025521f3..5a176088862 100644 --- a/vnet/vnet/ipsec-gre/node.c +++ b/vnet/vnet/ipsec-gre/node.c @@ -13,10 +13,10 @@ * limitations under the License. */ /** - * @file node.c + * @file * @brief L2-GRE over IPSec packet processing. * - * Removes GRE header from the packet and send it to the l2-input node. + * Removes GRE header from the packet and sends it to the l2-input node. */ #include <vlib/vlib.h> @@ -68,7 +68,7 @@ u8 * format_ipsec_gre_rx_trace (u8 * s, va_list * args) * * @par Graph mechanics: buffer metadata, next index usage * - * <em>Uses:<em> + * <em>Uses:</em> * - <code>ip->src_address</code> and <code>ip->dst_address</code> * - Match tunnel by source and destination addresses in GRE IP header. * diff --git a/vnet/vnet/l2/l2_bd.c b/vnet/vnet/l2/l2_bd.c index 490a08f2d03..ddbe934abeb 100644 --- a/vnet/vnet/l2/l2_bd.c +++ b/vnet/vnet/l2/l2_bd.c @@ -35,7 +35,7 @@ bd_main_t bd_main; /** - Init bridge domain if not done already + Init bridge domain if not done already. For feature bitmap, set all bits except ARP termination */ void @@ -175,7 +175,7 @@ VLIB_INIT_FUNCTION (l2bd_init); /** - Set the learn/forward/flood flags for the bridge domain + Set the learn/forward/flood flags for the bridge domain. Return 0 if ok, non-zero if for an error. */ u32 @@ -224,7 +224,7 @@ bd_set_flags (vlib_main_t * vm, u32 bd_index, u32 flags, u32 enable) } /** - set bridge-domain learn enable/disable + Set bridge-domain learn enable/disable. The CLI format is: set bridge-domain learn <bd_id> [disable] */ @@ -279,7 +279,7 @@ VLIB_CLI_COMMAND (bd_learn_cli, static) = { /* *INDENT-ON* */ /** - set bridge-domain forward enable/disable + Set bridge-domain forward enable/disable. The CLI format is: set bridge-domain forward <bd_index> [disable] */ @@ -333,7 +333,7 @@ VLIB_CLI_COMMAND (bd_fwd_cli, static) = { /* *INDENT-ON* */ /** - set bridge-domain flood enable/disable + Set bridge-domain flood enable/disable. The CLI format is: set bridge-domain flood <bd_index> [disable] */ @@ -388,7 +388,7 @@ VLIB_CLI_COMMAND (bd_flood_cli, static) = { /* *INDENT-ON* */ /** - set bridge-domain unkown-unicast flood enable/disable + Set bridge-domain unkown-unicast flood enable/disable. The CLI format is: set bridge-domain uu-flood <bd_index> [disable] */ @@ -443,7 +443,7 @@ VLIB_CLI_COMMAND (bd_uu_flood_cli, static) = { /* *INDENT-ON* */ /** - set bridge-domain arp term enable/disable + Set bridge-domain arp term enable/disable. The CLI format is: set bridge-domain arp term <bridge-domain-id> [disable] */ @@ -496,11 +496,15 @@ VLIB_CLI_COMMAND (bd_arp_term_cli, static) = { /** + * Add/delete IP address to MAC address mapping. + * * The clib hash implementation stores uword entries in the hash table. * The hash table mac_by_ip4 is keyed via IP4 address and store the * 6-byte MAC address directly in the hash table entry uword. - * This only works for 64-bit processor with 8-byte uword; which means - * this code *WILL NOT WORK* for a 32-bit prcessor with 4-byte uword. + * + * @warning This only works for 64-bit processor with 8-byte uword; + * which means this code *WILL NOT WORK* for a 32-bit prcessor with + * 4-byte uword. */ u32 bd_add_del_ip_mac (u32 bd_index, @@ -573,7 +577,7 @@ bd_add_del_ip_mac (u32 bd_index, } /** - set bridge-domain arp entry add/delete + Set bridge-domain arp entry add/delete. The CLI format is: set bridge-domain arp entry <bd-id> <ip-addr> <mac-addr> [del] */ @@ -689,7 +693,7 @@ format_vtr (u8 * s, va_list * args) } /** - show bridge-domain state + Show bridge-domain state. The CLI format is: show bridge-domain [<bd_index>] */ diff --git a/vnet/vnet/l2/l2_efp_filter.c b/vnet/vnet/l2/l2_efp_filter.c index 221db9abc73..2038dce2737 100644 --- a/vnet/vnet/l2/l2_efp_filter.c +++ b/vnet/vnet/l2/l2_efp_filter.c @@ -97,7 +97,7 @@ typedef enum /** * Extract fields from the packet that will be used in interface - * classification + * classification. */ static_always_inline void extract_keys (vnet_main_t * vnet_main, @@ -524,7 +524,7 @@ VLIB_NODE_FUNCTION_MULTIARCH (l2_efp_filter_node, l2_efp_filter_node_fn) VLIB_INIT_FUNCTION (l2_efp_filter_init); -/** Enable/disable the EFP Filter check on the subinterface */ +/** Enable/disable the EFP Filter check on the subinterface. */ void l2_efp_filter_configure (vnet_main_t * vnet_main, u32 sw_if_index, u32 enable) { @@ -534,7 +534,7 @@ l2_efp_filter_configure (vnet_main_t * vnet_main, u32 sw_if_index, u32 enable) /** - * set subinterface egress efp filter enable/disable + * Set subinterface egress efp filter enable/disable. * The CLI format is: * set interface l2 efp-filter <interface> [disable]] */ diff --git a/vnet/vnet/l2/l2_fib.c b/vnet/vnet/l2/l2_fib.c index 4275e884ce0..97620bfba6b 100644 --- a/vnet/vnet/l2/l2_fib.c +++ b/vnet/vnet/l2/l2_fib.c @@ -97,7 +97,7 @@ l2fib_table_dump (u32 bd_index, l2fib_entry_key_t ** l2fe_key, } } -/** Display the contents of the l2fib */ +/** Display the contents of the l2fib. */ static clib_error_t * show_l2fib (vlib_main_t * vm, unformat_input_t * input, vlib_cli_command_t * cmd) @@ -228,8 +228,8 @@ l2fib_clear_table (uint keep_static) l2learn_main.global_learn_count = 0; } -/** Clear all entries in L2FIB - * TODO: Later we may want a way to remove only the non-static entries +/** Clear all entries in L2FIB. + * @TODO: Later we may want a way to remove only the non-static entries */ static clib_error_t * clear_l2fib (vlib_main_t * vm, @@ -286,7 +286,7 @@ l2fib_add_entry (u64 mac, } /** - * Add an entry to the L2FIB + * Add an entry to the L2FIB. * The CLI format is: * l2fib add <mac> <bd> <intf> [static] [bvi] * l2fib add <mac> <bd> filter @@ -517,7 +517,7 @@ l2fib_del_entry (u64 mac, u32 bd_index) } /** - * Delete an entry from the L2FIB + * Delete an entry from the L2FIB. * The CLI format is: * l2fib del <mac> <bd-id> */ diff --git a/vnet/vnet/l2/l2_flood.c b/vnet/vnet/l2/l2_flood.c index 0654fe293b8..05df2a014d9 100644 --- a/vnet/vnet/l2/l2_flood.c +++ b/vnet/vnet/l2/l2_flood.c @@ -490,7 +490,7 @@ VLIB_INIT_FUNCTION (l2flood_init); -/** Add the L3 input node for this ethertype to the next nodes structure */ +/** Add the L3 input node for this ethertype to the next nodes structure. */ void l2flood_register_input_type (vlib_main_t * vm, ethernet_type_t type, u32 node_index) @@ -505,7 +505,7 @@ l2flood_register_input_type (vlib_main_t * vm, /** - * set subinterface flood enable/disable + * Set subinterface flood enable/disable. * The CLI format is: * set interface l2 flood <interface> [disable] */ diff --git a/vnet/vnet/l2/l2_fwd.c b/vnet/vnet/l2/l2_fwd.c index 4950b23a8f0..8fa355e01a0 100644 --- a/vnet/vnet/l2/l2_fwd.c +++ b/vnet/vnet/l2/l2_fwd.c @@ -104,7 +104,7 @@ typedef enum L2FWD_N_NEXT, } l2fwd_next_t; -/** Forward one packet based on the mac table lookup result */ +/** Forward one packet based on the mac table lookup result. */ static_always_inline void l2fwd_process (vlib_main_t * vm, @@ -400,7 +400,7 @@ VLIB_NODE_FUNCTION_MULTIARCH (l2fwd_node, l2fwd_node_fn) VLIB_INIT_FUNCTION (l2fwd_init); -/** Add the L3 input node for this ethertype to the next nodes structure */ +/** Add the L3 input node for this ethertype to the next nodes structure. */ void l2fwd_register_input_type (vlib_main_t * vm, ethernet_type_t type, u32 node_index) @@ -415,7 +415,7 @@ l2fwd_register_input_type (vlib_main_t * vm, /** - * set subinterface forward enable/disable + * Set subinterface forward enable/disable. * The CLI format is: * set interface l2 forward <interface> [disable] */ diff --git a/vnet/vnet/l2/l2_input.c b/vnet/vnet/l2/l2_input.c index 5c39b797fef..24cb31fbd7c 100644 --- a/vnet/vnet/l2/l2_input.c +++ b/vnet/vnet/l2/l2_input.c @@ -490,7 +490,7 @@ VLIB_NODE_FUNCTION_MULTIARCH (l2input_node, l2input_node_fn) VLIB_INIT_FUNCTION (l2input_init); -/** Get a pointer to the config for the given interface */ +/** Get a pointer to the config for the given interface. */ l2_input_config_t * l2input_intf_config (u32 sw_if_index) { @@ -500,7 +500,7 @@ l2input_intf_config (u32 sw_if_index) return vec_elt_at_index (mp->configs, sw_if_index); } -/** Enable (or disable) the feature in the bitmap for the given interface */ +/** Enable (or disable) the feature in the bitmap for the given interface. */ u32 l2input_intf_bitmap_enable (u32 sw_if_index, u32 feature_bitmap, u32 enable) { @@ -536,10 +536,10 @@ l2input_set_bridge_features (u32 bd_index, u32 feat_mask, u32 feat_value) /** * Set the subinterface to run in l2 or l3 mode. - * for L3 mode, just the sw_if_index is specified - * for bridged mode, the bd id and bvi flag are also specified - * for xconnect mode, the peer sw_if_index is also specified - * Return 0 if ok, or non-0 if there was an error + * For L3 mode, just the sw_if_index is specified. + * For bridged mode, the bd id and bvi flag are also specified. + * For xconnect mode, the peer sw_if_index is also specified. + * Return 0 if ok, or non-0 if there was an error. */ u32 @@ -771,7 +771,7 @@ set_int_l2_mode (vlib_main_t * vm, vnet_main_t * vnet_main, u32 mode, u32 sw_if_ } /** - * set subinterface in bridging mode with a bridge-domain ID + * Set subinterface in bridging mode with a bridge-domain ID. * The CLI format is: * set interface l2 bridge <interface> <bd> [bvi] [split-horizon-group] */ @@ -847,7 +847,7 @@ VLIB_CLI_COMMAND (int_l2_bridge_cli, static) = { /* *INDENT-ON* */ /** - * set subinterface in xconnect mode with another interface + * Set subinterface in xconnect mode with another interface. * The CLI format is: * set interface l2 xconnect <interface> <peer interface> */ @@ -897,7 +897,7 @@ VLIB_CLI_COMMAND (int_l2_xc_cli, static) = { /* *INDENT-ON* */ /** - * set subinterface in L3 mode + * Set subinterface in L3 mode. * The CLI format is: * set interface l3 <interface> */ @@ -936,6 +936,7 @@ VLIB_CLI_COMMAND (int_l3_cli, static) = { /* *INDENT-ON* */ /** + * Show interface mode. * The CLI format is: * show mode [<if-name1> <if-name2> ...] */ diff --git a/vnet/vnet/l2/l2_input_classify.c b/vnet/vnet/l2/l2_input_classify.c index 1b9f911cf24..69cd113d093 100644 --- a/vnet/vnet/l2/l2_input_classify.c +++ b/vnet/vnet/l2/l2_input_classify.c @@ -21,13 +21,14 @@ /** * @file - * @brief L2 input classifier + * @brief L2 input classifier. * - * See also .../vnet/vnet/classify/vnet_classify.[ch] + * @sa @ref vnet/vnet/classify/vnet_classify.c + * @sa @ref vnet/vnet/classify/vnet_classify.h */ /** - * @brief l2_input_classifier packet trace record + * @brief l2_input_classifier packet trace record. */ typedef struct { @@ -42,7 +43,7 @@ typedef struct } l2_input_classify_trace_t; /** - * @brief vlib node runtime + * @brief vlib node runtime. */ typedef struct { @@ -52,7 +53,7 @@ typedef struct l2_input_classify_main_t *l2cm; } l2_input_classify_runtime_t; -/** packet trace format function */ +/** Packet trace format function. */ static u8 * format_l2_input_classify_trace (u8 * s, va_list * args) { @@ -66,7 +67,7 @@ format_l2_input_classify_trace (u8 * s, va_list * args) return s; } -/** l2 input classifier main data structure */ +/** l2 input classifier main data structure. */ l2_input_classify_main_t l2_input_classify_main; vlib_node_registration_t l2_input_classify_node; @@ -106,19 +107,19 @@ static char *l2_input_classify_error_strings[] = { * @em Uses: * - <code>(l2_input_classify_runtime_t *) * rt->classify_table_index_by_sw_if_index</code> - * Head of the per-interface, perprotocol classifier table chain - * for a specific interface. ~0 => send pkts to the next - * feature in the L2 feature chain. + * - Head of the per-interface, per-protocol classifier table chain + * for a specific interface. + * - @c ~0 => send pkts to the next feature in the L2 feature chain. * - <code>vnet_buffer(b)->sw_if_index[VLIB_RX]</code> * - Indicates the @c sw_if_index value of the interface that the - * packet was received on. - * - <code>vnet_buffer (b0)->l2.feature_bitmap</code> + * packet was received on. + * - <code>vnet_buffer(b0)->l2.feature_bitmap</code> * - Used to steer packets across l2 features enabled on the interface * - <code>(vnet_classify_entry_t) e0->next_index</code> * - Used to steer traffic when the classifier hits on a session * - <code>(vnet_classify_entry_t) e0->advance</code> * - Signed quantity applied via <code>vlib_buffer_advance</code> - * when the classifier hits on a session + * when the classifier hits on a session * - <code>(vnet_classify_table_t) t0->miss_next_index</code> * - Used to steer traffic when the classifier misses * @@ -477,7 +478,7 @@ VLIB_REGISTER_NODE (l2_input_classify_node) = { VLIB_NODE_FUNCTION_MULTIARCH (l2_input_classify_node, l2_input_classify_node_fn); -/** l2 input classsifier feature initialization */ +/** l2 input classsifier feature initialization. */ clib_error_t * l2_input_classify_init (vlib_main_t * vm) { @@ -505,7 +506,7 @@ l2_input_classify_init (vlib_main_t * vm) VLIB_INIT_FUNCTION (l2_input_classify_init); -/** enable/disable l2 input classification on a specific interface */ +/** Enable/disable l2 input classification on a specific interface. */ void vnet_l2_input_classify_enable_disable (u32 sw_if_index, int enable_disable) { @@ -513,7 +514,7 @@ vnet_l2_input_classify_enable_disable (u32 sw_if_index, int enable_disable) (u32) enable_disable); } -/** @brief Set l2 per-protocol, per-interface input classification tables +/** @brief Set l2 per-protocol, per-interface input classification tables. * * @param sw_if_index interface handle * @param ip4_table_index ip4 classification table index, or ~0 diff --git a/vnet/vnet/l2/l2_learn.c b/vnet/vnet/l2/l2_learn.c index 30f5617f05e..96d4816e1e6 100644 --- a/vnet/vnet/l2/l2_learn.c +++ b/vnet/vnet/l2/l2_learn.c @@ -29,8 +29,9 @@ #include <vppinfra/error.h> #include <vppinfra/hash.h> -/* - * Ethernet bridge learning +/** + * @file + * Ethernet bridge learning. * * Populate the mac table with entries mapping the packet's source mac + bridge * domain ID to the input sw_if_index. @@ -102,7 +103,7 @@ typedef enum } l2learn_next_t; -/** Perform learning on one packet based on the mac table lookup result */ +/** Perform learning on one packet based on the mac table lookup result. */ static_always_inline void l2learn_process (vlib_node_runtime_t * node, @@ -462,7 +463,7 @@ VLIB_INIT_FUNCTION (l2learn_init); /** - * set subinterface learn enable/disable + * Set subinterface learn enable/disable. * The CLI format is: * set interface l2 learn <interface> [disable] */ diff --git a/vnet/vnet/l2/l2_output.c b/vnet/vnet/l2/l2_output.c index 8bc43744d9f..85678caf6b7 100644 --- a/vnet/vnet/l2/l2_output.c +++ b/vnet/vnet/l2/l2_output.c @@ -73,9 +73,10 @@ static char *l2output_error_strings[] = { }; /** - * Return 0 if split horizon check passes, otherwise return non-zero + * Check for split horizon violations. + * Return 0 if split horizon check passes, otherwise return non-zero. * Packets should not be transmitted out an interface with the same - * split-horizon group as the input interface, except if the shg is 0 + * split-horizon group as the input interface, except if the @c shg is 0 * in which case the check always passes. */ static_always_inline u32 @@ -592,7 +593,7 @@ output_node_mapping_send_rpc (u32 node_index, u32 sw_if_index) #endif -/** Create a mapping in the next node mapping table for the given sw_if_index */ +/** Create a mapping in the next node mapping table for the given sw_if_index. */ u32 l2output_create_output_node_mapping (vlib_main_t * vlib_main, vnet_main_t * vnet_main, u32 node_index, /* index of current node */ u32 * output_node_index_vec, @@ -660,7 +661,7 @@ l2output_intf_config (u32 sw_if_index) return vec_elt_at_index (mp->configs, sw_if_index); } -/** Enable (or disable) the feature in the bitmap for the given interface */ +/** Enable (or disable) the feature in the bitmap for the given interface. */ void l2output_intf_bitmap_enable (u32 sw_if_index, u32 feature_bitmap, u32 enable) { diff --git a/vnet/vnet/l2/l2_output_acl.c b/vnet/vnet/l2/l2_output_acl.c index 4597d42e945..94a4d66b48f 100644 --- a/vnet/vnet/l2/l2_output_acl.c +++ b/vnet/vnet/l2/l2_output_acl.c @@ -306,8 +306,8 @@ VLIB_NODE_FUNCTION_MULTIARCH (l2_outacl_node, l2_outacl_node_fn) VLIB_INIT_FUNCTION (l2_outacl_init); #if 0 -/** @todo maybe someone will add output ACL's in the future - * set subinterface outacl enable/disable +/** @todo maybe someone will add output ACL's in the future. + * Set subinterface outacl enable/disable. * The CLI format is: * set interface acl output <interface> [disable] */ diff --git a/vnet/vnet/l2/l2_output_classify.c b/vnet/vnet/l2/l2_output_classify.c index 1cb8b8507bf..c04df3c255b 100644 --- a/vnet/vnet/l2/l2_output_classify.c +++ b/vnet/vnet/l2/l2_output_classify.c @@ -12,18 +12,16 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -/* - * l2_classify.c - */ #include <vnet/l2/l2_classify.h> #include <vnet/api_errno.h> /** * @file - * @brief L2 input classifier + * @brief L2 input classifier. * - * See also .../vnet/vnet/classify/vnet_classify.[ch] + * @sa @ref vnet/vnet/classify/vnet_classify.c + * @sa @ref vnet/vnet/classify/vnet_classify.h */ typedef struct @@ -46,7 +44,7 @@ typedef struct l2_output_classify_main_t *l2cm; } l2_output_classify_runtime_t; -/** packet trace format function */ +/** Packet trace format function. */ static u8 * format_l2_output_classify_trace (u8 * s, va_list * args) { @@ -61,7 +59,7 @@ format_l2_output_classify_trace (u8 * s, va_list * args) return s; } -/** l2 output classifier main data structure */ +/** l2 output classifier main data structure. */ l2_output_classify_main_t l2_output_classify_main; vlib_node_registration_t l2_output_classify_node; @@ -477,7 +475,7 @@ VLIB_REGISTER_NODE (l2_output_classify_node) = { VLIB_NODE_FUNCTION_MULTIARCH (l2_output_classify_node, l2_output_classify_node_fn); -/** l2 output classsifier feature initialization */ +/** l2 output classsifier feature initialization. */ clib_error_t * l2_output_classify_init (vlib_main_t * vm) { @@ -507,7 +505,7 @@ l2_output_classify_init (vlib_main_t * vm) VLIB_INIT_FUNCTION (l2_output_classify_init); -/** enable/disable l2 input classification on a specific interface */ +/** Enable/disable l2 input classification on a specific interface. */ void vnet_l2_output_classify_enable_disable (u32 sw_if_index, int enable_disable) { @@ -516,15 +514,15 @@ vnet_l2_output_classify_enable_disable (u32 sw_if_index, int enable_disable) (u32) enable_disable); } -/** @brief Set l2 per-protocol, per-interface output classification tables +/** @brief Set l2 per-protocol, per-interface output classification tables. * - * @param sw_if_index interface handle - * @param ip4_table_index ip4 classification table index, or ~0 - * @param ip6_table_index ip6 classification table index, or ~0 + * @param sw_if_index interface handle + * @param ip4_table_index ip4 classification table index, or ~0 + * @param ip6_table_index ip6 classification table index, or ~0 * @param other_table_index non-ip4, non-ip6 classification table index, * or ~0 * @returns 0 on success, VNET_API_ERROR_NO_SUCH_TABLE, TABLE2, TABLE3 - * if the indicated (non-~0) table does not exist. + * if the indicated (non-~0) table does not exist. */ int diff --git a/vnet/vnet/l2/l2_vtr.c b/vnet/vnet/l2/l2_vtr.c index 6250074e303..3ec8b8a7d36 100644 --- a/vnet/vnet/l2/l2_vtr.c +++ b/vnet/vnet/l2/l2_vtr.c @@ -30,7 +30,7 @@ #include <vlib/cli.h> -/** Just a placeholder. Also ensures file is not eliminated by linker. */ +/** Just a placeholder; ensures file is not eliminated by linker. */ clib_error_t * l2_vtr_init (vlib_main_t * vm) { @@ -254,7 +254,7 @@ done: } /** - * Get vtag tag rewrite on the given interface. + * Get vtag tag rewrite on the given interface. * Return 1 if there is an error, 0 if ok */ u32 @@ -411,7 +411,7 @@ done: } /** - * set subinterface vtr enable/disable + * Set subinterface vtr enable/disable. * The CLI format is: * set interface l2 tag-rewrite <interface> [disable | pop 1 | pop 2 | push {dot1q|dot1ad} <tag> [<tag>]] * diff --git a/vnet/vnet/l2/l2_xcrw.c b/vnet/vnet/l2/l2_xcrw.c index 95219e6e9f0..344a8b96506 100644 --- a/vnet/vnet/l2/l2_xcrw.c +++ b/vnet/vnet/l2/l2_xcrw.c @@ -14,7 +14,8 @@ */ #include <vnet/l2/l2_xcrw.h> -/* +/** + * @file * General L2 / L3 cross-connect, used to set up * "L2 interface <--> your-favorite-tunnel-encap" tunnels. * diff --git a/vnet/vnet/unix/tuntap.c b/vnet/vnet/unix/tuntap.c index 83e7ec4f590..b3fbc7f32e7 100644 --- a/vnet/vnet/unix/tuntap.c +++ b/vnet/vnet/unix/tuntap.c @@ -786,9 +786,9 @@ tuntap_ip4_add_del_interface_address (ip4_main_t * im, } /** - * @brief workaround for a known #include bug - * #include <linux/ipv6.h> causes multiple definitions if - * netinet/in.h is also included. + * @brief workaround for a known include file bug. + * including @c <linux/ipv6.h> causes multiple definitions if + * @c <netinet/in.h is also included. */ struct in6_ifreq { struct in6_addr ifr6_addr; @@ -797,7 +797,7 @@ struct in6_ifreq { }; /** - * @brief Add or Del tun/tap interface address + * @brief Add or Del tun/tap interface address. * * Both the v6 interface address API and the way ifconfig * displays subinterfaces differ from their v4 couterparts. diff --git a/vppinfra/vppinfra/bihash_template.c b/vppinfra/vppinfra/bihash_template.c index a8d095c9758..2ad8293094c 100644 --- a/vppinfra/vppinfra/bihash_template.c +++ b/vppinfra/vppinfra/bihash_template.c @@ -13,7 +13,7 @@ * limitations under the License. */ -/** @if DOCUMENTATION_IS_IN_BIHASH_DOC_H */ +/** @cond DOCUMENTATION_IS_IN_BIHASH_DOC_H */ void BV (clib_bihash_init) (BVT (clib_bihash) * h, char *name, u32 nbuckets, uword memory_size) @@ -444,7 +444,7 @@ void BV (clib_bihash_foreach_key_value_pair) } } -/** @endif */ +/** @endcond */ /* * fd.io coding-style-patch-verification: ON diff --git a/vppinfra/vppinfra/bihash_template.h b/vppinfra/vppinfra/bihash_template.h index 07c3e7daec7..a8bb27ffb0e 100644 --- a/vppinfra/vppinfra/bihash_template.h +++ b/vppinfra/vppinfra/bihash_template.h @@ -14,7 +14,7 @@ * limitations under the License. */ -/** @if DOCUMENTATION_IS_IN_BIHASH_DOC_H */ +/** @cond DOCUMENTATION_IS_IN_BIHASH_DOC_H */ /* * Note: to instantiate the template multiple times in a single file, @@ -203,7 +203,7 @@ static inline int BV (clib_bihash_search_inline_2) #endif /* __included_bihash_template_h__ */ -/** @endif */ +/** @endcond */ /* * fd.io coding-style-patch-verification: ON |