From bfe1b7ca863ef6ba672391fd677b2ec7fca7791e Mon Sep 17 00:00:00 2001 From: Rey Tucker Date: Thu, 6 Dec 2018 19:00:45 -0500 Subject: [PATCH] host: bladeRF-cli: ADDING_COMMANDS: convert to markdown, freshen clean up formatting fix typos expand discussion of generate.bash --- .../bladeRF-cli/src/cmd/ADDING_COMMANDS.md | 135 ++++++++++++++++++ .../bladeRF-cli/src/cmd/ADDING_COMMANDS.txt | 121 ---------------- 2 files changed, 135 insertions(+), 121 deletions(-) create mode 100644 host/utilities/bladeRF-cli/src/cmd/ADDING_COMMANDS.md delete mode 100644 host/utilities/bladeRF-cli/src/cmd/ADDING_COMMANDS.txt diff --git a/host/utilities/bladeRF-cli/src/cmd/ADDING_COMMANDS.md b/host/utilities/bladeRF-cli/src/cmd/ADDING_COMMANDS.md new file mode 100644 index 00000000..314e9d93 --- /dev/null +++ b/host/utilities/bladeRF-cli/src/cmd/ADDING_COMMANDS.md @@ -0,0 +1,135 @@ +This file provides a brief summary of how to add a new command to the +`bladeRF-cli` program. + +## Creating a file for the command + +To add a new command, create a C file in this directory and add it to the list +of source files in `host/utilities/bladeRF-cli/CMakeLists.txt`. The entry point +of the command should have a prototype similar to the one shown below for a +*mycmd* command: + + int cmd_mycmd(struct cli_state *state, int argc, char **argv); + +The first parameter is a pointer to some CLI state information. The remaining +two parameters are similar to what one would expect for a `main()` function. + +The function shall `return 0` for success, or one of the `CLI_RET_*` values +defined in `common.h`. For all error values *except* `CLI_RET_INVPARAM` and +`CLI_RET_CMD_HANDLED`, the top-level command handling code will print an +appropriate error message; your command should not print anything. + +Use `CLI_RET_NARGS` for an incorrect number of arguments. Do not use the +`CLI_RET_INVPARAM` code in this case. + +However, if your command detects that is provided with an invalid parameter, it +should print an error message and return `CLI_RET_INVPARAM`. The rationale is +that only the command's implementation will "know" what is and is not valid, but +the other error codes are sufficiently generic. + +`CLI_RET_CMD_HANDLED` should be use for command-specific failures that have been +handled by the command (including printing the necessary output). If you find +that you're using this value, first consider whether the error situation is +generic enough to warrant adding a new value to the `CLI_RET_*` value +definitions in `common.h`. + +Error messages associated with `CLI_RET_INVPARAM` or `CLI_RET_CMD_HANDLED` shall +be printed using the `cli_err()` function, defined in `common.h`. Generally, +you'll want the prefix argument to `cli_err()` to be `argv[0]`. An acceptable +alternative for `CLI_RET_INVPARAM` is to use the argument name that was +incorrect as the prefix. + +Be sure to include a `\n` at the end of the message passed to `cli_err()` to +remain consistent with the preferred output format. This function will insert +the desired leading indentation; there is no need to manually prepend this to +the prefix. + +Another slightly special case is the handling of libbladeRF error codes. If a +libbladeRF function returns a non-zero error code, set `state->last_lib_error` +to the error code and return `CLI_RET_LIBBLADERF`. This will the top-level +command handling code to look up and print an appropriate error message via +`bladerf_strerror()`, instead of `cli_strerror()`. + +When printing informational output in your command, prepend and append newlines +to the beginning and end of your output, respectively. Output shall be indented +two spaces. Below is an example: + + bladeRF> mycmd arg1 arg2 + + Mycmd output line one. + Additional information on line two. + Sub-information 1 + Sub-information 2 + + bladeRF> mycmd badarg1 arg2 + + mycmd: badarg1 is invalid because XYZ... + + bladeRF> + + +## Adding the command to cmd.c + +When adding a command to `cmd.c`, please be sure to maintain the alphabetical +ordering of commands. This includes lists of declarations. + +First, add an appropriate `DECLARE_CMD()`. For the *mycmd* example above, this +would be: + + DECLARE_CMD(mycmd); + +Next, add the command name (and optional shortcuts/aliases) that will invoke +your command to list of `cmd_names_*` declarations. For example, to invoke the +*mycmd* command with `mycmd` and `m`: + + static const char *cmd_names_mycmd[] = { "mycmd", "m", NULL }; + +Next, add help text for your command in `doc/interactive-help.md`. For the +*mycmd* example, this might look like: + + mycmd + ----- + + Usage: `mycmd ` + + This is an example command that does such and such. + + Some more detailed examples and explanations go here. + + * `` - First argument + * `` - Second argument + +The `generate.bash` script can be used to regenerate the `cmd_help.*` artifacts. +Be sure to copy `cmd_help.h` to `cmd_help.h.in` and `cmd_help.man` to +`cmd_help.man.in`, then stage those files: + + cp cmd_help.h cmd_help.h.in + cp cmd_help.man cmd_help.man.in + git add cmd_help.h.in cmd_help.man.in interactive-help.md + +Finally, add an element to the `cmd_table[]` array. The fields here consist of: + +* The command names that invoke your command +* The function to execute +* A brief one-line description of the function to show in "help" output +* The command's detailed help text +* A flag to denote whether the command requires an open device handle +* A flag to denote whether the command requires the FPGA to be loaded + +The `requires_device` and `requires_fpga` flags should be set to `true` if some +or all of the operations provided by the command require the aforementioned +items. This allows the command-agnostic logic to print an appropriate error +message before even attempting to execute the command. The rationale for having +these flags is that it reduces duplicated device handle and FPGA state checks in +numerous commands. + +An example element might look like the following, if *mycmd* were to operate on +a device handle, but not require that the FPGA be loaded: + + { + FIELD_INIT(.names, cmd_names_mycmd), + FIELD_INIT(.exec, cmd_mycmd), + FIELD_INIT(.desc, "Perform such and such operatiions"), + FIELD_INIT(.help, CLI_CMD_HELPTEXT_mycmd), + FIELD_INIT(.requires_device, true), + FIELD_INIT(.requires_fpga, false), + }, diff --git a/host/utilities/bladeRF-cli/src/cmd/ADDING_COMMANDS.txt b/host/utilities/bladeRF-cli/src/cmd/ADDING_COMMANDS.txt deleted file mode 100644 index 1d07eb24..00000000 --- a/host/utilities/bladeRF-cli/src/cmd/ADDING_COMMANDS.txt +++ /dev/null @@ -1,121 +0,0 @@ -This file provides a brief summary of how to add a new command to the -bladeRF-cli program. - -= Creating a file for the command = - -To add a new command, create C file in this directory and add it to the list of -source files in the bladeRF-cli CMakeLists.txt. The entry point of the command -should have a prototype similar to the one shown below for an "mycmd" command: - - int cmd_mycmd(struct cli_state *state, int argc, char **argv); - -The first parameter is a pointer to some CLI state information. The remaining -two parameters are similar to what one would expect for a main() function. - -The function shall return 0 for success, or one of the CLI_RET_* values defined -in common.h. For all error values EXCEPT CLI_RET_INVPARAM and -CLI_RET_CMD_HANDLED, the top-level command handling code will print an -appropriate error message; your command should not print anything. - -Use CLI_RET_NARGS for an incorrect number of arguments. Do not use the -CLI_RET_INVPARAM code in this case. - -However, If your command detects that is provided with an invalid parameter, it -should print an error message and return CLI_RET_INVPARAM. The rationale is -that only the command's implementation will "know" what is and is not valid, -but the other error codes are sufficiently generic. - -CLI_RET_CMD_HANDLED should be use for command-specific failures that have been -handled by the command (including printing the necessary output). If you find -that you're using this value, first consider whether the error situation is -generic enough to warrant adding a new value to the CLI_RET_* value definitions -in common.h. - -Error messages associated with CLI_RET_INVPARAM or CLI_RET_CMD_HANDLED shall be -printed using the cli_err() function, defined in common.h. Generally, you'll -want the prefix argument to cli_err() to be argv[0]. An acceptable alternative -for CLI_RET_INVPARAM is to use the argument name that was incorrect as the -prefix. - -Be sure to include a "\n" at the end of the message passed to cli_err() to -remain consistent with the preferred output format. This function will insert -the desired leading indentation; there is no need to manually prepend this to -the prefix. - -Another slightly special case is the handling of libbladeRF error codes. If a -libbladeRF function returns a non-zero error code, set state->last_lib_error to -the error code and return CLI_RET_LIBBLADERF. This will the top-level command -handling code to look up and print an appropriate error message via -libbladerf_strerror(), instead of cli_strerror(). - -When printing informational output in your command, prepend and append newlines -to the beginning and end of your output, respectively. Output shall be indented -two spaces. Below is an example: - -bladeRF> mycmd arg1 arg2 - - Mycmd output line one. - Additional information on line two. - Sub-information 1 - Sub-information 2 - -bladeRF> mycmd badarg1 arg2 - - mycmd: badarg1 is invalid because XYZ... - -bladeRF> - - - -= Adding the command to cmd.c = - -When adding a command to cmd.c, please be sure to maintain the alphabetical -ordering of commands. This includes lists of declarations. - -First, add an appropriate DECLARE_CMD(). For the "mycmd" example above, this -would be: - - DECLARE_CMD(mycmd); - -Next, add the command name (and optional shortcuts/aliases) that will -invoke your command to list of cmd_names_* declarations. For example, -to invoke the mycmd command with "mycmd" and "m": - - static const char *cmd_names_mycmd[] = { "mycmd", "m", NULL }; - - -Next, add help text for your command in cmd_help.h.in. For the mycmd example, -this might look like: - - #define CLI_CMD_HELPTEXT_mycmd \ - "Usage: mycmd \n" - "\n" - "This is an example command that does such and such.\n" - "\n" - "Some more detailed examples and explanations go here.\n" - -Finally, added an element to the cmd_table[] array. The fields here consist of: - * The command names that invoke your command - * The function to execute - * A brief one-line description of the function to show in "help" output - * The command's detailed help text - * A flag to denote whether the command requires an open device handle - * A flag to denote whether the command requires the FPGA to be loaded - -The requires_device and requires_fpga flags should be set to true if some or -all of the operations provided by the command require the aforementioned items. -This allows the command-agnostic logic to print an appropriate error message -before even attempting to execute the command. The rationale for having these -flags is that it reduces duplicated device handle and FPGA state checks in -numerous commands. - -An example element might look like the following, if mycmd were to operate -on a device handle, but not require that the FPGA be loaded: - { - FIELD_INIT(.names, cmd_names_mycmd), - FIELD_INIT(.exec, cmd_mycmd), - FIELD_INIT(.desc, "Perform such and such operatiions"), - FIELD_INIT(.help, CLI_CMD_HELPTEXT_mycmd), - FIELD_INIT(.requires_device, true), - FIELD_INIT(.requires_fpga, false), - },