Shell¶

Overview¶

The Shell enables multiple subsystem to use and expose their shell interface simultaneously.

Each subsystem can support shell functionality dynamically by its Kconfig file, which enables or disables the shell usage for the subsystem.

Using shell commands¶

Use one of the following formats:

Help commands¶

help: Prints the list of available modules.
help MODULE_NAME: Prints the names of the available commands for the module.
help MODULE_NAME COMMAND: Prints help for the module’s command (the help describes the available module commands and required parameters).

Specific module’s commands¶

A shell interface exposing subsystem features is a shell module, multiple modules can be available at the same time.

MODULE_NAME COMMAND: One of the available modules is “KERNEL”, for Kernel module commands. Information about registering a new module and its commands can be found in SHELL_REGISTER documentation.

Select module commands¶

select MODULE_NAME: Use this command when using the shell only for one module. After entering this command, you will not need to enter the module name in further commands. If the selected module has set a default shell prompt during its initialization, the prompt will be changed to that one. Otherwise, the prompt will be changed to the selected module’s name to reflect the current module in use.
select: Clears selected module. Restores prompt as well.

Kernel module commands¶

When enabled through option CONFIG_KERNEL_SHELL, the Kernel shell module commands display useful kernel-specific information.

You can issue these Kernel module shell commands by specifying the module and command:

shell> kernel version

or by first selecting the kernel module, and then issuing the specific command:

shell> select kernel
kernel> version

Here are the Kernel module shell commands:

version: Displays the kernel version number
uptime: Displays the system uptime in milliseconds
cycles: Displays the current time (in cycles), as measured by the system’s hardware clock
threads: Displays information about the running threads (if CONFIG_OBJECT_TRACING and CONFIG_THREAD_MONITOR are enabled).
stacks: Displays size and use information about the main, idle, interrupt and system workqueue call stacks (if CONFIG_INIT_STACKS is enabled)

Other commands¶

noprompt: This command will disable the shell prompt. The shell will still be fully functional, but the prompt will not be printed each time the shell expects a new command.

Shell configuration¶

There are two levels of configuration: Infrastructure level and Module level.

Infrastructure level¶

The option CONFIG_CONSOLE_SHELL enables the shell subsystem and enable the default features of the shell subsystem.

Module/Subsystem level¶

Each subsystem using the shell service should add a unique flag in its Kconfig file.

Example:

CONFIG_NET_SHELL=y

In the subsystem’s code, the shell usage depends on this config parameter. This subsystem specific flag should also depend on CONFIG_CONSOLE_SHELL flag.

Configuration steps to add shell functionality to a module¶

Check that CONFIG_CONSOLE_SHELL is set to yes.

Add the subsystem unique flag to its Kconfig file.

Writing a shell module¶

In order to support shell in your subsystem, the application must do the following:

Module configuration flag: Declare a new flag in your subsystem Kconfig file. It should depend on CONFIG_CONSOLE_SHELL flag.
Module registration to shell: Add your shell identifier and register its callback functions in the shell database using SHELL_REGISTER.

Optionally, you can use one of the following API functions to override default behavior and settings:

shell_register_default_module()
shell_register_prompt_handler()

In case of a sample applications as well as the test environment, you can choose to set a default module in code level. In this case, the function shell_register_default_module() should be called after calling SHELL_REGISTER in application level. If the function shell_register_prompt_handler() was called as well, the prompt will be changed to that one. Otherwise, the prompt will be changed to the selected module’s name, in order to reflect the current module in use.

Note

Even if a default module was set in code level, it can be overwritten by “select” shell command.

You can use shell_register_default_module() in the following cases:

Use this command in case of using the shell only for one module. After entering this command, no need to enter module name in further commands.
Use this function for shell backward compatibility.

More details on those optional functions can be found in Shell API Functions.

Shell API Functions¶

group _shell_api_functions

Kernel Shell API.

Defines

SHELL_REGISTER(_name, _commands)¶

Create shell_module object and set it up for boot time initialization.

This macro defines a shell_module object that is automatically configured by the kernel during system initialization.

Parameters

_name: Module name to be entered in shell console.
_commands: Array of commands to register. Shell array entries must be packed to calculate array size correctly.

SHELL_REGISTER_WITH_PROMPT(_name, _commands, _prompt)¶

Create shell_module object and set it up for boot time initialization.

This macro defines a shell_module object that is automatically configured by the kernel during system initialization, in addition to that this also enables setting a custom prompt handler when the module is selected.

Parameters

_name: Module name to be entered in shell console.
_commands: Array of commands to register. Shell array entries must be packed to calculate array size correctly.
_prompt: Optional prompt handler to be set when module is selected.

SHELL_REGISTER_COMMAND(_name, _callback, _help)¶

Create a standalone command and set it up for boot time initialization.

This macro defines a shell_cmd object that is automatically configured by the kernel during system initialization.

The command will be available in the default module, so it will be available immediately.

Functions

void shell_init(const char *prompt)¶

Initialize shell with optional prompt, NULL in case no prompt is needed.

Parameters

prompt: Prompt to be printed on serial console.

void shell_register_app_cmd_handler(shell_cmd_function_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 eliminate typing it in shell console or for backwards compatibility.

Parameters

name: Module name.

void shell_register_mcumgr_handler(shell_mcumgr_function_t handler, void *arg)¶

Configures a callback for received mcumgr packets.

Parameters

handler: The callback to execute when an mcumgr packet is received.
arg: An optional argument to pass to the callback.

int shell_exec(char *line)¶

Execute command line.

Pass command line to shell to execute. The line cannot be a C string literal since it will be modified in place, instead a variable can be used:

char cmd[] = “command”; shell_exec(cmd);

Note: This by no means makes any of the commands a stable interface, so this function should only be used for debugging/diagnostic.

Return

Result of the execution

Parameters

line: Command line to be executed