高云FPGA系列教程（10）：letter-shell移植

本文是高云FPGA系列教程的第10篇文章。

shell，中文是外壳的意思，就是操作系统的外壳。通过shell命令可以操作和控制操作系统，比如Linux中的Shell命令就包括ls、cd、pwd等等。总结来说，Shell是一个命令解释器，它通过接受用户输入的Shell命令来启动、暂停、停止程序的运行或对计算机进行控制。

嵌入式平台可以基于串口实现shell功能，通过对串口命令的解析，可以执行相应的函数，查询变量的值等等。

本文介绍letter-shell开源shell库在高云GW1NSR-4C ARM处理器上的移植和应用。

letter-shell简介

letter-shell，一个功能强大的嵌入式shell，由标准C语言开发，可以在各种嵌入式平台上使用，可以通过命令行来执行函数，查询变量的值等等，支持裸机运行或RTOS运行，最新的发布版本是v3.1.2，letter-shell有以下功能：

• 命令自动补全
• 快捷键功能定义
• 命令权限管理
• 用户管理
• 变量支持
• 代理函数和参数代理解析

代码完全开源，并遵循MIT开源协议，Github收获近1K Star。

开源地址：

https://github.com/NevermindZZT/letter-shell

作者的主页地址：

https://nevermindzzt.github.io/

目前还保持更新状态，最近的一次提交是2023.07.25。

letter-shell源码获取

打开上文中letter-shell的开源地址，直接下载最新版本的Release代码，

或者，通过Git命令获取目前最新的代码，

$ git clone https://github.com/NevermindZZT/letter-shell.git --depth=1

Cloning into 'letter-shell'...
remote: Enumerating objects: 72, done.
remote: Counting objects: 100% (72/72), done.
remote: Compressing objects: 100% (66/66), done.
remote: Total 72 (delta 3), reused 35 (delta 2), pack-reused 0
Receiving objects: 100% (72/72), 783.28 KiB | 344.00 KiB/s, done.
Resolving deltas: 100% (3/3), done.

src目录中就是letter-shell的源文件，demo文件夹下是基于ESP32和STM32的移植示例代码。

letter-shell移植

首先把src文件夹的所有文件复制到GW1NSR-4C Keil工程的用户目录下，并新建两个接口文件：shell_port.c和shell_port.h，用来对接shell库。

把这些文件都导入到我们的工程中，并包含头文件路径。

shell_cfg.h文件通过宏定义，可以实现功能的配置，非常灵活。

在shell_port.c文件中实现shell_write函数（串口发送字符串），并进行shell初始化：

#include "shell.h"
#include "drv_uart.h"

Shell shell;
char shellBuffer[512];

short userShellWrite(char *data, unsigned short len)
{
    UART_SendString(UART0, data);
    return len;
}

void userShellInit(void)
{
    shell.write = userShellWrite;

    shellInit(&shell, shellBuffer, 512);
}

对于裸机移植，不用实现shell read函数，只需要实现write函数。

并在shellport.h文件中进行声明：

#ifndef __SHELL_PORT_H__
#define __SHELL_PORT_H__

#include "shell.h"

extern Shell shell;

void userShellInit(void);

#endif

然后在串口接收中断服务函数，每接收到一字节数据调用shellHandler函数。

void UART0_Handler(void)
{
	char rx = 0;
	
	if(UART_GetRxIRQStatus(UART0) == SET)
	{
		rx = UART_ReceiveChar(UART0);
        shellHandler(&shell, rx);
	}
	
	UART_ClearRxIRQ(UART0);
}

主程序初始化时调用userShellInit函数，

#include "main.h"

int main(void)
{
	delay_init();
	uart0_init(115200); //enable rx interrupt
    
    userShellInit();
    
    while(1)
    {

	}
}

重新编译生成bin文件，并下载到开发板，打开串口终端，如SercureCRT，可以看到串口输出如下信息，说明移植成功，按下tab键，会提示当前支持的一些命令：

函数和变量应用示例

移植成功之后，我们来演示函数和变量的调用，即通过在终端输入函数名和参数可以直接执行函数，输入变量名可以直接打印变量的实时值。

定义一些变量和函数，并注册到shell命令解析列表中。

#include "main.h"

char str[100] = "Hello GoWin GW1NSR-4C (TangNano 4K)";
int cnt = 0;

int func(int i, char ch, char *str)
{
    printf("input int: %d, char: %c, string: %s\r\n", i, ch, str);
    return 1;
}
//获取系统频率
int get_sysclk(void)
{
	printf("SystemCoreClock = %d\r\n", SystemCoreClock);
	printf("APB1 CLK = %d\r\n", PCLK1);
	printf("APB2 CLK = %d\r\n", PCLK2);
	printf("AHB CLK  = %d\r\n", HCLK);
    return 2;
}

SHELL_EXPORT_CMD(SHELL_CMD_PERMISSION(0)|SHELL_CMD_TYPE(SHELL_TYPE_CMD_FUNC), get_sysclk, get_sysclk, test);
SHELL_EXPORT_CMD(SHELL_CMD_PERMISSION(0)|SHELL_CMD_TYPE(SHELL_TYPE_CMD_FUNC), func, func, test);
SHELL_EXPORT_VAR(SHELL_CMD_PERMISSION(0)|SHELL_CMD_TYPE(SHELL_TYPE_VAR_INT), cnt, &cnt, test);
SHELL_EXPORT_VAR(SHELL_CMD_PERMISSION(0)|SHELL_CMD_TYPE(SHELL_TYPE_VAR_STRING), str, str, test);

int main(void)
{
	delay_init();
	uart0_init(115200); //enable rx interrupt
    
	printf("SystemCoreClock = %d\r\n", SystemCoreClock);
	printf("APB1 CLK = %d\r\n", PCLK1);
	printf("APB2 CLK = %d\r\n", PCLK2);
	printf("AHB CLK  = %d\r\n", HCLK);
	printf("Hello GW1NSR-4C SoC(ARM Cortex-M3)\r\n");
    printf("letter-shell Example\r\n");
    userShellInit();
    
    while(1)
    {
        delay_ms(1000);
        cnt++;
	}
}

下载，运行。

在终端中直接输入对应的函数名即可直接运行函数，如果函数带参数，还可以在后面输入参数，参数类型支持整形、字符、字符串等多种类型，而且运行结束可以看到函数的返回值，输入变量的名字，可以直接获取到当前实时值，变量类型值整形和字符、字符串多种类型，非常强大、方便。

本文是高云FPGA系列教程的第10篇文章。