Shell

Debug command shell (CONFIG_SHELL). More...

Modules
	Shell backends
	Interface between the shell core and the transports that carry it.

Data Structures
struct	pbl_shell_cmd
	Command. More...

Macros
#define	PBL_SHELL_OPT_ARG_MAX   UINT8_MAX
	Any number of optional arguments.
#define	PBL_SHELL_CMD_ARG(_syntax, _subcmd, _help, _handler, _mand, _opt)
	Initializer of a command with an argument count check.
#define	PBL_SHELL_CMD(_syntax, _subcmd, _help, _handler)    PBL_SHELL_CMD_ARG(_syntax, _subcmd, _help, _handler, 0, 0)
	Initializer of a command without an argument count check.
#define	PBL_SHELL_SUBCMD_SET_END   {0}
	Terminates a file-local subcommand array of PBL_SHELL_CMD() entries.
#define	PBL_SHELL_SUBCMD_SET_CREATE(_name)
	Define a subcommand set that any file can extend with PBL_SHELL_SUBCMD_ADD().
#define	PBL_SHELL_SUBCMD_ADD(_set, _syntax, _subcmd, _help, _handler, _mand, _opt)    PBL_SHELL_SUBCMD_ADD_ID(__COUNTER__, _set, _syntax, _subcmd, _help, _handler, _mand, _opt)
	Add a subcommand to a set, from any file.
#define	PBL_SHELL_CMD_ARG_REGISTER(_syntax, _subcmd, _help, _handler, _mand, _opt)
	Register a root command with an argument count check.
#define	PBL_SHELL_CMD_REGISTER(_syntax, _subcmd, _help, _handler)    PBL_SHELL_CMD_ARG_REGISTER(_syntax, _subcmd, _help, _handler, 0, 0)
	Register a root command without an argument count check.

Typedefs
typedef int(*	pbl_shell_cmd_handler_t) (const struct pbl_shell *sh, size_t argc, char **argv)
	Command handler.

Functions
void	pbl_shell_print (const struct pbl_shell *sh, const char *fmt,...)
	Print a formatted line.
void	pbl_shell_fprintf (const struct pbl_shell *sh, const char *fmt,...)
	Print formatted text without a line break.
void	pbl_shell_vfprintf (const struct pbl_shell *sh, const char *fmt, va_list args)
	Print formatted text without a line break, with a va_list.
void	pbl_shell_error (const struct pbl_shell *sh, const char *fmt,...)
	Print a formatted line prefixed with "error: ".
void	pbl_shell_hexdump (const struct pbl_shell *sh, const void *data, size_t len)
	Print a hex dump, 16 bytes a line with offsets and ASCII.
void	pbl_shell_help (const struct pbl_shell *sh, const struct pbl_shell_cmd *cmd)
	Print the help of a command and the list of its subcommands.
void	pbl_shell_cmd_done (const struct pbl_shell *sh, int ret)
	Finish a command whose handler returned -EINPROGRESS.
int	pbl_shell_strtol (const char *str, long *out)
	Parse an argument as a signed integer.
int	pbl_shell_strtoul (const char *str, unsigned long *out)
	Parse an argument as an unsigned integer.

Detailed Description

Debug command shell (CONFIG_SHELL).

Commands are defined next to the code they drive, collected at link time and served by any number of shell instances, one per backend (see Shell backends). Commands form a tree: a command has a name, a help string, an optional handler and optional subcommands. Handlers of every instance run on KernelBG.

A handler gets argc / argv with argv[0] being the matched command name. The core checks the argument count, prints the help of the matched command for -h / --help, unknown subcommands and commands without a handler, and prints an error for unknown commands.

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);

Code in other files can extend a command when its subcommands are a set:

// owner
PBL_SHELL_SUBCMD_SET_CREATE(sub_flash);
PBL_SHELL_CMD_REGISTER(flash, sub_flash, "Flash", NULL);
 
// any other file
PBL_SHELL_SUBCMD_ADD(sub_flash, erase, NULL, "Erase <addr> <len>", prv_erase, 3, 0);

---

Data Structure Documentation

pbl_shell_cmd

struct pbl_shell_cmd

Command.

Data Fields
pbl_shell_cmd_handler_t	handler	Handler, or NULL to print the help.
const char *	help	Help string, or NULL.
uint8_t	mandatory	Arguments counting the command name itself; 0 skips the check.
uint8_t	optional	Extra arguments allowed, or PBL_SHELL_OPT_ARG_MAX for any number.
const struct pbl_shell_cmd *	subcmd	Subcommands, terminated by PBL_SHELL_SUBCMD_SET_END, or NULL.
const char *	syntax	Name.

Macro Definition Documentation

PBL_SHELL_CMD

#define PBL_SHELL_CMD	(		_syntax,
			_subcmd,
			_help,
			_handler
	)		PBL_SHELL_CMD_ARG(_syntax, _subcmd, _help, _handler, 0, 0)

Initializer of a command without an argument count check.

Parameters

_syntax	Name, an identifier.
_subcmd	Subcommands, or NULL.
_help	Help string, or NULL.
_handler	Handler, or NULL.

PBL_SHELL_CMD_ARG

#define PBL_SHELL_CMD_ARG	(		_syntax,
			_subcmd,
			_help,
			_handler,
			_mand,
			_opt
	)

Value:

  {                                                                       \
    .syntax = #_syntax,                                                   \
    .help = (_help),                                                      \
    .subcmd = (_subcmd),                                                  \
    .handler = (_handler),                                                \
    .mandatory = (_mand),                                                 \
    .optional = (_opt),                                                   \
  }

Initializer of a command with an argument count check.

Parameters

_syntax	Name, an identifier.
_subcmd	Subcommands, or NULL.
_help	Help string, or NULL.
_handler	Handler, or NULL.
_mand	Mandatory arguments, the command name included; 0 skips the check.
_opt	Optional arguments, or PBL_SHELL_OPT_ARG_MAX.

PBL_SHELL_CMD_ARG_REGISTER

#define PBL_SHELL_CMD_ARG_REGISTER	(		_syntax,
			_subcmd,
			_help,
			_handler,
			_mand,
			_opt
	)

Value:

  static const struct pbl_shell_cmd pbl_shell_root_cmd_##_syntax PBL_USED PBL_ALIGNED(4) \
      PBL_SECTION(".pbl_shell_root_cmds." #_syntax) =                                    \
          PBL_SHELL_CMD_ARG(_syntax, _subcmd, _help, _handler, _mand, _opt)

Register a root command with an argument count check.

Root commands are sorted by name by the linker script, or when looked up in builds without one.

Parameters

_syntax	Name, an identifier.
_subcmd	Subcommands, or NULL.
_help	Help string, or NULL.
_handler	Handler, or NULL.
_mand	Mandatory arguments, the command name included; 0 skips the check.
_opt	Optional arguments, or PBL_SHELL_OPT_ARG_MAX.

PBL_SHELL_CMD_REGISTER

#define PBL_SHELL_CMD_REGISTER	(		_syntax,
			_subcmd,
			_help,
			_handler
	)		PBL_SHELL_CMD_ARG_REGISTER(_syntax, _subcmd, _help, _handler, 0, 0)

Register a root command without an argument count check.

Parameters

_syntax	Name, an identifier.
_subcmd	Subcommands, or NULL.
_help	Help string, or NULL.
_handler	Handler, or NULL.

PBL_SHELL_OPT_ARG_MAX

#define PBL_SHELL_OPT_ARG_MAX   UINT8_MAX

Any number of optional arguments.

PBL_SHELL_SUBCMD_ADD

#define PBL_SHELL_SUBCMD_ADD	(		_set,
			_syntax,
			_subcmd,
			_help,
			_handler,
			_mand,
			_opt
	)		PBL_SHELL_SUBCMD_ADD_ID(__COUNTER__, _set, _syntax, _subcmd, _help, _handler, _mand, _opt)

Add a subcommand to a set, from any file.

Entries of a set that is not built are unreachable.

Parameters

_set	Set created with PBL_SHELL_SUBCMD_SET_CREATE().
_syntax	Name, an identifier.
_subcmd	Subcommands, or NULL.
_help	Help string, or NULL.
_handler	Handler, or NULL.
_mand	Mandatory arguments, the command name included; 0 skips the check.
_opt	Optional arguments, or PBL_SHELL_OPT_ARG_MAX.

PBL_SHELL_SUBCMD_SET_CREATE

#define PBL_SHELL_SUBCMD_SET_CREATE

(

_name

)

Value:

  static const struct pbl_shell_cmd _name[0] PBL_USED PBL_ALIGNED(4)    \
      PBL_SECTION(".pbl_shell_subcmds." #_name ".!");                   \
  static const struct pbl_shell_cmd _name##_end PBL_USED PBL_ALIGNED(4) \
      PBL_SECTION(".pbl_shell_subcmds." #_name ".~") = PBL_SHELL_SUBCMD_SET_END

Define a subcommand set that any file can extend with PBL_SHELL_SUBCMD_ADD().

Entries are sorted by name by the linker script, or when looked up in builds without one (PBL_NO_LINKER_SCRIPT).

Parameters

_name

Name of the set, usable as the _subcmd of a command.

PBL_SHELL_SUBCMD_SET_END

#define PBL_SHELL_SUBCMD_SET_END   {0}

Terminates a file-local subcommand array of PBL_SHELL_CMD() entries.

Typedef Documentation

pbl_shell_cmd_handler_t

typedef int(* pbl_shell_cmd_handler_t) (const struct pbl_shell *sh, size_t argc, char **argv)

Command handler.

Parameters

sh	Shell the command runs on; its output goes back there.
argc	Number of arguments in argv, the command name included.
argv	Matched command name followed by its arguments, NULL-terminated.

Returns

0 on success, a negative errno on failure, or -EINPROGRESS to finish later with pbl_shell_cmd_done().

Function Documentation

pbl_shell_cmd_done()

void pbl_shell_cmd_done	(	const struct pbl_shell *	sh,
		int	ret
	)

Finish a command whose handler returned -EINPROGRESS.

May be called from any thread.

Parameters

sh	Shell the command runs on.
ret	Result of the command, 0 or a negative errno.

pbl_shell_error()

void pbl_shell_error	(	const struct pbl_shell *	sh,
		const char *	fmt,
			...
	)

Print a formatted line prefixed with "error: ".

Parameters

sh	Shell.
fmt	printf-style format.
...	Format arguments.

pbl_shell_fprintf()

void pbl_shell_fprintf	(	const struct pbl_shell *	sh,
		const char *	fmt,
			...
	)

Print formatted text without a line break.

Output is truncated to CONFIG_SHELL_PRINTF_BUFF_SIZE - 1 characters.

Parameters

sh	Shell.
fmt	printf-style format.
...	Format arguments.

pbl_shell_help()

void pbl_shell_help	(	const struct pbl_shell *	sh,
		const struct pbl_shell_cmd *	cmd
	)

Print the help of a command and the list of its subcommands.

Parameters

sh	Shell.
cmd	Command.

pbl_shell_hexdump()

void pbl_shell_hexdump	(	const struct pbl_shell *	sh,
		const void *	data,
		size_t	len
	)

Print a hex dump, 16 bytes a line with offsets and ASCII.

Parameters

sh	Shell.
data	Data.
len	Length of data in bytes.

pbl_shell_print()

void pbl_shell_print	(	const struct pbl_shell *	sh,
		const char *	fmt,
			...
	)

Print a formatted line.

Parameters

sh	Shell.
fmt	printf-style format.
...	Format arguments.

pbl_shell_strtol()

int pbl_shell_strtol	(	const char *	str,
		long *	out
	)

Parse an argument as a signed integer.

Accepts decimal, hex (0x prefix) and octal (0 prefix).

Parameters

	str	Argument.
[out]	out	Value.

Return values

0	Success.
-EINVAL	str is empty, not a number or out of range.

pbl_shell_strtoul()

int pbl_shell_strtoul	(	const char *	str,
		unsigned long *	out
	)

Parse an argument as an unsigned integer.

As pbl_shell_strtol(), rejecting negative numbers.

Parameters

	str	Argument.
[out]	out	Value.

Return values

0	Success.
-EINVAL	str is empty, negative, not a number or out of range.

pbl_shell_vfprintf()

void pbl_shell_vfprintf	(	const struct pbl_shell *	sh,
		const char *	fmt,
		va_list	args
	)

Print formatted text without a line break, with a va_list.

Parameters

sh	Shell.
fmt	printf-style format.
args	Format arguments.