* 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.
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.
*/
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.
}
}
-/** \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.
*
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
}
}
-/** \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.
}
}
-/** \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)
{
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)
{
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)
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)
{
}
}
-/** \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)
{
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)
{
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)
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.
*
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.
*/
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,
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)
{
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
#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);
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);
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)
{
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)
{
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 { \
} \
} 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); \
(_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); \
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; \
_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);
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
} \
} 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 { \
})); \
} 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) \
({ \
_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); \
_pool_var(rv); \
})
+/** Iterate pool by index. */
#define pool_foreach_index(i,v,body) \
for ((i) = 0; (i) < vec_len (v); (i)++) \
{ \
Code Review / vpp.git / commitdiff