diff options
| -rw-r--r-- | vlib/vlib/unix/cli.c | 34 | ||||
| -rw-r--r-- | vnet/vnet/ip/ip4_forward.c | 6 | ||||
| -rw-r--r-- | vppinfra/vppinfra/pool.h | 127 |
3 files changed, 91 insertions, 76 deletions
diff --git a/vlib/vlib/unix/cli.c b/vlib/vlib/unix/cli.c index 58aa6dfc6bf..e36b80ad990 100644 --- a/vlib/vlib/unix/cli.c +++ b/vlib/vlib/unix/cli.c @@ -37,7 +37,7 @@ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ /** - * @file vlib/vlib/unix/cli.c + * @file * @brief Unix stdin/socket command line interface. * Provides a command line interface so humans can interact with VPP. * This is predominantly a debugging and testing mechanism. @@ -269,7 +269,7 @@ typedef enum UNIX_CLI_PARSE_ACTION_NOMATCH } unix_cli_parse_action_t; -/** \brief Mapping of input buffer strings to action values. +/** @brief Mapping of input buffer strings to action values. * @note This won't work as a hash since we need to be able to do * partial matches on the string. */ @@ -428,7 +428,7 @@ typedef struct static unix_cli_main_t unix_cli_main; /** - * \brief Search for a byte sequence in the action list. + * @brief Search for a byte sequence in the action list. * * Searches the @ref unix_cli_parse_actions_t list in @a a for a match with * the bytes in @a input of maximum length @a ilen bytes. @@ -518,7 +518,7 @@ unix_cli_del_pending_output (unix_file_t * uf, } } -/** \brief A bit like strchr with a buffer length limit. +/** @brief A bit like strchr with a buffer length limit. * Search a buffer for the first instance of a character up to the limit of * the buffer length. If found then return the position of that character. * @@ -544,7 +544,7 @@ unix_vlib_findchr (u8 chr, u8 * str, word len) return len; } -/** \brief Send a buffer to the CLI stream if possible, enqueue it otherwise. +/** @brief Send a buffer to the CLI stream if possible, enqueue it otherwise. * Attempts to write given buffer to the file descriptor of the given * Unix CLI session. If that session already has data in the output buffer * or if the write attempt tells us to try again later then the given buffer @@ -582,7 +582,7 @@ unix_vlib_cli_output_raw (unix_cli_file_t * cf, } } -/** \brief Process a buffer for CRLF handling before outputting it to the CLI. +/** @brief Process a buffer for CRLF handling before outputting it to the CLI. * * @param cf Unix CLI session of the desired stream to write to. * @param uf The Unix file structure of the desired stream to write to. @@ -625,7 +625,7 @@ unix_vlib_cli_output_cooked (unix_cli_file_t * cf, } } -/** \brief Output the CLI prompt */ +/** @brief Output the CLI prompt */ static void unix_cli_cli_prompt (unix_cli_file_t * cf, unix_file_t * uf) { @@ -634,7 +634,7 @@ unix_cli_cli_prompt (unix_cli_file_t * cf, unix_file_t * uf) unix_vlib_cli_output_raw (cf, uf, cm->cli_prompt, vec_len (cm->cli_prompt)); } -/** \brief Output a pager prompt and show number of buffered lines */ +/** @brief Output a pager prompt and show number of buffered lines */ static void unix_cli_pager_prompt (unix_cli_file_t * cf, unix_file_t * uf) { @@ -657,7 +657,7 @@ unix_cli_pager_prompt (unix_cli_file_t * cf, unix_file_t * uf) vec_free (prompt); } -/** \brief Output a pager "skipping" message */ +/** @brief Output a pager "skipping" message */ static void unix_cli_pager_message (unix_cli_file_t * cf, unix_file_t * uf, char *message, char *postfix) @@ -673,7 +673,7 @@ unix_cli_pager_message (unix_cli_file_t * cf, unix_file_t * uf, vec_free (prompt); } -/** \brief Erase the printed pager prompt */ +/** @brief Erase the printed pager prompt */ static void unix_cli_pager_prompt_erase (unix_cli_file_t * cf, unix_file_t * uf) { @@ -695,7 +695,7 @@ unix_cli_pager_prompt_erase (unix_cli_file_t * cf, unix_file_t * uf) } } -/** \brief Uses an ANSI escape sequence to move the cursor */ +/** @brief Uses an ANSI escape sequence to move the cursor */ static void unix_cli_ansi_cursor (unix_cli_file_t * cf, unix_file_t * uf, u16 x, u16 y) { @@ -1012,7 +1012,7 @@ unix_cli_terminal_type (u8 * term, uword len) return 0; } -/** \brief Emit initial welcome banner and prompt on a connection. */ +/** @brief Emit initial welcome banner and prompt on a connection. */ static void unix_cli_file_welcome (unix_cli_main_t * cm, unix_cli_file_t * cf) { @@ -1054,7 +1054,7 @@ unix_cli_file_welcome (unix_cli_main_t * cm, unix_cli_file_t * cf) cf->started = 1; } -/** \brief A failsafe triggered on a timer to ensure we send the prompt +/** @brief A failsafe triggered on a timer to ensure we send the prompt * to telnet sessions that fail to negotiate the terminal type. */ static void unix_cli_file_welcome_timer (any arg, f64 delay) @@ -1073,7 +1073,7 @@ unix_cli_file_welcome_timer (any arg, f64 delay) unix_cli_file_welcome (cm, cf); } -/** \brief A mostly no-op Telnet state machine. +/** @brief A mostly no-op Telnet state machine. * Process Telnet command bytes in a way that ensures we're mostly * transparent to the Telnet protocol. That is, it's mostly a no-op. * @@ -1201,7 +1201,7 @@ unix_cli_process_telnet (unix_main_t * um, return consume; } -/** \brief Process actionable input. +/** @brief Process actionable input. * Based on the \c action process the input; this typically involves * searching the command history or editing the current command line. */ @@ -1883,7 +1883,7 @@ unix_cli_line_process_one (unix_cli_main_t * cm, return 1; } -/** \brief Process input bytes on a stream to provide line editing and +/** @brief Process input bytes on a stream to provide line editing and * command history in the CLI. */ static int unix_cli_line_edit (unix_cli_main_t * cm, @@ -1961,7 +1961,7 @@ unix_cli_line_edit (unix_cli_main_t * cm, return 1; } -/** \brief Process input to a CLI session. */ +/** @brief Process input to a CLI session. */ static void unix_cli_process_input (unix_cli_main_t * cm, uword cli_file_index) { diff --git a/vnet/vnet/ip/ip4_forward.c b/vnet/vnet/ip/ip4_forward.c index 2ccdd37cbc2..6b7fa9b4d05 100644 --- a/vnet/vnet/ip/ip4_forward.c +++ b/vnet/vnet/ip/ip4_forward.c @@ -1039,7 +1039,7 @@ ip4_lookup_inline (vlib_main_t * vm, return frame->n_vectors; } -/** \brief IPv4 lookup node. +/** @brief IPv4 lookup node. @node ip4-lookup This is the main IPv4 lookup dispatch node. @@ -2960,7 +2960,7 @@ ip4_rewrite_inline (vlib_main_t * vm, } -/** \brief IPv4 transit rewrite node. +/** @brief IPv4 transit rewrite node. @node ip4-rewrite-transit This is the IPv4 transit-rewrite node: decrement TTL, fix the ipv4 @@ -3000,7 +3000,7 @@ ip4_rewrite_transit (vlib_main_t * vm, /* rewrite_for_locally_received_packets */ 0); } -/** \brief IPv4 local rewrite node. +/** @brief IPv4 local rewrite node. @node ip4-rewrite-local This is the IPv4 local rewrite node. Fetch the ip adjacency, check diff --git a/vppinfra/vppinfra/pool.h b/vppinfra/vppinfra/pool.h index c6235e648d2..186a973107f 100644 --- a/vppinfra/vppinfra/pool.h +++ b/vppinfra/vppinfra/pool.h @@ -34,6 +34,12 @@ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ +/** @file + * @brief Fixed length block allocator. + Pools are built from clib vectors and bitmaps. Use pools when + repeatedly allocating and freeing fixed-size data. Pools are + fast, and avoid memory fragmentation. + */ #ifndef included_pool_h #define included_pool_h @@ -42,27 +48,24 @@ #include <vppinfra/error.h> #include <vppinfra/mheap.h> -/* Pools are built from clib vectors and bitmaps. Use pools when - repeatedly allocating and freeing fixed-size data. Pools are - fast, and avoid memory fragmentation. */ typedef struct { - /* Bitmap of indices of free objects. */ + /** Bitmap of indices of free objects. */ uword * free_bitmap; - /* Vector of free indices. One element for each set bit in bitmap. */ + /** Vector of free indices. One element for each set bit in bitmap. */ u32 * free_indices; } pool_header_t; -/* Align pool header so that pointers are naturally aligned. */ +/** Align pool header so that pointers are naturally aligned. */ #define pool_aligned_header_bytes \ vec_aligned_header_bytes (sizeof (pool_header_t), sizeof (void *)) -/* Get pool header from user pool pointer */ +/** Get pool header from user pool pointer */ always_inline pool_header_t * pool_header (void * v) { return vec_aligned_header (v, sizeof (pool_header_t), sizeof (void *)); } -/* Validate a pool */ +/** Validate a pool */ always_inline void pool_validate (void * v) { pool_header_t * p = pool_header (v); @@ -93,7 +96,9 @@ do { \ pool_header_validate_index ((v), __pool_validate_index); \ } while (0) -/* Number of active elements in a pool */ +/** Number of active elements in a pool. + * @return Number of active elements in a pool + */ always_inline uword pool_elts (void * v) { uword ret = vec_len (v); @@ -102,18 +107,19 @@ always_inline uword pool_elts (void * v) return ret; } -/* Number of elements in pool vector +/** Number of elements in pool vector. - Note: you probably want to call pool_elts() instead + @note You probably want to call pool_elts() instead. */ #define pool_len(p) vec_len(p) -/* Number of elements in pool vector (usable as an lvalue) - Note: you probably don't want to use this macro +/** Number of elements in pool vector (usable as an lvalue) + + @note You probably don't want to use this macro. */ #define _pool_len(p) _vec_len(p) -/*Memory usage of pool header */ +/** Memory usage of pool header. */ always_inline uword pool_header_bytes (void * v) { @@ -125,13 +131,13 @@ pool_header_bytes (void * v) return vec_bytes (p->free_bitmap) + vec_bytes (p->free_indices); } -/*Memory usage of pool */ +/** Memory usage of pool. */ #define pool_bytes(P) (vec_bytes (P) + pool_header_bytes (P)) -/*Local variable naming macro. */ +/** Local variable naming macro. */ #define _pool_var(v) _pool_##v -/*Queries whether pool has at least N_FREE free elements. */ +/** Queries whether pool has at least N_FREE free elements. */ always_inline uword pool_free_elts (void * v) { @@ -148,9 +154,9 @@ pool_free_elts (void * v) return n_free; } -/* Allocate an object E from a pool P (general version) +/** Allocate an object E from a pool P (general version). - First search free list. If nothing is free extend vector of objects + First search free list. If nothing is free extend vector of objects. */ #define pool_get_aligned(P,E,A) \ do { \ @@ -182,10 +188,10 @@ do { \ } \ } while (0) -/* Allocate an object E from a pool P (unspecified alignment) */ +/** Allocate an object E from a pool P (unspecified alignment). */ #define pool_get(P,E) pool_get_aligned(P,E,0) -/* Use free bitmap to query whether given element is free */ +/** Use free bitmap to query whether given element is free. */ #define pool_is_free(P,E) \ ({ \ pool_header_t * _pool_var (p) = pool_header (P); \ @@ -193,10 +199,10 @@ do { \ (_pool_var (i) < vec_len (P)) ? clib_bitmap_get (_pool_var (p)->free_bitmap, _pool_i) : 1; \ }) -/* Use free bitmap to query whether given index is free */ +/** Use free bitmap to query whether given index is free */ #define pool_is_free_index(P,I) pool_is_free((P),(P)+(I)) -/* Free an object E in pool P */ +/** Free an object E in pool P. */ #define pool_put(P,E) \ do { \ pool_header_t * _pool_var (p) = pool_header (P); \ @@ -210,14 +216,14 @@ do { \ vec_add1 (_pool_var (p)->free_indices, _pool_var (l)); \ } while (0) -/* Free pool element with given index. */ +/** Free pool element with given index. */ #define pool_put_index(p,i) \ do { \ typeof (p) _e = (p) + (i); \ pool_put (p, _e); \ } while (0) -/* Allocate N more free elements to pool (general version) */ +/** Allocate N more free elements to pool (general version). */ #define pool_alloc_aligned(P,N,A) \ do { \ pool_header_t * _p; \ @@ -229,10 +235,10 @@ do { \ _vec_len (_p->free_indices) -= (N); \ } while (0) -/* Allocate N more free elements to pool (unspecified alignment) */ +/** Allocate N more free elements to pool (unspecified alignment). */ #define pool_alloc(P,N) pool_alloc_aligned(P,N,0) -/* low-level free pool operator (do not call directly) */ +/** Low-level free pool operator (do not call directly). */ always_inline void * _pool_free (void * v) { pool_header_t * p = pool_header (v); @@ -244,10 +250,10 @@ always_inline void * _pool_free (void * v) return 0; } -/* Free a pool. */ +/** Free a pool. */ #define pool_free(p) (p) = _pool_free(p) -/* Optimized iteration through pool +/** Optimized iteration through pool. @param LO pointer to first element in chunk @param HI pointer to last element in chunk @@ -296,34 +302,39 @@ do { \ } \ } while (0) -/* Iterate through pool +/** Iterate through pool. - @param VAR variable of same type as pool vector - @param POOL pool to iterate across - @param BODY operation to perform. See the example below. + @param VAR A variable of same type as pool vector to be used as an + iterator. + @param POOL The pool to iterate across. + @param BODY The operation to perform, typically a code block. See + the example below. - call BODY with each active pool element. + This macro will call @c BODY with each active pool element. - Example: - proc_t *procs; // a pool of processes <br> - proc_t *proc; // pointer to one process <br> + It is a bad idea to allocate or free pool element from within + @c pool_foreach. Build a vector of indices and dispose of them later. - pool_foreach (proc, procs, ({ - <br> - if (proc->state != PROC_STATE_RUNNING)<br> - continue; - <br> - <i>check a running proc in some way</i><br> - })); - It is a bad idea to allocate or free pool element from within - pool_foreach. Build a vector of indices and dispose of them later. + @par Example + @code{.c} + proc_t *procs; // a pool of processes. + proc_t *proc; // pointer to one process; used as the iterator. - Because pool_foreach is a macro, syntax errors can be difficult to - find inside BODY, let alone actual code bugs. One can temporarily - split a complex pool_foreach into a trivial pool_foreach which - builds a vector of active indices, and a vec_foreach() (or plain - for-loop) to walk the active index vector. + pool_foreach (proc, procs, ({ + if (proc->state != PROC_STATE_RUNNING) + continue; + + // check a running proc in some way + ... + })); + @endcode + + @warning Because @c pool_foreach is a macro, syntax errors can be + difficult to find inside @c BODY, let alone actual code bugs. One + can temporarily split a complex @c pool_foreach into a trivial + @c pool_foreach which builds a vector of active indices, and a + vec_foreach() (or plain for-loop) to walk the active index vector. */ #define pool_foreach(VAR,POOL,BODY) \ do { \ @@ -337,11 +348,14 @@ do { \ })); \ } while (0) -/* Returns pointer to element at given index +/** Returns pointer to element at given index. - ASSERTs that the supplied index is valid. Even though - one can write correct code of the form "p = pool_base + index", - use of pool_elt_at_index is strongly suggested. + ASSERTs that the supplied index is valid. + Even though one can write correct code of the form + @code + p = pool_base + index; + @endcode + use of @c pool_elt_at_index is strongly suggested. */ #define pool_elt_at_index(p,i) \ ({ \ @@ -350,7 +364,7 @@ do { \ _e; \ }) -/* Return next occupied pool index after i, useful for safe iteration */ +/** Return next occupied pool index after @c i, useful for safe iteration. */ #define pool_next_index(P,I) \ ({ \ pool_header_t * _pool_var (p) = pool_header (P); \ @@ -363,6 +377,7 @@ do { \ _pool_var(rv); \ }) +/** Iterate pool by index. */ #define pool_foreach_index(i,v,body) \ for ((i) = 0; (i) < vec_len (v); (i)++) \ { \ |