From 90f52bf990791ea73479ffc50fc1eb3450de443a Mon Sep 17 00:00:00 2001 From: Chris Luke Date: Mon, 12 Sep 2016 08:55:13 -0400 Subject: Refactor pre-Doxy siphon scripts; VPP-396 - Modularize the code to make the Siphon process easier to maintain. - Move much of the output rendering into Jinja2 templates. - Add syscfg siphon type for startup config documentation. - Add sample syscfg documentation. - Add clicfg and syscfg preamble docs, adapted from their wiki pages. - Fix sorting of CLI items across multiple directories. Change-Id: Ib8288fe005adfea68ceed75a38ff8eba25d3cc79 Signed-off-by: Chris Luke --- vlib/vlib/unix/cj.c | 35 ++++++++++++++++++++++++++++++++- vlib/vlib/unix/cli.c | 6 +++++- vlib/vlib/unix/dir.dox | 3 ++- vlib/vlib/unix/main.c | 53 ++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 94 insertions(+), 3 deletions(-) (limited to 'vlib') diff --git a/vlib/vlib/unix/cj.c b/vlib/vlib/unix/cj.c index 553b450ffaa..33ba163abca 100644 --- a/vlib/vlib/unix/cj.c +++ b/vlib/vlib/unix/cj.c @@ -17,6 +17,16 @@ *------------------------------------------------------------------ */ +/** + * @file + * Circular joournal diagnostic mechanism. + * + * The @c cj thread-safe circular log buffer scheme is occasionally useful + * when chasing bugs. Calls to it should not be checked in. + */ +/*? %%clicmd:group_label Circular Journal %% ?*/ +/*? %%syscfg:group_label Circular Journal %% ?*/ + #include #include @@ -94,6 +104,18 @@ cj_config (vlib_main_t * vm, unformat_input_t * input) return 0; } +/*? + * Configure the circular journal diagnostic mechanism. This is only useful + * if you, the deveoper, have written code to make use of the circular + * journal. + * + * @cfgcmd{records, <number>} + * Configure the number of records to allocate for the circular journal. + * + * @cfgcmd{on} + * Enable the collection of records in the circular journal at the + * earliest opportunity. +?*/ VLIB_CONFIG_FUNCTION (cj_config, "cj"); void @@ -220,10 +242,21 @@ cj_command_fn (vlib_main_t * vm, return 0; } +/*? + * Enable, disable the collection of diagnostic data into a + * circular journal or dump the circular journal diagnostic data. + * This is only useful if you, the deveoper, have written code to make + * use of the circular journal. + * + * When dumping the data it is formatted and sent to @c stderr of the + * VPP process; when running VPP in unix interactive mode + * this is typically the same place as the Debug CLI. +?*/ + /* *INDENT-OFF* */ VLIB_CLI_COMMAND (cj_command,static) = { .path = "cj", - .short_help = "cj", + .short_help = "cj ", .function = cj_command_fn, }; /* *INDENT-ON* */ diff --git a/vlib/vlib/unix/cli.c b/vlib/vlib/unix/cli.c index bf09ee0cce2..69fca6ec7bc 100644 --- a/vlib/vlib/unix/cli.c +++ b/vlib/vlib/unix/cli.c @@ -42,7 +42,8 @@ * Provides a command line interface so humans can interact with VPP. * This is predominantly a debugging and testing mechanism. */ -/*? %%clicmd:group_label Debug CLI %% ?*/ +/*? %%clicmd:group_label Command line session %% ?*/ +/*? %%syscfg:group_label Command line session %% ?*/ #include #include @@ -2504,6 +2505,9 @@ unix_cli_config (vlib_main_t * vm, unformat_input_t * input) return 0; } +/*? + * This module has no configurable parameters. +?*/ VLIB_CONFIG_FUNCTION (unix_cli_config, "unix-cli"); /** Called when VPP is shutting down, this restores the system diff --git a/vlib/vlib/unix/dir.dox b/vlib/vlib/unix/dir.dox index cdded0f19d3..1380fa56b37 100644 --- a/vlib/vlib/unix/dir.dox +++ b/vlib/vlib/unix/dir.dox @@ -23,5 +23,6 @@ VLIB application library Unix interface layer. */ -/*? %%clicmd:group_label VLIB Unix stuff%% ?*/ +/*? %%clicmd:group_label Unix Interface %% ?*/ +/*? %%syscfg:group_label Unix Interface %% ?*/ diff --git a/vlib/vlib/unix/main.c b/vlib/vlib/unix/main.c index 3087c283d9e..562778e0e5d 100644 --- a/vlib/vlib/unix/main.c +++ b/vlib/vlib/unix/main.c @@ -407,6 +407,59 @@ unix_config (vlib_main_t * vm, unformat_input_t * input) } /* unix { ... } configuration. */ +/*? + * + * @cfgcmd{interactive} + * Attach CLI to stdin/out and provide a debugging command line interface. + * Implies @c nodaemon. + * + * @cfgcmd{nodaemon} + * Do not fork or background the VPP process. Typically used when invoking + * VPP applications from a process monitor. + * + * @cfgcmd{exec, <filename>} + * @par startup-config <filename> + * Read startup operational configuration from @c filename. + * The contents of the file will be performed as though entered at the CLI. + * The two keywords are aliases for the same function; if both are specified, + * only the last will have an effect. + * + * @cfgcmd{log, <filename>} + * Logs the startup configuration and all subsequent CLI commands in + * @c filename. + * Very useful in situations where folks don't remember or can't be bothered + * to include CLI commands in bug reports. + * + * @cfgcmd{full-coredump} + * Ask the Linux kernel to dump all memory-mapped address regions, instead + * of just text+data+bss. + * + * @cfgcmd{cli-listen, <address:port>} + * Bind the CLI to listen at the address and port given. @clocalhost + * on TCP port @c 5002, given as cli-listen localhost:5002, + * is typical. + * + * @cfgcmd{cli-line-mode} + * Disable character-by-character I/O on stdin. Useful when combined with, + * for example, emacs M-x gud-gdb. + * + * @cfgcmd{cli-prompt, <string>} + * Configure the CLI prompt to be @c string. + * + * @cfgcmd{cli-history-limit, <nn>} + * Limit commmand history to @c nn lines. A value of @c 0 + * disables command history. Default value: @c 50 + * + * @cfgcmd{cli-no-banner} + * Disable the login banner on stdin and Telnet connections. + * + * @cfgcmd{cli-no-pager} + * Disable the output pager. + * + * @cfgcmd{cli-pager-buffer-limit, <nn>} + * Limit pager buffer to @c nn lines of output. + * A value of @c 0 disables the pager. Default value: @c 100000 +?*/ VLIB_CONFIG_FUNCTION (unix_config, "unix"); static clib_error_t * -- cgit 1.2.3-korg