subsys/shell/ is the debug command shell. Its public API is
include/pbl/shell/shell.h, and backends implement
include/pbl/shell/backend.h. Commands are defined next to the code they drive, collected at link time, and served
by any number of shell instances, one per backend.
A command is a struct pbl_shell_cmd: a name, a help string, a handler and
optionally a table of subcommands, so commands form a tree (bt disc start).
PBL_SHELL_CMD_REGISTER() / PBL_SHELL_CMD_ARG_REGISTER() register a root
command from any file. The entries land in the .pbl_shell_root_cmds
linker section, sorted by name.
A file-local subcommand table is a plain struct pbl_shell_cmd array of
PBL_SHELL_CMD() entries ending with PBL_SHELL_SUBCMD_SET_END.
PBL_SHELL_SUBCMD_SET_CREATE() builds a subcommand set that other files
extend with PBL_SHELL_SUBCMD_ADD(), without referencing any symbol of
the owner. The entries live in .pbl_shell_subcmds.<set>.<name> input
sections, sorted between a start marker and a terminator, so a set is a
contiguous, NULL-terminated array once linked. This is how, for
instance, the Bluetooth, console and driver code all add to bt or
flash.
Handlers get argc/argv with argv[0] being the matched command name.
mandatory (which counts argv[0]) and optional let the core check the
argument count; -h/--help, unknown subcommands and commands without a
handler print the help of the matched node. A handler returns 0 or a
negative errno; -EINPROGRESS keeps the shell busy until
pbl_shell_cmd_done(), for commands that finish from a callback.
Shell code is wrapped in #ifdef CONFIG_SHELL, and modules with a group of
commands can gate them further; for example drivers/imu/shell.c
builds with CONFIG_IMU_SHELL. Such options are off by default, as most of
these commands are bring-up tools; only the commands the integration tests
rely on are built with CONFIG_SHELL alone. CONFIG_DRIVER_SHELL and
CONFIG_SUBSYS_SHELL turn on every driver or subsystem command group at
once, e.g. pbl configure --board obelix@pvt -DCONFIG_DRIVER_SHELL=y.
static int prv_accel_read(const struct pbl_shell *sh, size_t argc, char **argv) {
...
pbl_shell_print(sh, "x=%d y=%d z=%d mg", sample.x, sample.y, sample.z);
return 0;
}
static const struct pbl_shell_cmd sub_accel[] = {
PBL_SHELL_CMD(read, NULL, "Read one sample", prv_accel_read),
PBL_SHELL_SUBCMD_SET_END,
};
PBL_SHELL_CMD_REGISTER(accel, sub_accel, "Accelerometer", NULL);
PBL_SHELL_DEFINE() creates an instance bound to a backend. Every instance
has its own line buffer and state, and commands receive the instance they
run on, so their output goes back where the command came from. Commands of
every instance run on SysWorkq.
Interactive instances (with a prompt) feed received characters with
pbl_shell_input_from_isr(). The core does line editing, echo, the prompt
and tab completion of command names on SysWorkq.
Line instances (no prompt) submit whole command lines with
pbl_shell_execute_line(), and get a done callback when the command
finishes.
The firmware’s backend is subsys/console/console.c, interactive, on the
Console: the shell is always listening, and log lines print above the
prompt, which comes back with the line being edited.
Release firmware has no shell: it needs CONFIG_CONSOLE, which is off there
unless it is manufacturing firmware.
Generated from PebbleOS f3212a729. This page is maintained in the pebbleos repository: docs/subsystems/shell.md.