Shell backends

Interface between the shell core and the transports that carry it. More...

Data Structures
struct	pbl_shell_backend_api
	Backend operations. More...
struct	pbl_shell
	Shell instance, defined with PBL_SHELL_DEFINE(). More...

Macros
#define	PBL_SHELL_DEFINE(_name, _prompt, _api, _backend_data)
	Define a shell instance and its state.

Functions
void	pbl_shell_start_from_isr (const struct pbl_shell *sh)
	Start a session of an interactive shell.
void	pbl_shell_stop (const struct pbl_shell *sh)
	End the session of an interactive shell, dropping pending input.
void	pbl_shell_input_from_isr (const struct pbl_shell *sh, char c)
	Queue a character received by an interactive shell.
int	pbl_shell_execute_line (const struct pbl_shell *sh, const char *line, size_t len)
	Run a command line on a line shell.
bool	pbl_shell_is_busy (const struct pbl_shell *sh)
	Check whether a command submitted to a shell is running.

Detailed Description

Interface between the shell core and the transports that carry it.

A backend owns one shell instance, defined with PBL_SHELL_DEFINE(), and moves its bytes. Interactive backends (with a prompt) feed raw characters with pbl_shell_input_from_isr() and get line editing, echo, the prompt and tab completion; line backends submit whole commands with pbl_shell_execute_line() and are told when they finish.

static void prv_write(const struct pbl_shell *sh, const char *data, size_t len) {
  uart_write(data, len);
}
 
static const struct pbl_shell_backend_api s_api = {
  .write = prv_write,
};
 
PBL_SHELL_DEFINE(shell_uart, "pebble> ", &s_api, NULL);
 
void uart_rx_isr(char c) {
  pbl_shell_input_from_isr(&shell_uart, c);
}

---

Data Structure Documentation

pbl_shell

struct pbl_shell

Shell instance, defined with PBL_SHELL_DEFINE().

Data Fields
const struct pbl_shell_backend_api *	api	Backend operations.
void *	backend_data	Backend data.
struct pbl_shell_ctx *	ctx	Runtime state.
const char *	name	Instance name.
const char *	prompt	Prompt of an interactive shell, NULL for a line shell.

Macro Definition Documentation

PBL_SHELL_DEFINE

#define PBL_SHELL_DEFINE	(		_name,
			_prompt,
			_api,
			_backend_data
	)

Value:

  static struct pbl_shell_ctx _name##_ctx;                    \
  const struct pbl_shell _name = {                            \
    .name = #_name,                                           \
    .prompt = (_prompt),                                      \
    .api = (_api),                                            \
    .backend_data = (_backend_data),                          \
    .ctx = &_name##_ctx,                                      \
  }

Define a shell instance and its state.

Parameters

_name	Instance name, an identifier; the instance is a global const struct pbl_shell with this name.
_prompt	Prompt for an interactive shell, NULL for a line shell.
_api	Backend operations.
_backend_data	Backend data.

Function Documentation

pbl_shell_execute_line()

int pbl_shell_execute_line	(	const struct pbl_shell *	sh,
		const char *	line,
		size_t	len
	)

Run a command line on a line shell.

The line is copied and runs on KernelBG; pbl_shell_backend_api::done reports the result.

Parameters

sh	Line shell.
line	Command line, not NUL-terminated.
len	Length of line.

Return values

0	The command was submitted.
-EBUSY	A command is running.
-ENOSPC	line is longer than CONFIG_SHELL_CMD_BUFF_SIZE.
-ENOMEM	The command could not be queued to KernelBG.

pbl_shell_input_from_isr()

void pbl_shell_input_from_isr	(	const struct pbl_shell *	sh,
		char	c
	)

Queue a character received by an interactive shell.

Call from an interrupt handler. Characters that overflow CONFIG_SHELL_RX_BUFF_SIZE are dropped.

Parameters

sh	Interactive shell.
c	Character.

pbl_shell_is_busy()

bool pbl_shell_is_busy

(

const struct pbl_shell *

sh

)

Check whether a command submitted to a shell is running.

Parameters

sh

Shell.

Returns

true while a command runs.

pbl_shell_start_from_isr()

void pbl_shell_start_from_isr

(

const struct pbl_shell *

sh

)

Start a session of an interactive shell.

Drops pending input; the prompt is printed from KernelBG. Call from an interrupt handler.

Parameters

sh	Interactive shell.

pbl_shell_stop()

void pbl_shell_stop

(

const struct pbl_shell *

sh

)

End the session of an interactive shell, dropping pending input.

Parameters

sh	Interactive shell.