在使用HC32官方的代码生成工具XHCode的时候发现一个小问题：虽然在时钟树界面配置了USB的时钟，但是生成的代码中并没有对USBCKS的初始化。同时翻看官方驱动库HC32F460_DDL_Rev3.3.0中的例程时，发现并没有USB的例程。所以稍微研究了一下各个外设的时钟源，以及如何选择各时钟源，写篇文章记录一下。

## 时钟树概览
手册中的时钟树框图如下：
![](https://blog.zxcli.top/static/img/040d20df82162ee740885c9e76bf1e7e.clipboard-2025-09-16.png)
看起来有亿点~~复杂~~，稍微简化一下就是XHCode配置界面的样子：
![](https://blog.zxcli.top/static/img/107df6de6faa1b0449484f3d6a3df3fe.clipboard-2025-09-16.png)   
外部XTAL，XTAL32以及内部的HRC，MRC，LRC这些低速时钟无需特别关心，因为它们基本上都是固定的值，~~没啥好讲的~~。   
:::note{title="外部晶振XTAL的频率定义"}
**位于common/system_hc32f460.h中，XTAL_VALUE即为晶振频率。XHCode并不会自动修改这个值，如果不是8M请自行修改。**
![](https://blog.zxcli.top/static/img/6dfed12c65cb4069fa43ddfd9a6e1aa0.clipboard-2025-09-16.png)
:::
:::tip{title="注意"}
**如果使用GCC进行开发的话**，HRC这里会有一点小坑，它有两个频率16M和20M可以选择。如果代码是用20M的频率去配置一般是没有问题的，但是如果使用16M就会出现时钟初始化失败的情况。根本原因就在于HC32官方选择了一种很扭捏的方式配置HRC_VALUE的值，导致选择16M时实际代码里面是按20M在计算。从上面的图可以看到，HRC_VALUE并没有和MRC_VALUE，LRC_VALUE写在一起。
HRC_VALUE的具体配置位于**SystemCoreClockUpdate()**：
![](https://blog.zxcli.top/static/img/07907d354c904cd768936f43f008d349.clipboard-2025-09-16.png) 
但是这个函数位于main()之前，而且通过注释可以知道HRC_VALUE的值是根据ICG1.HRCFREQSEL来选择的。这个IGC1是个什么东西呢，手册里面是这样描述的：
![](https://blog.zxcli.top/static/img/9b44f575dc871a7cfdb83ca324d88fde.clipboard-2025-09-16.png)
HRCFREQSEL位是这样定义的：
![](https://blog.zxcli.top/static/img/deb1cc99fc8664020d5d71a849d47619.clipboard-2025-09-16.png)
也就是说，在烧录代码之前，要先烧录ICG1.HRCFREQSEL位为1才能才能选择HRC为16M，否则HRC的值会一直是20M。但是你要是使用XHCode生成的keil工程，而且使用keil进行烧录，就会发现使用16M配置也是正常的。原因在于XHCode生成了.SFR文件，里面提前写入了ICG1.HRCFREQSEL的值，keil在烧录代码之前就会提前烧录这个寄存器的值。但是GCC这边就没法这样干了，所以使用GCC进行开发时，如果没有特殊需求，HRC最好还是配置成20M。
:::
低速时钟经过PLLSRC的选择进入MPLL和UPLL进行倍频和分频，然后得到UPLLR,UPLLQ,UPLLP,MPLLR,MPLLQ,MPLLP六个时钟，供系统时钟和外设时钟选择。官方例程中MPLL和UPLL的初始化如下：
``` c
/* MPLL config */
// 以PLL为指代
stc_clock_pll_init_t stcMPLLInit;

(void)CLK_PLLStructInit(&stcMPLLInit);

stcMPLLInit.PLLCFGR = 0UL;
stcMPLLInit.PLLCFGR_f.PLLM = (2UL - 1UL);
stcMPLLInit.PLLCFGR_f.PLLN = (40UL - 1UL);
stcMPLLInit.PLLCFGR_f.PLLP = (2UL - 1UL);
stcMPLLInit.PLLCFGR_f.PLLQ = (2UL - 1UL);
stcMPLLInit.PLLCFGR_f.PLLR = (2UL - 1UL);
stcMPLLInit.u8PLLState = CLK_PLL_ON;
stcMPLLInit.PLLCFGR_f.PLLSRC = CLK_PLL_SRC_HRC;

(void)CLK_PLLInit(&stcMPLLInit);

/* UPLL config */
// 以PLLx为指代
stc_clock_xtal_init_t stcXtalInit;

(void)CLK_PLLxStructInit(&stcUpllInit);

stcUpllInit.u8PLLState = CLK_PLLX_ON;
stcUpllInit.PLLCFGR = 0UL;
stcUpllInit.PLLCFGR_f.PLLM = (2UL  - 1UL);
stcUpllInit.PLLCFGR_f.PLLN = (40UL - 1UL);
stcUpllInit.PLLCFGR_f.PLLR = (8UL  - 1UL);
stcUpllInit.PLLCFGR_f.PLLQ = (10UL - 1UL);
stcUpllInit.PLLCFGR_f.PLLP = (16UL - 1UL);
(void)CLK_PLLxInit(&stcUpllInit);
```
总之就是配置输入时钟源，以及分频和倍频系数。   

## 系统时钟
![](https://blog.zxcli.top/static/img/9cc62b32fcd05c01bec5bd579a36c1e5.clipboard-2025-09-16.png)
系统时钟的时钟源有6个，分别是MPLLP,XTAL,XTAL32,HRC,MRC和LRC。选择系统时钟源的API是`CLK_SetSysClockSrc(uint8_t u8Src)`，u8Src可以输入的参数如下：

``` c
/**
 * @defgroup CLK_System_Clock_Source System Clock Source
 * @{
 */
#define CLK_SYSCLK_SRC_HRC              (0x00U)
#define CLK_SYSCLK_SRC_MRC              (0x01U)
#define CLK_SYSCLK_SRC_LRC              (0x02U)
#define CLK_SYSCLK_SRC_XTAL             (0x03U)
#define CLK_SYSCLK_SRC_XTAL32           (0x04U)
#define CLK_SYSCLK_SRC_PLL              (0x05U)
```
系统时钟经过分频后又生成8个时钟：HCLK,PCLK0,PCLK1,PCLK2,PCLK3,PCLK4,EXCLK,TPIUCLK。各自的作用在手册中有详细说明，如下：
![](https://blog.zxcli.top/static/img/603b1cbbaa62b309d8718dc0bb703a3b.clipboard-2025-09-16.png)
这8个时钟的分频系数可以通过`CLK_SetClockDiv(uint32_t u32Clock, uint32_t u32Div)`设置，示例如下：
``` c
/* Set bus clock div. */
CLK_SetClockDiv(CLK_BUS_CLK_ALL, (CLK_HCLK_DIV1 | CLK_PCLK0_DIV1 | CLK_PCLK1_DIV2 | \
                               CLK_PCLK2_DIV4 | CLK_PCLK3_DIV2 | CLK_PCLK4_DIV2));
```
下面讲一下ADC时钟和USB时钟。   
## ADC时钟
![](https://blog.zxcli.top/static/img/990d785dae521d5307ff678542885a8b.clipboard-2025-09-17.png)
根据手册描述，ADC模块需要两个时钟，一个是模拟电路时钟ADCLK，另一个是数字接口时钟PCLK4。ADC的时钟源大致可以分为两类：   

1. 使用系统时钟分频出来的PCLK2和PCLK4   
当使用PCLK2和PCLK4作为ADC的时钟时，PCLK2作为模拟电路时钟，最高频率60M；PCLK4作为数字接口时钟，最高频率100M。同时还要满足`PCLK4 : PCLK2 = 1:1, 2:1, 4:1, 8:1, 1:2, 1:4`的关系。
2. 使用UPLL和MPLL生成的时钟   
当使用使用UPLL和MPLL生成的6个时钟时，模拟电路时钟和数字接口时钟连接在一起，此时最高频率为60M。   

ADC选择时钟源的API是`CLK_SetPeriClockSrc(uint16_t u16Src)`。说实话，刚看见这个函数名字的时候我还以为这个函数是通用的外设时钟源配置函数，直到我看见函数上面的注释：peripheral for ADC/DAC/TRNG，~~害得我找半天ADC选择时钟源的函数~~。   
u16Src可以输入的参数如下：
``` c

/**
 * @defgroup CLK_PERIPH_Sel CLK Peripheral Clock Selection
 * @note    ADC,I2S,DAC,TRNG
 * @{
 */
/*  PCLK2 is used for ADC clock, PCLK3 is used for I2S clock, PCLK4 is used for DAC/TRNG clock */
#define CLK_PERIPHCLK_PCLK              (0x0000U)
#define CLK_PERIPHCLK_PLLP              (0x0008U)
#define CLK_PERIPHCLK_PLLQ              (0x0009U)
#define CLK_PERIPHCLK_PLLR              (0x000AU)
#define CLK_PERIPHCLK_PLLXP             (0x000BU)
#define CLK_PERIPHCLK_PLLXQ             (0x000CU)
#define CLK_PERIPHCLK_PLLXR             (0x000DU)

```
其中CLK_PERIPHCLK_PCLK就是上面的第一种配置，后面的就是第二种配置，PLL依旧指代MPLL，PLLX指代UPLL。   
如果时钟源选择第一种的话，可以不使用`CLK_SetPeriClockSrc(uint16_t u16Src)`来配置时钟源，因为ADC的默认时钟源就是PCLK2和PCLK4，只需将PCLK2和PCLK4配置到正确的范围即可。   
## USB时钟
![](https://blog.zxcli.top/static/img/cdd5610692e1b5b8ab9a7578e41ea150.clipboard-2025-09-17.png)
USBFS需要的时钟是48M，设置时钟源的API是`CLK_SetUSBClockSrc(uint8_t u8Src)`，u8Src可以输入的参数如下：
```c
/**
 * @defgroup CLK_USBCLK_Sel CLK USB Clock Selection
 * @{
 */
#define CLK_USBCLK_SYSCLK_DIV2          (0x02U << CMU_USBCKCFGR_USBCKS_POS)
#define CLK_USBCLK_SYSCLK_DIV3          (0x03U << CMU_USBCKCFGR_USBCKS_POS)
#define CLK_USBCLK_SYSCLK_DIV4          (0x04U << CMU_USBCKCFGR_USBCKS_POS)
#define CLK_USBCLK_PLLP                 (0x08U << CMU_USBCKCFGR_USBCKS_POS)
#define CLK_USBCLK_PLLQ                 (0x09U << CMU_USBCKCFGR_USBCKS_POS)
#define CLK_USBCLK_PLLR                 (0x0AU << CMU_USBCKCFGR_USBCKS_POS)
#define CLK_USBCLK_PLLXP                (0x0BU << CMU_USBCKCFGR_USBCKS_POS)
#define CLK_USBCLK_PLLXQ                (0x0CU << CMU_USBCKCFGR_USBCKS_POS)
#define CLK_USBCLK_PLLXR                (0x0DU << CMU_USBCKCFGR_USBCKS_POS)

```
PLL依旧指代MPLL，PLLX指代UPLL。为了让MCU跑在最高的频率，一般使用UPLL的时钟作为USB的时钟源，所以要在一开始就把UPLL初始化好，~~这也是写这篇文章的目的~~。   
## 其余外设
剩下还有I2S和CAN的时钟源配置有点特殊，这俩我用的比较少，等以后用到了再回来补充吧。
## 开启外设时钟
上面扯了一大堆，都是在配置外设的时钟源，要想外设真正跑起来，还需要开启外设的时钟。对应的API是
``` c
FCG_Fcg0PeriphClockCmd(uint32_t u32Fcg0Periph, en_functional_state_t enNewState)  
FCG_Fcg1PeriphClockCmd(uint32_t u32Fcg1Periph, en_functional_state_t enNewState)   
FCG_Fcg2PeriphClockCmd(uint32_t u32Fcg2Periph, en_functional_state_t enNewState)   
FCG_Fcg3PeriphClockCmd(uint32_t u32Fcg3Periph, en_functional_state_t enNewState)
```
其中u32Fcg0Periph，u32Fcg1Periph，u32Fcg2Periph，u32Fcg3Periph能输入的参数如下：


```c
/**
 * @defgroup FCG_Global_Macros FCG Global Macros
 * @{
 */
/**
 * @defgroup FCG_FCG0_Peripheral FCG FCG0 peripheral
 * @{
 */
#define FCG0_PERIPH_SRAMH               (PWC_FCG0_SRAMH)
#define FCG0_PERIPH_SRAM12              (PWC_FCG0_SRAM12)
#define FCG0_PERIPH_SRAM3               (PWC_FCG0_SRAM3)
#define FCG0_PERIPH_SRAMRET             (PWC_FCG0_SRAMRET)
#define FCG0_PERIPH_DMA1                (PWC_FCG0_DMA1)
#define FCG0_PERIPH_DMA2                (PWC_FCG0_DMA2)
#define FCG0_PERIPH_FCM                 (PWC_FCG0_FCM)
#define FCG0_PERIPH_AOS                 (PWC_FCG0_AOS)
#define FCG0_PERIPH_AES                 (PWC_FCG0_AES)
#define FCG0_PERIPH_HASH                (PWC_FCG0_HASH)
#define FCG0_PERIPH_TRNG                (PWC_FCG0_TRNG)
#define FCG0_PERIPH_CRC                 (PWC_FCG0_CRC)
#define FCG0_PERIPH_DCU1                (PWC_FCG0_DCU1)
#define FCG0_PERIPH_DCU2                (PWC_FCG0_DCU2)
#define FCG0_PERIPH_DCU3                (PWC_FCG0_DCU3)
#define FCG0_PERIPH_DCU4                (PWC_FCG0_DCU4)
#define FCG0_PERIPH_KEY                 (PWC_FCG0_KEY)
/**
 * @}
 */

/**
 * @defgroup FCG_FCG1_Peripheral FCG FCG1 peripheral
 * @{
 */
#define FCG1_PERIPH_CAN                 (PWC_FCG1_CAN)
#define FCG1_PERIPH_QSPI                (PWC_FCG1_QSPI)
#define FCG1_PERIPH_I2C1                (PWC_FCG1_I2C1)
#define FCG1_PERIPH_I2C2                (PWC_FCG1_I2C2)
#define FCG1_PERIPH_I2C3                (PWC_FCG1_I2C3)
#define FCG1_PERIPH_USBFS               (PWC_FCG1_USBFS)
#define FCG1_PERIPH_SDIOC1              (PWC_FCG1_SDIOC1)
#define FCG1_PERIPH_SDIOC2              (PWC_FCG1_SDIOC2)
#define FCG1_PERIPH_I2S1                (PWC_FCG1_I2S1)
#define FCG1_PERIPH_I2S2                (PWC_FCG1_I2S2)
#define FCG1_PERIPH_I2S3                (PWC_FCG1_I2S3)
#define FCG1_PERIPH_I2S4                (PWC_FCG1_I2S4)
#define FCG1_PERIPH_SPI1                (PWC_FCG1_SPI1)
#define FCG1_PERIPH_SPI2                (PWC_FCG1_SPI2)
#define FCG1_PERIPH_SPI3                (PWC_FCG1_SPI3)
#define FCG1_PERIPH_SPI4                (PWC_FCG1_SPI4)
#define FCG1_PERIPH_USART1              (PWC_FCG1_USART1)
#define FCG1_PERIPH_USART2              (PWC_FCG1_USART2)
#define FCG1_PERIPH_USART3              (PWC_FCG1_USART3)
#define FCG1_PERIPH_USART4              (PWC_FCG1_USART4)
/**
 * @}
 */

/**
 * @defgroup FCG_FCG2_Peripheral FCG FCG2 peripheral
 * @{
 */
#define FCG2_PERIPH_TMR0_1              (PWC_FCG2_TIMER0_1)
#define FCG2_PERIPH_TMR0_2              (PWC_FCG2_TIMER0_2)
#define FCG2_PERIPH_TMRA_1              (PWC_FCG2_TIMERA_1)
#define FCG2_PERIPH_TMRA_2              (PWC_FCG2_TIMERA_2)
#define FCG2_PERIPH_TMRA_3              (PWC_FCG2_TIMERA_3)
#define FCG2_PERIPH_TMRA_4              (PWC_FCG2_TIMERA_4)
#define FCG2_PERIPH_TMRA_5              (PWC_FCG2_TIMERA_5)
#define FCG2_PERIPH_TMRA_6              (PWC_FCG2_TIMERA_6)
#define FCG2_PERIPH_TMR4_1              (PWC_FCG2_TIMER4_1)
#define FCG2_PERIPH_TMR4_2              (PWC_FCG2_TIMER4_2)
#define FCG2_PERIPH_TMR4_3              (PWC_FCG2_TIMER4_3)
#define FCG2_PERIPH_EMB                 (PWC_FCG2_EMB)
#define FCG2_PERIPH_TMR6_1              (PWC_FCG2_TIMER6_1)
#define FCG2_PERIPH_TMR6_2              (PWC_FCG2_TIMER6_2)
#define FCG2_PERIPH_TMR6_3              (PWC_FCG2_TIMER6_3)
/**
 * @}
 */

/**
 * @defgroup FCG_FCG3_Peripheral FCG FCG3 peripheral
 * @{
 */
#define FCG3_PERIPH_ADC1                (PWC_FCG3_ADC1)
#define FCG3_PERIPH_ADC2                (PWC_FCG3_ADC2)
#define FCG3_PERIPH_CMP                 (PWC_FCG3_CMP)
#define FCG3_PERIPH_OTS                 (PWC_FCG3_OTS)
/**
 * @}
 */

/**
 * @defgroup FCG_FCGx_Peripheral_Mask FCG FCGx Peripheral Mask
 * @{
 */
#define FCG_FCG0_PERIPH_MASK            (0x8FF3C511UL)
#define FCG_FCG1_PERIPH_MASK            (0x0F0FFD79UL)
#define FCG_FCG2_PERIPH_MASK            (0x000787FFUL)
#define FCG_FCG3_PERIPH_MASK            (0x00001103UL)
/**
 * @}
 */
 
 /**
 * @}
 */
```
 
用法示例：
```c
/* 1. Enable ADC1 peripheral clock. */
FCG_Fcg3PeriphClockCmd(FCG3_PERIPH_ADC1, ENABLE);
```

:::info{title="XHCode生成代码的BUG"}
在XHCode V1.10.0中，为HC32F334生成的配置HRPWM的代码中开启外设时钟函数的位置有问题。   
具体情况为：在开启HRPWM时钟前就对微边沿定位的步长进行校准，最后会导致代码卡在校准超时失败的函数中。   
解决方法：将下面红框中的函数提前到校准函数之前
![](https://blog.zxcli.top/static/img/c2401f2f3002c022d1f7bb1b7112902d.clipboard-2025-09-17.png)
:::

HC32F460外设时钟源设置

![](/static/img/d97fd6a404b32cb8338b3001a2d25745.clipboard-2025-09-08.png)   
最近了解到了Letter Shell这个轻量级的命令行，看了一下官方给出的例程，可以移植到SEGGER RTT上，于是尝试了一下，记录一下过程。



## 下载Letter Shell
首先从GitHub上拉取Letter Shell的源码：https://github.com/NevermindZZT/letter-shell   
**建议将Github上的说明文档仔细看一遍再参考我下面的教程。**

## 下载SEGGER RTT
然后从JLink的安装目录下将SEGGER RTT的库文件拷贝出来，库文件一般在**Jlink安装目录/Samples/RTT**下面
![](/static/img/4b1fcf7d56e6c5a18562173b127519c6.RTTç®å½.webp)

## 移植SEGGER RTT
将RTT的库文件拷贝到你的工程里面，设置好文件路径，在文件中包含RTT的头文件**SEGGER_RTT.h** ，然后在main函数中调用SEGGER_RTT_printf()，随意打印一些东西，编译下载运行。插上Jlink，用J-Link RTT Viewer连接单片机，如果能够打印出东西，说明RTT已经移植成功。     
![](/static/img/e4d408d88c8c590a28d0a41b9b6eb898.RTTæµè¯.webp)  
运行结果如下：   
![](/static/img/369826a1a25219a96d4856a8e3a3ea25.RTTæµè¯ç»æ.webp) 

## 移植Letter Shell
同样将Letter Shell的库文件拷贝到你的工程中，并设置好文件路径。   

### 新建shell_port.h和.c文件
**shell_port.h**和.c文件用于shell和外部接口的对接，包括读写函数和初始化shell的函数。这里是将shell对接到了RTT的通道0上面。我的这两个文件如下：

shell_port.h:
```c
    /**
    * @file shell_port.h
    * @author Letter (NevermindZZT@gmail.com)
    * @brief 
    * @version 0.1
    * @date 2019-02-22
    * 
    * @copyright (c) 2019 Letter
    * 
    */

    /*
        加在.rodata :
       _shell_command_start = .;
        KEEP (*(shellCommand))
        _shell_command_end = .;
    */

    #ifndef __SHELL_PORT_H__
    #define __SHELL_PORT_H__


    #include "shell.h"
    #include <stdbool.h>

    extern Shell rttShell;

    void rttShellInit(void);
    short rttShellRead(char *data, unsigned short len);
    short rttShellWrite(char *data, unsigned short len);
    #endif
```


shell_port.c:
```c
    /**
    * @file shell_port.c
    * @author Letter (NevermindZZT@gmail.com)
    * @brief 
    * @version 0.1
    * @date 2019-02-22
    * 
    * @copyright (c) 2019 Letter
    * 
    */

    #include "shell.h"
    #include "shell_port.h"
    #include "SEGGER_RTT.h"

    Shell rttShell;
    char rttShellBuffer[512];

    /**
    * @brief rtt shell写
    *
    * @param data 数据
    * @param len 数据长度
    *
    * @return short 实际写入的数据长度
    */
    short rttShellWrite(char *data, unsigned short len)
    {
        static int blocked = 0;
        unsigned int time  = HAL_GetTick();
        short avail        = 0;
        short write        = 0;
        short wrote        = 0;
        do {
            avail = SEGGER_RTT_GetAvailWriteSpace(0);
            if (avail <= 0) {
                if (blocked > 10) {
                    return 0;
                }
                HAL_Delay(1);
                blocked++;
            } else {
                blocked = 0;
                write   = avail >= len ? len : avail;
                SEGGER_RTT_Write(0, data, write);
                data += write;
                len -= write;
                wrote += write;
            }
        } while (len > 0 && HAL_GetTick() - time < 10);
        return wrote;
    }

    /**
    * @brief rtt shell读
    *
    * @param data 数据
    * @param len 数据长度
    *
    * @return short 实际读取的数据长度
    */
    short rttShellRead(char *data, unsigned short len)
    {
        return SEGGER_RTT_Read(0, data, len);
    }

    /**
    * @brief 用户shell初始化
    *
    */
    void rttShellInit(void)
    {
        rttShell.write = rttShellWrite;
        rttShell.read  = rttShellRead;
        shellInit(&rttShell, rttShellBuffer, 512);
    }

```  
### 修改shell_cfg.h
然后根据需要修改**shell_cfg.h**中的配置，我的配置如下：   
```c
/**
 * @file shell_cfg.h
 * @author Letter (nevermindzzt@gmail.com)
 * @brief shell config
 * @version 3.0.0
 * @date 2019-12-31
 * 
 * @copyright (c) 2019 Letter
 * 
 */

#include "main.h"

#ifndef __SHELL_CFG_H__
#define __SHELL_CFG_H__

#ifdef SHELL_CFG_USER
#include SHELL_CFG_USER
#endif

#ifndef SHELL_TASK_WHILE
/**
 * @brief 是否使用默认shell任务while循环
 *        使能此宏，则`shellTask()`函数会一直循环读取输入，一般使用操作系统建立shell
 *        任务时使能此宏，关闭此宏的情况下，一般适用于无操作系统，在主循环中调用`shellTask()`
 */
#define     SHELL_TASK_WHILE            0
#endif /** SHELL_TASK_WHILE */

#ifndef SHELL_USING_CMD_EXPORT
/**
 * @brief 是否使用命令导出方式
 *        使能此宏后，可以使用`SHELL_EXPORT_CMD()`等导出命令
 *        定义shell命令，关闭此宏的情况下，需要使用命令表的方式
 */
#define     SHELL_USING_CMD_EXPORT      1
#endif /** SHELL_USING_CMD_EXPORT */

#ifndef SHELL_USING_COMPANION
/**
 * @brief 是否使用shell伴生对象
 *        一些扩展的组件(文件系统支持，日志工具等)需要使用伴生对象
 */
#define     SHELL_USING_COMPANION       0
#endif /** SHELL_USING_COMPANION */

#ifndef SHELL_SUPPORT_END_LINE
/**
 * @brief 支持shell尾行模式
 */
#define     SHELL_SUPPORT_END_LINE      0
#endif /** SHELL_SUPPORT_END_LINE */

#ifndef SHELL_HELP_LIST_USER
/**
 * @brief 是否在输出命令列表中列出用户
 */
#define     SHELL_HELP_LIST_USER        0
#endif /** SHELL_HELP_LIST_USER */

#ifndef SHELL_HELP_LIST_VAR
/**
 * @brief 是否在输出命令列表中列出变量
 */
#define     SHELL_HELP_LIST_VAR         0
#endif /** SHELL_HELP_LIST_VAR */

#ifndef SHELL_HELP_LIST_KEY
/**
 * @brief 是否在输出命令列表中列出按键
 */
#define     SHELL_HELP_LIST_KEY         0
#endif /** SHELL_HELP_LIST_KEY */

#ifndef SHELL_HELP_SHOW_PERMISSION
/**
 * @brief 是否在输出命令列表中展示命令权限
 */
#define     SHELL_HELP_SHOW_PERMISSION  1
#endif /** SHELL_HELP_SHOW_PERMISSION */

#ifndef SHELL_ENTER_LF
/**
 * @brief 使用LF作为命令行回车触发
 *        可以和SHELL_ENTER_CR同时开启
 */
#define     SHELL_ENTER_LF              1
#endif /** SHELL_ENTER_LF */

#ifndef SHELL_ENTER_CR
/**
 * @brief 使用CR作为命令行回车触发
 *        可以和SHELL_ENTER_LF同时开启
 */
#define     SHELL_ENTER_CR              1
#endif /** SHELL_ENTER_CR */

#ifndef SHELL_ENTER_CRLF
/**
 * @brief 使用CRLF作为命令行回车触发
 *        不可以和SHELL_ENTER_LF或SHELL_ENTER_CR同时开启
 */
#define     SHELL_ENTER_CRLF            0
#endif /** SHELL_ENTER_CRLF */

#ifndef SHELL_EXEC_UNDEF_FUNC
/**
 * @brief 使用执行未导出函数的功能
 *        启用后，可以通过`exec [addr] [args]`直接执行对应地址的函数
 * @attention 如果地址错误，可能会直接引起程序崩溃
 */
#define     SHELL_EXEC_UNDEF_FUNC       0
#endif /** SHELL_EXEC_UNDEF_FUNC */

#ifndef SHELL_PARAMETER_MAX_NUMBER
/**
 * @brief shell命令参数最大数量
 *        包含命令名在内，超过16个参数并且使用了参数自动转换的情况下，需要修改源码
 */
#define     SHELL_PARAMETER_MAX_NUMBER  8
#endif /** SHELL_PARAMETER_MAX_NUMBER */

#ifndef SHELL_HISTORY_MAX_NUMBER
/**
 * @brief 历史命令记录数量
 */
#define     SHELL_HISTORY_MAX_NUMBER    5
#endif /** SHELL_HISTORY_MAX_NUMBER */

#ifndef SHELL_DOUBLE_CLICK_TIME
/**
 * @brief 双击间隔(ms)
 *        使能宏`SHELL_LONG_HELP`后此宏生效，定义双击tab补全help的时间间隔
 */
#define     SHELL_DOUBLE_CLICK_TIME     200
#endif /** SHELL_DOUBLE_CLICK_TIME */

#ifndef SHELL_QUICK_HELP
/**
 * @brief 快速帮助
 *        作用于双击tab的场景，当使能此宏时，双击tab不会对命令进行help补全，而是直接显示对应命令的帮助信息
 */
#define     SHELL_QUICK_HELP            1
#endif /** SHELL_QUICK_HELP */

#ifndef SHELL_KEEP_RETURN_VALUE
/**
 * @brief 保存命令返回值
 *        开启后会默认定义一个`RETVAL`变量，会保存上一次命令执行的返回值，可以在随后的命令中进行调用
 *        如果命令的`SHELL_CMD_DISABLE_RETURN`标志被设置，则该命令不会更新`RETVAL`
 */
#define     SHELL_KEEP_RETURN_VALUE     0
#endif /** SHELL_KEEP_RETURN_VALUE */

#ifndef SHELL_MAX_NUMBER
/**
 * @brief 管理的最大shell数量
 */
#define     SHELL_MAX_NUMBER            5
#endif /** SHELL_MAX_NUMBER */

#ifndef SHELL_PRINT_BUFFER
/**
 * @brief shell格式化输出的缓冲大小
 *        为0时不使用shell格式化输出
 */
#define     SHELL_PRINT_BUFFER          128
#endif /** SHELL_PRINT_BUFFER */

#ifndef SHELL_SCAN_BUFFER
/**
 * @brief shell格式化输入的缓冲大小
 *        为0时不使用shell格式化输入
 * @note shell格式化输入会阻塞shellTask, 仅适用于在有操作系统的情况下使用
 */
#define     SHELL_SCAN_BUFFER          0
#endif /** SHELL_SCAN_BUFFER */

#ifndef SHELL_GET_TICK
/**
 * @brief 获取系统时间(ms)
 *        定义此宏为获取系统Tick，如`HAL_GetTick()`
 * @note 此宏不定义时无法使用双击tab补全命令help，无法使用shell超时锁定
 */
#define     SHELL_GET_TICK()            HAL_GetTick()
#endif /** SHELL_GET_TICK */

#ifndef SHELL_USING_LOCK
/**
 * @brief 使用锁
 * @note 使用shell锁时，需要对加锁和解锁进行实现
 */
#define     SHELL_USING_LOCK            0
#endif /** SHELL_USING_LOCK */

#ifndef SHELL_MALLOC
/**
 * @brief shell内存分配
 *        shell本身不需要此接口，若使用shell伴生对象，需要进行定义
 */
#define     SHELL_MALLOC(size)          0
#endif /** SHELL_MALLOC */

#ifndef SHELL_FREE
/**
 * @brief shell内存释放
 *        shell本身不需要此接口，若使用shell伴生对象，需要进行定义
 */
#define     SHELL_FREE(obj)             0
#endif /** SHELL_FREE */

#ifndef SHELL_SHOW_INFO
/**
 * @brief 是否显示shell信息
 */
#define     SHELL_SHOW_INFO             1
#endif /** SHELL_SHOW_INFO */

#ifndef SHELL_CLS_WHEN_LOGIN
/**
 * @brief 是否在登录后清除命令行
 */
#define     SHELL_CLS_WHEN_LOGIN        1
#endif /** SHELL_CLS_WHEN_LOGIN */

#ifndef SHELL_DEFAULT_USER
/**
 * @brief shell默认用户
 */
#define     SHELL_DEFAULT_USER          "letter-shell"
#endif /** SHELL_DEFAULT_USER */

#ifndef SHELL_DEFAULT_USER_PASSWORD
/**
 * @brief shell默认用户密码
 *        若默认用户不需要密码，设为""
 */
#define     SHELL_DEFAULT_USER_PASSWORD ""
#endif /** SHELL_DEFAULT_USER_PASSWORD */

#ifndef SHELL_LOCK_TIMEOUT
/**
 * @brief shell自动锁定超时
 *        shell当前用户密码有效的时候生效，超时后会自动重新锁定shell
 *        设置为0时关闭自动锁定功能，时间单位为`SHELL_GET_TICK()`单位
 * @note 使用超时锁定必须保证`SHELL_GET_TICK()`有效
 */
#define     SHELL_LOCK_TIMEOUT          0 * 60 * 1000
#endif /** SHELL_LOCK_TIMEOUT */

#ifndef SHELL_USING_FUNC_SIGNATURE
/**
 * @brief 使用函数签名
 *        使能后，可以在声明命令时，指定函数的签名，shell 会根据函数签名进行参数转换，
 *        而不是自动判断参数的类型，如果参数和函数签名不匹配，会停止执行命令
 */
#define     SHELL_USING_FUNC_SIGNATURE  0
#endif /** SHELL_USING_FUNC_SIGNATURE */

#ifndef SHELL_SUPPORT_ARRAY_PARAM
/**
 * @brief 支持数组参数
 *        使能后，可以在命令中使用数组参数，如`cmd [1,2,3]`
 *        需要使能 `SHELL_USING_FUNC_SIGNATURE` 宏，并且配置 `SHELL_MALLOC`, `SHELL_FREE`
 */
#define     SHELL_SUPPORT_ARRAY_PARAM   0
#endif /** SHELL_SUPPORT_ARRAY_PARAM */

#endif

```  
### 调用shell   
首先初始化shell,直接调用刚才在shell_port.c中实现的函数：

```c
rttShellInit(); // 初始化RTT Shell
```
接下来就是调用shell任务。官方说明文档给出了调用shell任务的几种方式：
![](/static/img/abe60fc0ec63e290650a1c6b1befd272.è°ç¨shellä»»å¡å®æ¹è¯´æ.webp)

因为我这边是裸机开发，所以我选择了调用**shellHandler**的方式，然后在whlie(1)中简单实现一个定时调度的状态机，给shellHandler分配了一个任务：   
![](/static/img/9161d0715e77e7fe1c14e435654c1a0e.shellHandlerä»»å¡.webp)

### 注意事项
如果在编译的时候，出现类似的错误：   
![](/static/img/556d8736c7bb3c15e3d280035788eb8f.æ¥éä¿¡æ¯.webp)
参考官方文档的说明，添加对应的参数：
![](/static/img/fa48db60ea52427c2904d6a6da4aa447.å®æ¹å»ºè®®.webp) 
因为我使用的是GCC编译器，所以在链接文件中添加如下内容：
![](/static/img/013565bd355624796cb3dcfaf9552580.è§£å³æ¹æ³.webp)
解决完上面的问题之后，编译下载，就可以在RTT Viewer中看到shell的界面了：
![](/static/img/3864523166114028553a340a829ef770.Letter-Shellçé¢.webp)
## 将RTT对接到终端
为了方便使用，我们可以选择将RTT对接到终端，这样就可以直接在终端中使用shell。  
由于J-Link RTT Viewer中只能输入单个字符，不便于我们输入一长串指令，也不方便我们修改，所以对接到正经的终端中非常有必要。   
这里我使用了Letter Shell官方推荐的rtt转发telnet工具**Rtt2Telnet**：   
https://github.com/mcujackson/Rtt2Telnet   
设置好Rtt2Telnet的目标芯片和连接速度后，点击开启，就会在本地的6198端口上开启RTT转发，使用支持telnet连接的终端即可连接到RTT。我这里使用的是MobaXterm，配置成功的结果如下：   
![](/static/img/940cd4b60b99a0f9befe1e207bad4a2a.mobaxtermè¿æ¥ç»æ.webp)

将Letter Shell对接到SEGGER RTT上

![](/static/img/a54c5795c6b84d0804ae670993d16313.clipboard-2025-09-08.png)

在进行C2000开发时，能选择的IDE很少，只有TI自家的Code Composer Studio(CCS)，是基于Eclipse魔改过来的(CCS20开始是基于theia魔改的了)。新人在一开始上手使用CCS的时候可能会一头雾水，并且CCS的代码补全功能非常鸡肋，所以在这里介绍一种在~~宇宙最强编辑器~~VSCODE上编辑并编译C2000工程的方法。 



## 从CCS中导入C2000工程  
在将工程导入VSCODE之前，我们需要先要将工程导入CCS中。  
### 为什么要先使用CCS导入工程  
CCS编译工程靠的是makefile加gmake的方式。gmake是TI自己弄的编译器。在makefile文件中包括了编译C2000工程所需要的所有信息，包括编译器路径、编译器参数、编译顺序等等。每个子文件夹还有自己的subdir_rules.mk和subdir_vars.mk文件，用来告诉编译器如何编译子文件夹中的文件。在makefile和各种.mk文件中，编译器所需要知道的文件路径大部分都是以相对路径表示的，但是像项目路径，编译器路径，C2000专用的头文件路径等，都是以绝对路径表示的。在将例程或者别人的工程导入CCS之前，这些绝对路径都是错误的。而导入CCS后，CCS会自动修改这些路径，使得工程可以在CCS中正常编译。  
第二个原因则是像C2000ware中的例程和空工程中是不包含driverlib驱动库文件的，使用CCS导入后，CCS会将这些文件添加到工程中，并生成对应的makefile文件。  
### 如何导入工程  
1. 打开CCS，点击菜单栏中的Project -> Import CCS Project，选择要导入的工程文件夹。
![](/static/img/133ee052f5d5d8f6525c78aa836c7572.å¯¼å¥.png)
2. 选择文件夹  
这里导入280049的空工程
![](/static/img/80ce06ee22e71ac43d9575750ffce04b.å¯¼å¥ç©ºå·¥ç¨.png)
注意事项：    
在导入的时候记得勾上下面两个选项。
![](/static/img/b1afb2cb8d4e6b5af791f6939b6cabaf.æ³¨æå¾é.png)
3. 选择C语言工程  
我们开发的时候一般使用C语言，所以选择C语言工程。勾选第二个工程选项。然后点击finish完成导入。  
![](/static/img/8160f3d04de894c2bd49d53d3c97c042.å¯¼å¥cå·¥ç¨.png)
完成导入后，CCS中就有我们的工程了，可以对比一下，CCS导入后比原文件夹多了不少东西。  
![](/static/img/9e7f808ff3ea681bb1bc3287f149efbf.å¯¹æ¯.png)
### 在CCS中修改工程   
在导入工程后，我们需要在CCS中修改工程，比如重命名工程，新增文件夹，设置代码烧录位置等等。  
但是要记住，以上的操作都要在CCS中进行，因为CCS在每次编译时都会会自动修改makefile文件，使得工程可以在CCS中正常编译。如果你在文件资源管理器里面直接修改文件名或文件夹名，makefile文件中的路径是不会自动更新的，编译器找不到文件，就会报错。  
在修改完工程后，可以点击菜单栏上面的小锤子编译一下，看看有没有报错。
## 将工程导入VSCODE  
在导入工程的文件夹的空白处右键，选择在VSCODE中打开。
![](/static/img/86dcb3fc1a206647bb15940eae9ad08c.å³é®æå¼.png) 
![](/static/img/1868f56ac60761ed2948b9b6e7f10bc6.vscode.png)
在VSCODE中的操作分为两步，一个是能让VSCODE正常跳转和补全，另一个是能在VSCODE的终端里面正常编译。  
### 让VSCODE正常跳转和补全  
在工程根目录下新建.vscode文件夹，在.vscode文件夹下新建c_cpp_properties.json文件，文件内容如下：
```
{
    "configurations": [
        {
            "name": "TI C2000",
            "includePath": [
                "${workspaceFolder}/**",
                "${workspaceFolder}/CPU1_FLASH/syscfg",
                "${workspaceFolder}/device/",
                "${workspaceFolder}/device/driverlib",
                "${workspaceFolder}/device/driverlib/inc",
                "C:/ti/ccstheia150/ccs/tools/compiler/ti-cgt-c2000_22.6.1A23259/include"
            ],
            "defines": [
                "UNICODE",
                "_UNICODE",
                "__TMS320C28XX__",
                "__interrupt=" // 定义为空，消除红色波浪线
            ],
            "cStandard": "c11",
            "compilerPath": "C:/ti/ccstheia150/ccs/tools/compiler/ti-cgt-c2000_22.6.1A23259/bin/cl2000.exe",
            "intelliSenseMode": "clang-x64"
        }
    ],
    "version": 4
}
``` 

第6行到第21行是我们要根据工程修改的地方，其余的都是文件框架，直接复制就行。  
"includePath"中填写的是编译器搜索头文件的路径。${workspaceFolder}表示工程根目录，然后依次添加你自己新添加的包括.h文件的文件夹路径(我这里没有新建.h文件以及文件夹，所以只有第6行)。  
第7行的**CPU1_FLASH/syscfg**是为了包含syscfg生成的board.h文件。如果你设置的是烧录到RAM，那路径应该改成**CPU1_RAM/syscfg**。双核CPU同理。
下面的三行是包括的driverlib文件夹的路径。  
includePath的最后一行的路径是C2000的C标准函数库头文件路径。这个要到CCS的安装目录里面找。或者你可以在工程文件里面包含一下标准库的头文件的路径，然后跳转进去，CCS的标题就会变成该头文件的路径，就像下面这样：   
![](/static/img/c03d844c251275aaf9f293d9f50ea80f.std-path.png)
"defines"中填写的是编译器预定义的宏。这里定义了三个宏，第一个是UNICODE，第二个是_UNICODE，第三个是__TMS320C28XX__。这三个宏在driverlib中会使用到。  
"compilerPath"是编译器的路径，添加这个是为了防止VSCODE无法跳转某些标准库的头文件，实际上并没有什么用。这个要根据你的安装路径来修改。  
"intelliSenseMode"是智能提示模式，这里选择clang-x64。   
将c_cpp_properties.json文件修改好之后，应该就能正常跳转和补全了，而且不会有红色波浪线报错。    
### 让VSCODE正常编译   
#### 将gmake添加到环境变量中
要在VSCODE中编译C2000的工程，本质上还是调用CCS的编译器，也就是gmake。所以我们首先要把gmake添加到环境变量中，然后才在VSCODE中调用gmake。  
gmake的安装路径也在CCS的安装目录下，路径为：
![](/static/img/58afaaca6364ab0b0fec98ed1dc6ee65.gmkeè·¯å¾.png)   
然后添加到环境变量中：
![](/static/img/58d1731d0e01a13dc5c842e737055f39.ç¯å¢åé.png)
然后重启电脑，在VSCODE中打开终端，输入`gmake -v`，如果出现gmake的版本信息，说明添加成功。
![](/static/img/2c424edb122f0c391579dbe4a7c5e16f.gmakeéªè¯.png)
#### 创建编译脚本
接下来就是创建一个调用gmake的编译脚本，在工程根目录新建一个build.ps1文件，文件内容如下：

```
cd ./CPU1_FLASH
gmake -k -j32 all -O
cd ..
```
这个脚本是在powershell中执行上述三条代码。   
其中`cd ./CPU1_FLASH`是进入CPU1_FLASH文件夹，因为makefile文件在这个目录里面，如果你设置的是烧录到RAM，就改成`cd ./CPU1_RAM`(双核的我暂时还没试过)。   
`gmake -k -j32 all -O`是调用gmake编译工程。   
`cd ..`是返回上一级目录。  
添加完文件后在VSCODE中打开终端，输入`.\build.ps1`，如果出现编译信息，说明脚本创建成功。
![](/static/img/947c0a54ca137a9b70ff462fc76e89a3.æ§è¡ç¼è¯.png)
如果出现报错，查看报错信息，是否存在语法错误；如果报错是找不到变量或函数，而且变量或函数正好在你新添加的文件夹里面，CCS编译设置中也有包含这个文件夹，可以在CCS中先编译一遍，把旧的makefile文件路径更新一下，就可以在VSCODE中编译了。  
#### 创建清理脚本   
和上面的编译脚本类似，在工程根目录新建一个clean.ps1文件，文件内容如下：

```
cd ./CPU1_FLASH
gmake clean
cd ..
```
### 添加工作区  
在VSCODE中打开你的工程，然后在菜单栏上点击文件->将工作区另存为，将工作区保存到你的工程根目录。
![](/static/img/3439d98048aa1288a49b8557719ed808.ä¿å­å·¥ä½åº.png)
以后再要打开工程，直接双击打开这个.workspace后缀的工作区文件即可。