Zephyr shell系统使用指南-常用函数说明

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

打印函数 链接到标题

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

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

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] 数据长度.

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命令

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

其它函数 链接到标题 

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

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

  • shell – [in] 指向shell实例.

  • prompt – [in] 提示符字符串.

  • 返回值：0表示成功，-EINVAL失败

void shell_help(const struct shell *shell)

显示当前命令的帮助信息

  • shell – [in] 指向shell实例.
int shell_set_root_cmd(const char *cmd)

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

  • cmd – 命令字符串，传入NULL表示reset，等同于执行alt+r
  • 返回值：0表示成功，-EINVAL失败
void shell_set_bypass(const struct shell *shell, shell_bypass_cb_t bypass)

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

  • shell – [in] 指向shell实例.

  • bypass – [in] 回调函数，当传入NULL时表示禁用bypass.

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

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

  • shell – [in] 指向shell实例.

  • val – [in] 插入模式

  • 返回值：前一次的状态(0或1)，-EINVAL失败

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

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

  • shell – [in] 指向shell实例

  • val – [in] 是否支持shell颜色.

  • 返回值：前一次的状态(0或1)，-EINVAL失败

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

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

  • shell – [in] 指向shell实例

  • val – [in] 是否支持回显.

  • 返回值：前一次的状态(0或1)，-EINVAL失败

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