本文说明shell系统中提供给用户的常用函数及作用。

打印函数

为避免输出信息混乱，在shell的命令函数内尽量避免使用printf和printk。可以以下函数将shell信息显示在shell后端上

1	void shell_fprintf(const struct shell shell, enum shell_vt100_color color, const char fmt, ...)

类printf将格式化字符串输出到shell后端

shell – [in] 指向shell实例.
color – [in] 输出字符串的颜色.
fmt – [in] 格式化字符串.
… – [in] 参数列表.

为了方便使用对shell_fprintf进行了包装提供了如下几个宏接口：

shell_print(_sh, _ft, ...)
shell_info(_sh, _ft, ...)
shell_warn(_sh, _ft, ...)
shell_error(_sh, _ft, ...)

宏接口使用方法一致，显示结果只有颜色的区别, print无色，info绿色，warn黄色，error红色。

_sh – [in] 指向shell实例。
_ft – [in] F格式化字符串。
… – [in] 参数列表。

shell函数在被shell系统调用时会传入shell实例，例如shell命令函数cmd_info_board使用示例

static int cmd_info_board(const struct shell *sh, size_t argc, char **argv)
{

	shell_print(sh, CONFIG_BOARD);
	shell_info(sh, CONFIG_BOARD);
	shell_warn(sh, CONFIG_BOARD);
	shell_error(sh, CONFIG_BOARD);

	return 0;
}

1	void shell_hexdump_line(const struct shell shell, unsigned int offset, const uint8_t data, size_t len)

指定显示地址，输出第一行十六进制数据。一行输出为16个字节，因此无论len多长都只输出前16个字节。

shell – [in] 指向shell实例.
offset – [in] 显示的地址.
data – [in] 指向数据.
len – [in] 数据长度.

1	void shell_hexdump(const struct shell shell, const uint8_t data, size_t len)

输出十六进制数据。

shell – [in] 指向shell实例.
offset – [in] 显示的地址.
len – [in] 数据长度.

下面代码片段演示shell_hexdump_line与shell_hexdump差别

uint8_t data[] = { 1, 2, 3, 4, 5, 6, 7, 8,
    9, 10, 11, 12, 13, 14, 15, 16,
    17, 18, 19, 20, 21, 22, 23, 24,
    25, 26, 27, 28, 29, 30, 31, 32,
    33, 34, };

shell_info(sh, "shell_hexdump_line");
shell_hexdump_line(sh, 0x8000, data, sizeof(data));

shell_info(sh, "shell_hexdump");
shell_hexdump(sh, data, sizeof(data));

显示结果为

shell_hexdump_line
00008000: 01 02 03 04 05 06 07 08  09 0a 0b 0c 0d 0e 0f 10 |........ ........|
shell_hexdump
00000000: 01 02 03 04 05 06 07 08  09 0a 0b 0c 0d 0e 0f 10 |........ ........|
00000010: 11 12 13 14 15 16 17 18  19 1a 1b 1c 1d 1e 1f 20 |........ ....... |
00000020: 21 22                                            |!"               |

命令执行函数

在代码中可以通过shell_execute_cmd函数执行shell命令

1	int shell_execute_cmd(const struct shell shell, const char cmd)

shell – [in] 指向执行shell命令的shell实例。
cmd – [in] 要执行的shell命令.

shell实例传入NULL表示使用Dummy，其它的后端shell实例可以通过下面函数获取：

UART： const struct shell *shell_backend_uart_get_ptr(void)
RTT：const struct shell *shell_backend_rtt_get_ptr(void)
telnet：const struct shell *shell_backend_telnet_get_ptr(void)
mqtt：const struct shell *shell_backend_mqtt_get_ptr(void)

实例代码如下:

void main(void)
{
        /* 在dummy后端执行shell命令，看不到输出 */
        shell_execute_cmd(NULL, "shell_sample info");

        /* 在uart后端执行shell命令，可以看到输出 */
        shell_execute_cmd(shell_backend_uart_get_ptr(),
                          "shell_sample info");
}

其它函数

1	int shell_prompt_change(const struct shell shell, const char prompt)

改变shell提示符，例如uart shell后端的提示符为uart:~$

shell – [in] 指向shell实例.
prompt – [in] 提示符字符串.
返回值：0表示成功，-EINVAL失败

1	void shell_help(const struct shell *shell)

显示当前命令的帮助信息

shell – [in] 指向shell实例.

1	int shell_set_root_cmd(const char *cmd)

设置根命令，等同于select命令

cmd – 命令字符串，传入NULL表示reset，等同于执行alt+r
返回值：0表示成功，-EINVAL失败

1	void shell_set_bypass(const struct shell *shell, shell_bypass_cb_t bypass)

将shell接收到的数据跳过，送到bypass的回调中处理。

shell – [in] 指向shell实例.
bypass – [in] 回调函数，当传入NULL时表示禁用bypass.

1	int shell_insert_mode_set(const struct shell *shell, bool val)

设置shell终端输入插入模式，等同于Insert按键

shell – [in] 指向shell实例.
val – [in] 插入模式
返回值：前一次的状态(0或1)，-EINVAL失败

1	int shell_use_colors_set(const struct shell *shell, bool val)

设置shell颜色，等同于shell colors命令

shell – [in] 指向shell实例
val – [in] 是否支持shell颜色.
返回值：前一次的状态(0或1)，-EINVAL失败

1	int shell_echo_set(const struct shell *shell, bool val)

设置shell自动回显，等同于shell echo命令

shell – [in] 指向shell实例
val – [in] 是否支持回显.
返回值：前一次的状态(0或1)，-EINVAL失败

1	int shell_mode_delete_set(const struct shell *shell, bool val)

设置backspace模式，等同于shell backspace_mode命令

shell – [in] 指向shell实例
val – [in] backspace模式.
返回值：前一次的状态(0或1)，-EINVAL失败

参考

https://docs.zephyrproject.org/latest/services/shell/index.html