- Fix issue in Doxy dependency check when nothing needs to be installed.
'set -e' and plain '[]' logic don't mix well.
- Fix Makefile snafu when building Doxy output for a single file.
- Include only one of vnet/vnet/buffer.c/dpdk_buffer.c in docs depending on
DPDKness. This could do with some improvement in future, eg to properly
align the pre-doxy steps with what Doxy does.
- Fix rendering of 'inline' tag in Doxygen by having it interpret
always_inline as "inline static".
- Bunch of duplicate CLI command structure names that confused docs and may
one day have caused debugging issues.
- Several other Doxygen syntax issues fixed, like documenting non-existant
parameters (usually just the wrong parameter name, typos, etc)
Change-Id: Ia8cca545e5de9f8750602bffa3c4548acc8971aa
Signed-off-by: Chris Luke <chrisy@flirble.org>
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)
-DOXY_INCLUDE_PATH += $(shell set -e; cpp -v </dev/null 2>&1 | grep -A 1000 '\#include' | awk '/^ /{print $$1}')
+
+# 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
for i in $(DOC_DEB_DEPENDS); do \
dpkg-query --show $$i >/dev/null 2>&1 || inst="$$inst $$i"; \
done; \
- [ "$$inst" ] && sudo apt-get $(CONFIRM) $(FORCE) install $$inst
+ 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
$(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 | sed -e "s/^/\$$(SIPHON_FILES): /" >> $@; \
+ \( -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
$(SIPHON_FILES): $(DOXY_DIR)/siphon_generate.py $(BR)/.doxygen-bootstrap.ok
@rm -rf "$(SIPHON_INPUT)" "$(SIPHON_OUTPUT)"
@mkdir -p "$(SIPHON_INPUT)" "$(SIPHON_OUTPUT)"
- set -e; for input in $(DOXY_INPUT); do \
+ @touch $(SIPHON_INPUT)/files
+ for input in $(DOXY_INPUT); do \
cd "$(WS_ROOT)"; \
find "$$input" -type f \
- \( -name '*.[ch]' -or -name '*.dox' \) \
- -print >> $(SIPHON_INPUT)/files; \
+ \( -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)" \
# 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
__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
# Collated output for each siphon
output = {}
+# Build a list of known siphons
+known_siphons = []
+for item in siphon_patterns:
+ siphon = item[1]
+ if siphon not in known_siphons:
+ known_siphons.append(siphon)
+
+# Setup information for siphons we know about
+for siphon in known_siphons:
+ output[siphon] = {
+ "file": "%s/%s.siphon" % (args.output, siphon),
+ "global": {},
+ "items": [],
+ }
+
# Pre-process file names in case they indicate a file with
# a list of files
files = []
if close_siphon is not None:
# Write the siphoned contents to the right place
siphon_name = close_siphon[0]
- if siphon_name not in output:
- output[siphon_name] = {
- "global": {},
- "items": [],
- "file": "%s/%s.siphon" % (args.output, close_siphon[0])
- }
# Copy directives for the file
details = {}
* WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
+/**
+ * @cond (!DPDK)
+ * @file
+ *
+ * Allocate/free network buffers.
+ */
+
#include <vlib/vlib.h>
uword
};
/* *INDENT-ON* */
+/** @endcond */
/*
* fd.io coding-style-patch-verification: ON
*
/** \brief Translate buffer pointer into buffer index
@param vm - (vlib_main_t *) vlib main data structure pointer
- @param b - (void *) buffer pointer
+ @param p - (void *) buffer pointer
@return - (u32) buffer index
*/
always_inline u32
/** \brief Copy buffer contents to memory
@param vm - (vlib_main_t *) vlib main data structure pointer
- @param bi - (u32) buffer index
+ @param buffer_index - (u32) buffer index
@param contents - (u8 *) memory, <strong>must be large enough</strong>
@return - (uword) length of buffer chain
*/
} vlib_counter_t;
/** Add two combined counters, results in the first counter
- @param [in/out] a - (vlib_counter_t *) dst counter
+ @param [in,out] a - (vlib_counter_t *) dst counter
@param b - (vlib_counter_t *) src counter
*/
}
/** Subtract combined counters, results in the first counter
- @param [in/out] a - (vlib_counter_t *) dst counter
+ @param [in,out] a - (vlib_counter_t *) dst counter
@param b - (vlib_counter_t *) src counter
*/
always_inline void
* WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
+/**
+ * @cond DPDK
+ * @file
+ *
+ * Allocate/free network buffers with DPDK.
+ */
+
#include <rte_config.h>
#include <rte_common.h>
VLIB_INIT_FUNCTION (buffer_state_validation_init);
#endif
+/** @endcond */
/*
* fd.io coding-style-patch-verification: ON
*
Here's an example:
- <pre>
- #define EXAMPLE_POLL_PERIOD 10.0
+ <code><pre>
+ \#define EXAMPLE_POLL_PERIOD 10.0
static uword
example_process (vlib_main_t * vm, vlib_node_runtime_t * rt,
.type = VLIB_NODE_TYPE_PROCESS,
.name = "example-process",
};
- </pre>
+ </pre></code>
In this example, the VLIB process node waits for an event to
occur, or for 10 seconds to elapse. The code demuxes on the event
return 0;
}
-VLIB_CLI_COMMAND (set_input_acl_command, static) = {
+VLIB_CLI_COMMAND (set_policer_classify_command, static) = {
.path = "set policer classify",
.short_help =
"set policer classify interface <int> [ip4-table <index>]\n"
b->current_length </code> and dispatch directly to
ip4-input-no-checksum, or ip6-input. Trace the packet if required.
- @param vm vlib_main_t corresponding to the current thread
+ @param vm vlib_main_t corresponding to the current thread
@param node vlib_node_runtime_t
- @param frame vlib_frame_t input-node, not used.
+ @param f vlib_frame_t input-node, not used.
@par Graph mechanics: buffer metadata, next index usage
return error;
}
-VLIB_CLI_COMMAND (set_interface_ip_table_command, static) = {
+VLIB_CLI_COMMAND (set_interface_ip6_table_command, static) = {
.path = "set interface ip6 table",
.function = add_del_ip6_interface_table,
.short_help = "set interface ip6 table <intfc> <table-id>"
-VLIB_CLI_COMMAND (show_ip_local, static) = {
+VLIB_CLI_COMMAND (show_ip6_local, static) = {
.path = "show ip6 local",
.function = show_ip6_local_command_fn,
.short_help = "Show ip6 local protocol table",
feature subgraph arc, which needs to run before @c ip4-lookup. In
either base code or a plugin,
<CODE><PRE>
- #include <vnet/ip/ip_feature_registration.h>
+ \#include <vnet/ip/ip_feature_registration.h>
</PRE></CODE>
and add the new feature as shown:
@c my-ip4-unicast-feature on an interface:
<CODE><PRE>
- ip4_main_t *im = &ip4_main;
+ ip4_main_t *im = \&ip4_main;
ip_lookup_main_t *lm = &im->lookup_main;
ip_config_main_t *rx_cm =
&lm->feature_config_mains[VNET_IP_RX_UNICAST_FEAT];
*
* This node remove GRE header.
*
- * @param vm vlib_main_t corresponding to the current thread.
- * @param node vlib_node_runtime_t data for this node.
- * @param frame vlib_frame_t whose contents should be dispatched.
+ * @param vm vlib_main_t corresponding to the current thread.
+ * @param node vlib_node_runtime_t data for this node.
+ * @param from_frame vlib_frame_t whose contents should be dispatched.
*
* @par Graph mechanics: buffer metadata, next index usage
*
/**
* @file
* @brief PCAP function.
- * Usage
*
- * #include <vnet/unix/pcap.h>
+ * Usage:
+ *
+ * <code><pre>
+ * \#include <vnet/unix/pcap.h>
*
* static pcap_main_t pcap = {
* .file_name = "/tmp/ip4",
* .n_packets_to_capture = 2,
* .packet_type = PCAP_PACKET_TYPE_ip,
* };
+ * </pre></code>
*
* To add a buffer:
*
- * pcap_add_buffer (&pcap, vm, pi0, 128);
+ * <code><pre>pcap_add_buffer (&pcap, vm, pi0, 128);</pre></code>
*
- * File will be written after n_packets_to_capture or call to pcap_write (&pcap).
+ * File will be written after @c n_packets_to_capture or call to pcap_write (&pcap).
*
*/
/**
* @brief Connect a TAP interface
*
- * @param *vm - vlib_main_t
- * @param *intfc_name - u8
- * @param *hwaddr_arg - u8
- * @param *sw_if_index - u32
+ * @param vm - vlib_main_t
+ * @param intfc_name - u8
+ * @param hwaddr_arg - u8
+ * @param sw_if_indexp - u32
*
* @return rc - int
*
* @param *vm
* @param *node
* @param *from_frame
- * @param ip_ip4
+ * @param is_ip4
*
* @return from_frame->n_vectors
*
/** Format a clib_bihash_kv_8_8_t instance
@param s - u8 * vector under construction
- @param v (vararg) - the (key,value) pair to format
+ @param args (vararg) - the (key,value) pair to format
@return s - the u8 * vector under construction
*/
static inline u8 *
/** Add or delete a (key,value) pair from a bi-hash table
@param h - the bi-hash table to search
- @param add_kv - the (key,value) pair to add
+ @param add_v - the (key,value) pair to add
@param is_add - add=1, delete=0
@returns 0 on success, < 0 on error
@note This function will replace an existing (key,value) pair if the
}
/** Duplicate a bitmap
- @param ai - pointer to a bitmap
+ @param v - pointer to a bitmap
@returns a duplicate of the bitmap
*/
#define clib_bitmap_dup(v) vec_dup(v)
/** Sets the ith bit of a bitmap to new_value
Removes trailing zeros from the bitmap
- @param a - pointer to the bitmap
+ @param ai - pointer to the bitmap
@param i - the bit position to interrogate
- @param new_value - new value for the bit
+ @param value - new value for the bit
@returns the old value of the bit
*/
always_inline uword *
/** Return a random bitmap of the requested length
@param ai - pointer to the destination bitmap
@param n_bits - number of bits to allocate
- @param [in/out] seed - pointer to the random number seed
+ @param [in,out] seed - pointer to the random number seed
@returns a reasonably random bitmap based. See random.h.
*/
always_inline uword *
Code Review / vpp.git / commitdiff