Shell

The shell runs above the console and provides two functionalities:

The shell uses the OS default event queue for shell events and runs in the context of the main task. An application can, optionally, specify a dedicated event queue for the shell to use.

The sys/shell package implements the shell. To use the shell you must:

  • Include the sys/shell package.

  • Set the SHELL_TASK syscfg setting value to 1 to enable the shell.

Note: The functions for the shell API are only compiled and linked with the application when the SHELL_TASK setting is enabled. When you develop a package that supports shell commands, we recommend that your pakcage define:

  1. A syscfg setting that enables shell command processing for your package, with a restriction that when this setting is enabled, the SHELL_TASK setting must also be enabled.

  2. A conditional dependency on the sys/shell package when the setting defined in 1 above is enabled.

Here are example definitions from the syscfg.yml and pkg.yml files for the sys/log/full package. It defines the LOG_CLI setting to enable the log command in the shell:

# sys/log/full syscfg.yml
 LOG_CLI:
        description: 'Expose "log" command in shell.'
        value: 0
        restrictions:
            - SHELL_TASK

# sys/log/full pkg.yml
pkg.deps.LOG_CLI:
    - "@apache-mynewt-core/sys/shell"

Description

Processing Console Input Commands

The shell’s first job is to direct incoming commands to other subsystems. It parses the incoming character string into tokens and uses the first token to determine the subsystem command handler to call to process the command. When the shell calls the command handler, it passes the other tokens as arguments to the handler.

Registering Command Handlers

A package that implements a shell command must register a command handler to process the command.

New in release 1.1: The shell supports the concept of modules and allows a package to group shell commands under a name space. To run a command in the shell, you enter the module name and the command name. You can set a default module, using the select command, so that you only need to enter the command name to run a command from the default module. You can switch the module you designate as the default module.

There are two methods to register command handlers in Mynewt 1.1:

  • Method 1 (New in release 1.1): Define and register a set of commands for a module. This method allows grouping shell commands into namespaces. A package calls the shell_register() function to define a module and register the command handlers for the module.

    Note: The SHELL_MAX_MODULES syscfg setting specifies the maximum number of modules that can be registered. You can increase this value if your application and the packages it includes register more than the default value.

  • Method 2: Register a command handler without defining a module. A package calls the shell_cmd_register() function defined in Mynewt 1.0 to register a command handler. When a shell command is registered using this method, the command is automatically added to the compat module. The compat module supports backward compatibility for all the shell commands that are registered using the shell_cmd_register() function.

    Notes:

    • The SHELL_COMPAT syscfg setting must be set to 1 to enable backward compatibility support and the shell_cmd_register() function. Since Mynewt packages use method 2 to register shell commands and Mynewt plans to continue this support in future releases, you must keep the default setting value of 1.

    • The SHELL_MAX_COMPAT_COMMANDS syscfg setting specifies the maximum number of command handlers that can be registered using this method. You can increase this value if your application and the packages it includes register more than the default value.

Enabling Help Information for Shell Commands

The shell supports command help. A package that supports command help initializes the struct shell_cmd data structure with help text for the command before it registers the command with the shell. The SHELL_CMD_HELP syscfg setting enables or disbles help support for all shell commands. The feature is enabled by default.

Note: A package that implements help for a shell command should only initialize the help data structures within the #if MYNEWT_VAL(SHELL_CMD_HELP) preprocessor directive.

Enabling the OS and Prompt Shell Modules

The shell implements the os and prompt modules. These modules support the shell commands to view OS resources.

The os module implements commands to list task and mempool usage information and to view and change the time of day. The SHELL_OS_MODULE syscfg setting enables or disables the module. The module is enabled by default.

The prompt module implements the ticks command that controls whether to print the current os ticks in the prompt. The SHELL_PROMPT_MODULE syscfg setting enables or disables this module. The module is disabled by default.

Enabling Command Name Completion

The shell supports command name completion. The SHELL_COMPLETION syscfg setting enables or disables the feature. The feature is enabled by default.

Processing Newtmgr Line Protocol Over Serial Transport

The shell’s second job is to handle packet framing, encoding, and decoding of newtmgr protocol messages that are sent over the console. The Newtmgr serial transport package (mgmt/newtmgr/transport/newtmgr_shell) calls the shell_nlip_input_register() function to register a handler that the shell calls when it receives newtmgr request messages.

The SHELL_NEWTMGR syscfg setting specifies whether newtmgr is enabled over shell. The setting is enabled by default.

Data Structures

The struct shell_cmd data structure represents a shell command and is used to register a command.

struct shell_cmd {
    const char *sc_cmd;
    shell_cmd_func_t sc_cmd_func;
    const struct shell_cmd_help *help;
};

Element

Description

sc_cmd

Character string of the command name.

sc_cmd_f unc_t

Pointer to the command handler that processes the command.

help

Pointer to the shell_cmd_he lp structure. If the pointer is NULL, help information is not provided.

The sc_cmd_func_t is the command handler function type.

typedef int (*shell_cmd_func_t)(int argc, char *argv[]);

The argc parameter specifies the number of command line arguments and the argv parameter is an array of character pointers to the command arguments. The SHELL_CMD_ARGC_MAX syscfg setting specifies the maximum number of command line arguments that any shell command can have. This value must be increased if a shell command requires more than SHELL_CMD_ARGC_MAX number of command line arguments.

The struct shell_module data structure represents a shell module. It is used to register a shell module and the shell commands for the module.

struct shell_module {
    const char *name;
    const struct shell_cmd *commands;
};

Eleme nt

Description

name

Character string of the module name.

commands

Array of shell_cmd structures that specify the commands for the module. The sc_cmd, sc_cmd_func , and help fields in the last entry must be set to NULL to indicate the last entry in the array.

Note: A command handler registered via the shell_cmd_register() function is automatically added to the compat module.

The struct shell_param and struct shell_cmd_help data structures hold help texts for a shell command.

struct shell_param {
    const char *param_name;
    const char *help;
};

Element

Description

param_name

Character string of the command parameter name.

help

Character string of the help text for the parameter.

 
struct shell_cmd_help {
    const char *summary;
    const char *usage;
    const struct shell_param *params;
};

Element

Description

summary

Character string of a short description of the command.

usage

Character string of a usage description for the command.

params

Array of shell_param` ` structures that describe each parameter for the command. The last ``struct shell _param in the array must have the param_name and help fields set to NULL to indicate the last entry in the array.

API

- cmd_name command name (it will be put in “” to make string

Register global extended shell command function

Macro creates shell command that can be used when shell task is enabled This is equivalent of calling deprecated function shell_cmd_register.

@func - command function function of shell_cmd_ext_func_t @help pointer to shell_cmd_help

MAKE_SHELL_CMD(cmd_name, func, help)
MAKE_SHELL_EXT_CMD(cmd_name, func, help)
SHELL_HELP_(help_)
SHELL_CMD(cmd_, func_, help_)

constructs a legacy shell command.

SHELL_CMD_EXT(cmd_, func_, help_)

constructs an extended shell command.

typedef const char *(*shell_prompt_function_t)(void)

Callback to get the current prompt.

Return:

Current prompt string.

typedef int (*shell_nlip_input_func_t)(struct os_mbuf*, void *arg)
int shell_register(const char *shell_name, const struct shell_cmd *shell_commands)

Register a shell_module object.

Parameters:

  • shell_name – Module name to be entered in shell console.

  • shell_commands – Array of commands to register. The array should be terminated with an empty element.

void shell_register_app_cmd_handler(shell_cmd_func_t handler)

Optionally register an app default cmd handler.

Parameters:

  • handler – To be called if no cmd found in cmds registered with shell_init.

void shell_register_prompt_handler(shell_prompt_function_t handler)

Optionally register a custom prompt callback.

Parameters:

  • handler – To be called to get the current prompt.

void shell_register_default_module(const char *name)

Optionally register a default module, to avoid typing it in shell console.

Parameters:

  • name – Module name.

void shell_evq_set(struct os_eventq *evq)

Optionally set event queue to process shell command events.

Parameters:

  • evq – Event queue to be used in shell

int shell_exec(int argc, char **argv, struct streamer *streamer)

Processes a set of arguments and executes their corresponding shell command.

Parameters:

  • argc – The argument count (including command name).

  • argv – The argument list ([0] is command name).

  • streamer – The streamer to send output to.

Returns:

0 on success; SYS_E[…] on failure.

int shell_nlip_input_register(shell_nlip_input_func_t nf, void *arg)
int shell_nlip_output(struct os_mbuf *m)
int shell_cmd_register(const struct shell_cmd *sc)

Defines

SHELL_NMGR_OP_EXEC

Command IDs in the “shell” newtmgr group.

SHELL_MODULES_SECTION
SHELL_MODULE_SECTION(mod)
SHELL_MODULE_STD(_name, _command_begin, _command_end)

Create shell module with commands designated by begin and end pointers.

This will create object of type shell_mod_std and pointer to this object. Pointer will be placed in .shell_modules section so it will be put together with all other shell modules on one link time table.

Parameters:

  • _name – - name of the module

  • _command_begin – - pointer to start of the table with commands

  • _command_end – - pointer to end of the table with commands

SHELL_MODULE_WITH_TABLE(name_, table_)

Create shell module with static command table.

Parameters:

  • _name – - name of the module @parma _table - standard table of const struct shell_cmd with know size

SHELL_MODULE_CMD_SECTION(mod_, cmd_)
SHELL_COMPAT_CMDS_SECTION
SHELL_COMPAT_CMD_SECTION(cmd_)

Create shell module with link time table (name derived from _name)

Link table will have name derived from shell module. Link table must be declared in some pkg.yml in pkg.link_tables: section

i.e. pkg.yml

pkg.link_tables:

  • mcu_commands

mcu_cli.c

SHELL_MODULE_WITH_LINK_TABLE(mcu)

Parameters:

  • _name – - name of the shell module

SHELL_MODULE_CMD_WITH_NAME(mod_, cmd_, name_, ext_, func_, help_)

Create command for module.

Macro creates object of struct shell_cmd and puts it in link table for module

Parameters:

  • mod_ – - module name

  • cmd_ – - command name

  • name_ – - command name as string

  • ext_ – - 1 for extended command with streamer

  • func_ – - function to execute

  • help_ – - help structure for function

SHELL_MODULE_CMD(mod_, cmd_, func_, help_)

Create command for module.

Macro creates object of struct shell_cmd and puts it in link table for module

Parameters:

  • mod_ – - module name

  • cmd_ – - command name

  • func_ – - function to execute

  • help_ – - help structure for function

SHELL_MODULE_EXT_CMD(mod_, cmd_, func_, help_)

Create command for module.

Macro creates object of struct shell_cmd and puts it in link table for module

Parameters:

  • mod_ – - module name

  • cmd_ – - command name

  • func_ – - function to execute

  • help_ – - help structure for function

Typedefs

typedef int (*shell_cmd_func_t)(int argc, char *argv[])

Callback called when command is entered.

Param argc:

Number of parameters passed.

Param argv:

Array of option strings. First option is always command name.

Return:

0 in case of success or negative value in case of error.

typedef int (*shell_cmd_ext_func_t)(const struct shell_cmd *cmd, int argc, char *argv[], struct streamer *streamer)

Callback for “extended” shell commands.

Param cmd:

The shell command being executed.

Param argc:

Number of arguments passed.

Param argv:

Array of option strings. First option is always command name.

Param streamer:

The streamer to write shell output to.

Return:

0 on success; SYS_E[…] on failure.

typedef const struct shell_mod *shell_mod_t
typedef const struct shell_cmd *shell_cmd_t
typedef struct shell_mod_ops shell_mod_ops_t
typedef struct shell_mod_std shell_mod_std_t

Functions

static inline int shell_mod_command_count(shell_mod_t mod)
static inline shell_cmd_t shell_mod_command(shell_mod_t mod, size_t ix)

Variables

const struct shell_mod_ops shell_mod_std_ops
struct shell_param
#include <shell.h>

Public Members

const char *param_name
const char *help
struct shell_cmd_help
#include <shell.h>

Public Members

const char *summary
const char *usage
const struct shell_param *params
struct shell_cmd
#include <shell.h>

Public Members

uint8_t sc_ext
union shell_cmd.[anonymous] [anonymous]
const char *sc_cmd
const struct shell_cmd_help *help
struct shell_module
#include <shell.h>

Public Members

const char *name
const struct shell_cmd *commands
struct shell_mod_ops
#include <shell.h>

Public Members

size_t (*count)(shell_mod_t mod)

Returns number of module commands.

shell_cmd_t (*get)(shell_mod_t mod, size_t ix)

Return module command by it’s index.

struct shell_mod
#include <shell.h>

Public Members

const shell_mod_ops_t *ops
const char *name
struct shell_mod_std
#include <shell.h>

Public Members

struct shell_mod mod
const struct shell_cmd *commands
const struct shell_cmd *commands_end