BSP本地接口介绍

1. I2C 接口及功能介绍¶

1.1. I2C 概述¶

I2C (Inter-Integrated Circuit) 协议使用双向串行数据线 (SDA) 和串行时钟线 (SCL)，在主控制器和从机之间进行同步、半双工数据传输。Linux 将 I2C 控制器抽象成 i2c_adapter，I2C driver 会根据设备树中 I2C 节点数量生成相应的 I2C 设备节点，目前 dev/ 路径下有 i2c-0~6 共 7 个 I2C 设备节点，即有0~6通道可供使用。I2C 设备节点支持配置速率，可通过 sys/class/mstar/i2cx/speed 节点读写，最高速率 1500 KHz。

使用 I2C driver 之前，需要先将相关 config CONFIG_SSTAR_I2C 添加到vendor/sigmastar/alkaid/kernel/common/arch/arm64/configs/pioneer5_android_gki.fragment 文件中。若要将某个引脚复用成 I2C 功能，需要先在vendor/sigmastar/alkaid/kernel/common/dtbo/pioneer5-ssxxxxx-xxxx-x.dts 文件（文件名与板子型号匹配）配置，重复配置会引起引脚复用失败，配置前需要将冲突注释掉，I2C PADMUX 参考示例：

<PAD_KEY5 PINMUX_FOR_12C4_MODE_1 MDRV_PUSE_12C4_SDA>
<PAD_KEY6 PINMUX_FOR_12C4_MODE_1 MDRV PUSE_12C4_SCL>

以 I2C0为例，在设备树中的节点配置如下：

i2c0: i2c@1f222800 {
    compatible = "sstar,i2c";
    reg = <0x1F2228000 x200>;
    #address-cells = <1>;
    #size-cells = <0>;
    interrupts = <GIC_SPI INT_IRQ_MIIC IRQ_TYPE_LEVEL_HIGH>;
    clocks = <&CLK_miic0>;
    i2c-group = <0>;
    i2c-en-dma = <1>;
    i2c-speed = <400000>;
    i2c-t-hd = <0>;
    i2c-t-su = <0>;
    i2c-t-start = <0>;
    i2c-t-stop = <0>;
    i2c-push-pull = <1>;
    i2c-oen-cnt = <1>;
    status = "ok";
};

I2C 驱动中支持配置的属性如下表：

属性	描述	备注
compatible	用于匹配驱动进行驱动注册，需与代码中一致	禁止修改
reg	用于指定 I2C 寄存器 bank 地址	不需要修改
interrupts	用于指定使用的硬件中断号及属性	不需要修改
clocks	用于指定 I2C 使用的时钟源	不需要修改
i2c-group	用于指定 I2C 外设编号序列号	不需要修改
i2c-en-dma	用于选择是否使用 DMA 模式	可根据需要修改
i2c-speed	用于选择 I2C speed，直接填写实际值	可根据需要修改
i2c-t-hd	用于设定起始信号建立时间	可根据需要修改
i2c-t-su	用于设定结束信号保持时间	可根据需要修改
i2c-t-start	用于设定其实信号保持时间	可根据需要修改
i2c-t-stop	用于设定结束信号建立时间	可根据需要修改
i2c-push-pull	用于打开推挽输出方式	可根据需要修改
i2c-oen-cnt	用于优化推免输出的上升沿波形	可根据需要修改
status	用于选择是否使能 I2C 驱动	可根据需要修改

I2C 读写支持 DMA / 非 DMA 两种模式，可在设备树节点中修改 i2c-en-dma 属性值来选择模式。对于每次支持的传输字节数，非 DMA mode 不做限制，理论上不应该超过 u32 即 0xFFFFFFFF。DMA mode 因 DMA buffer 长度限制，每次通信允许的最大限度为 4096 字节，建议传输字节数较大的时候打开 DMA mode，减少 CPU loading。

I2C 设备读写是通过调用 I2C driver 的 ioctl 实现的，应用层操作 I2C 是以数据包形式通信，数据包对应的结构体是 i2c_rdwr_ioctl_data，其中第一个结构体成员要发送数据包的指针，包含了通信所需的从机地址、读写 flag（flag = 1 为读数据，flag = 0 为写数据）、数据包长度和所指向的地址，第二个结构体成员是数据包的个数。一次 ioctl 下发信息中可以包含多个 struct i2c_msg 信息。

// i2c-dev.h
#define I2C_RDWR 0x0707

/* This is the structure as used in the I2C_RDWR ioctl call */
struct i2c_rdwr_ioctl_data {
    struct i2c_msg *msgs;    /* pointers to i2c_msgs */
    __u32 nmsgs;            /* number of i2c_msgs */
};

// i2c.h
 /*
 * I2C Message - used for pure i2c transaction, also from /dev interface
 */
struct i2c_msg {
    __u16 addr;    /* slave address            */
    unsigned short flags;
#define I2C_M_TEN    0x10    /* we have a ten bit chip address    */
#define I2C_M_RD    0x01
#define I2C_M_NOSTART    0x4000
#define I2C_M_REV_DIR_ADDR    0x2000
#define I2C_M_IGNORE_NAK    0x1000
#define I2C_M_NO_RD_ACK        0x0800
    short len;        /* msg length                */
    char *buf;        /* pointer to msg data            */
};

1.2. I2C 接口说明¶

(1) int32_t sstar_i2c_init(uinit32_t i2c_num)¶

功能描述：I2C 初始化

参数：

i2c_num : I2C 通道号，通道号范围为 0 ~ 6

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(2) int32_t sstar_i2c_deinit(uinit32_t i2c_num)¶

功能描述：I2C 去初始化

参数：

i2c_num : I2C 通道号，通道号范围为 0 ~ 6

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(3) int32_t sstar_i2c_set_rate(uinit32_t i2c_num, uint32_t rate)¶

功能描述：I2C 设置通信速率

参数：

i2c_num : I2C 通道号，通道号范围为 0 ~ 6
rate : I2C 速率

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(4) int32_t sstar_i2c_get_rate(uinit32_t i2c_num, uint32_t* rate)¶

功能描述：I2C 获取通信速率

参数：

i2c_num : I2C 通道号，通道号范围为 0 ~ 6
rate : 获取到的 I2C 速率

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(5) int32_t sstar_i2c_write(uinit32_t i2c_num, uint32_t slave_addr, uint32_t reg_addr, uint32_t reg_count, unsigned char* buf, uint32_t length )¶

功能描述：I2C 写数据

参数：

i2c_num : I2C 通道号，通道号范围为 0 ~ 6
slave_addr : 从机地址
reg_addr : 从机寄存器地址，传入的是 reg_addr 地址，必须高位在前低位在后
reg_count : 从机寄存器地址长度
buf : 要写入的 buf 数据，传入的是 buf 地址
length : 要写入 buf 的长度

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(6) int32_t sstar_i2c_read(uinit32_t i2c_num, uint32_t slave_addr, uint32_t reg_addr, uint32_t reg_count, unsigned char* buf, uint32_t length )¶

功能描述：I2C 写数据

参数：

i2c_num : I2C 通道号，通道号范围为 0 ~ 6
slave_addr : 从机地址
reg_addr : 从机寄存器地址，传入的是 reg_addr 地址，必须高位在前低位在后
reg_count : 从机寄存器地址长度
buf : 要读取的 buf 数据，传入的是 buf 地址
length : 要读取 buf 的长度

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

1.3. I2C 接口使用示例¶

int32_t ret;
uinit32_t i2c_num = 4;
uinit32_t set_speed = 100000;
uinit32_t get_speed;
uint32_t slave_addr = 0x50;
unsigned char reg_addr[2] = {0x00, 0x01};
unsigned char tx[2] = {0x01, 0x02};
unsigned char rx[2] = {0};

// 初始化
ret = sstar_i2c_init(i2c_num);
// 设置 I2C-4 速率为 100KHz
ret = sstar_i2c_set_rate(i2c_num , set_speed);
// 获取 I2C-4 速率
ret = sstar_i2c_get_rate(i2c_num , &get_speed);
// I2C-4 发送 buf
ret = sstar_i2c_write(i2c_num, slave_addr, reg_addr, sizeof(reg_addr), tx, sizeof(tx));
// I2C-4 接收 buf
ret = sstar_i2c_read(i2c_num, slave_addr, reg_addr, sizeof(reg_addr), rx, sizeof(rx));

1.4. GPIO 模拟 I2C 功能说明¶

若遇到 I2C 设备节点不够用的情况，可以使用 Linux 原生的 i2c-gpio driver 模拟 I2C 协议，驱动位于 kernel/common/driver/i2c/busses/i2c-gpio.c，使用该驱动需要加上 config CONFIG_I2C_GPIO。该驱动的核心在于使用两个 GPIO 引脚模拟 I2C 总线时序，需要先将这两个引脚配置 GPIO PADMUX，例如使用 PAD_KEY3 和 PAD_KEY4 作为 GPIO 功能，PADMAX 配置如下：

<PAD_KEY3 PINMUX_FOR_GPIO_MODE MDRV_PUSE_NA>
<PAD_KEY4 PINMUX_FOR_GPIO_MODE MDRV_PUSE_NA>

参考 vendor/sigmastar/ bootloader/u-boot/doc/device-tree-bindings/i2c/i2c-gpio.txt 文档描述，在设备树中配置如下。建议别名从 i2c7 开始，即通道号从 7 开始。

aliases {
    ... ...
    i2c7 = &i2c_gpio;
};
... ...
i2c_gpio:@1 {
    #address-cells = <1>;
    #size-cells = <0>;

    compatible = "i2c-gpio";
    gpios = <&gpio 14 GPIO_ACTIVE_HIGH>,
            <&gpio 15 GPIO_ACTIVE_HIGH>,

    i2c-gpio,delay-us = <5>;
    i2c-gpio,timeout-ms = <10>;

    status = "ok";
    ... ...
}

i2c-gpio driver 中支持配置的属性如下表：

属性	描述	设定值	备注
compatible	用于匹配驱动进行驱动注册，需与代码中一致	i2c-gpio	禁止修改
i2c-gpio,delay-us	用于指定通信频率，分为三种情况：（1）如果 delay-us (us) 有设定值，频率(Hz) = 1000000 / 4 * delay；（2）如果设置了 i2c-gpio,scl-output-only 属性，频率则为10KHz；（3）如果都没有指定，默认100KHz		可根据需要修改
i2c-gpio,timeout-ms	用于指定延时时间，单位为 ms，如果不指定默认 100ms		可根据需要修改
i2c-gpio,sda-open-drain	如果指定了这个属性，表示其他驱动已经将 SDA 设置为开漏，本驱动不需要设置		可根据需要修改
i2c-gpio,scl-open-drain	如果指定了这个属性，表示其他驱动已经将 SDA 设置为开漏，本驱动不需要设置		可根据需要修改
i2c-gpio,scl-output-only	如果指定了这个属性，表示 SCL 引脚仅输出		可根据需要修改

因 i2c-gpio driver 匹配到相应的设备树节点后，也是注册到 I2C adaptor 上，和普通 I2C 驱动设备的使用方法一致。但通信速率在设备树节点中指定，不支持通过 sstar_i2c_set_rate 接口调配速率。

2. PWM 接口及功能介绍¶

2.1. PWM 概述¶

PWM （Pulse Width Modulation）模块通过改变占空比来改变输出的电流、电压，进而控制电机转速、液晶屏调光等。

PWM driver 相应的 config 为 CONFIG_SSTAR_PWM。若要将某个引脚复用成 PWM 功能，需要先在 vendor/sigmastar/alkaid/kernel/common/dtbo/pioneer5-xxxxxxx-xxxx-x.dts 文件（文件名与板子型号匹配）配置，重复配置回引起引脚复用失败，配置前需要将冲突注释掉，PWM PADMUX 参考示例：

<PAD_PWM_OUT6 PINMUX_FOR_PWM_OUT6_MODE_1 MDRV_PUSE_PWM6>

PWM 在设备树中的节点如下所示：

pwm {
    compatible = "sstar,pwm";
    reg = <0x1F2032000 x200>;
    npwm = <22>;
    clocks = <&CLK_pwm>;
    interrputs = <GIC_SPI INT_IRQ_PWM IRQ_TYPE_level_HIGH>;
    status = "ok";
}

PWM 驱动支持的属性如下：

属性	描述	备注
compatible	用于匹配驱动进行驱动注册，需与代码中一致	禁止修改
reg	用于指定 PWM 寄存器 bank 地址	不需要修改
interrupts	用于指定使用的硬件中断号及属性	不需要修改
clocks	用于指定 PWM 使用的时钟源	不需要修改
npwm	用于指定 PWM Channel 数量	不需要修改
status	用于选择是否使能 PWM 驱动	可根据需要修改

PWM driver 共有 20 通道，目前支持的 period 精度支持2档调节，普通模式精度范围为 44Hz - 6MHz；设置更高精度需要打开 CONFIG_PWM_NEW 选项，此时精度范围为 0.000698Hz - 6MHz。默认为高精度选项。普通精度模式的 period 单位为 Hz，duty_cycle 为百分比。而高精度模式的 period 和 duty_cycle都为 ns，若要设置 PWM 信号频率为 10KHz、占空比为 50%，则要先计算周期和占空比的值，再设置，计算出的参数值如下：

period = 10^9 / 10000 = 100000
duty_cycle = 10000 / 2 = 50000

2.2. PWM 接口说明¶

(1) int32_t sstar_pwm_init(uinit32_t pwm_num)¶

功能描述：PWM 通道初始化，如果初始化成功，将在 /sys/class/pwm/pwmchip0 下生成对应通道号的 PWM 节点

参数：

pwm_num : PWM 通道号，通道号范围为 0 ~ 19

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(2) int32_t sstar_pwm_deinit(uinit32_t pwm_num)¶

功能描述：PWM 通道去初始化，如果去初始化成功，将注销 /sys/class/pwm/pwmchip0 对应PWM 节点

参数：

pwm_num : PWM 通道号，通道号范围为 0 ~ 19

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(3) int32_t sstar_pwm_set_attr(uinit32_t pwm_num, struct pwm_attr* attr)¶

功能描述：PWM 周期、占空比和极性参数配置。如果 Uboot 下的 PWM 参数没有设置，周期和占空比默认为 0，极性默认为 normal，如果 Uboot 下已经设置了，初始参数与 Uboot 下的 PWM 参数一致。调用该接口必须满足 period > 0 且 period > duty 条件。

参数：

pwm_num : PWM 通道号，通道号范围为 0 ~ 19

attr : PWM 参数配置，包括周期、占空比和极性。周期指的是一个 PWM 信号的一个上升沿执行到下一个上升沿的时间，PWM 信号频率 = 1 / PWM 信号周期，占空比指的是高电平持续时间或低电平持续时间占 PWM 周期的比例，分为正极性和负极性两种，相关枚举和结构体内容如下：

// PWM 极性选择，NORMAL 代表设置高电平持续时间占 PWM 周期的比例，INVERSED 代表设置低电平持续时间占 PWM 周期的比例，
enum pwm_polarity {
    NORMAL,
    INVERSED,
};

struct pwm_attr {
    uint32_t period;            // PWM 周期
    uint32_t duty_cycle;        // PWM 占空比
    enum pwm_polarity polarity; // PWM 极性
};

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(4) int32_t sstar_pwm_get_attr(uinit32_t pwm_num, struct pwm_attr* attr)¶

功能描述：获取 PWM 周期、占空比和极性参数。如果 Uboot 下的 PWM 参数没有设置，周期和占空比默认为 0，极性默认为 normal，如果 Uboot 下已经设置了，初始参数与 Uboot 下的 PWM 参数一致。

参数：

pwm_num : PWM 通道号，通道号范围为 0 ~ 19
attr : PWM 参数配置，包括周期、占空比和极性，参考 sstar_pwm_set_attr 接口描述

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(5) int32_t sstar_pwm_enable(uinit32_t pwm_num, bool enable)¶

功能描述：PWM 通道使能，必须要在 PWM 参数配置完之后使能

参数：

pwm_num : PWM 通道号，通道号范围为 0 ~ 19
enable : enable / disable

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

2.3. PWM 接口使用示例¶

注意事项：如果调用了 sstar_pwm_init 接口，必须通过 sstar_pwm_set_attr 接口设置period 参数，同时满足 period > 0 且 period > duty 条件。如果 period 设置为 0，那么在进入 STR 状态时会报错。

int32_t ret;
uinit32_t pwm_num = 6;
struct pwm_attr set_attr = {5000, 10000, NORMAL};
struct pwm_attr get_attr;

// 初始化 PWM 通道6
ret = sstar_pwm_init(pwm_num);
// 设置 PWM 周期 10000 ns，占空比 50%， 极性为正
ret = sstar_pwm_set_attr(pwm_num, &set_attr);
// 获取 PWM 配置参数
ret = sstar_pwm_set_attr(pwm_num, &get_attr);
// PWM 使能
ret = sstar_pwm_enable(pwm_num, true);
// 去初始化 PWM 通道6
sstar_pwm_deinit(pwm_num);

3. UART 接口及功能介绍¶

3.1. UART 概述¶

UART (Universal Asynchronous Receiver/Transmitter) 通用异步收发传输器，是一种串行异步收发协议。UART 驱动采用 Linux 框架，并添加 Sigmastar 附加功能。当前平台共有 6 组带 URDMA的FUART 节点，其中 UART0 默认作为 console 使用。FUART 相对于普通的 UART 增加了 DMA 以及硬件流控，所以理论上是可以支持更大的波特率范围，可以在更高的波特率运行保证数据不丢失，硬件流控仅 FUART 支持。需要开启的 config 为 CONFIG_SSTAR_UART 。目前 dev/ 目录下有 ttyS0 ~ 6 共 7 个通道。

UART dtsi 节点举例如下, 别名可以更方便访问节点：

aliases {
    console = &uart0;
    serial0 = &uart0;
    seriall = &uart1;
    serial2 = &uart2;
    serial3 = &uart3;
    serial4 = &uart4;
    serial5 = &fuart;
    serial6 = &pm_uart;
};

uart0: uart0@1F221000 {
    compatible = "sstar,uart";
    reg = <0x1F2210000 x100>, <0x1F220E000 x100>;
    interrupts=<GIC_SPI INT_IRQ_FUART_0 IRQ_TYPE_LEVEL_HIGH>, <GIC_SPI INT_IRQ_URDMA_0 IRQ_TYPE_LEVEL_HIGH>, <GIC_SPI INT_IRQ_FUART_EMPTY IRQ_TYPE_LEVEL_HIGH>;
    dma = <1>:
    status = "ok";
    clocks = <&CLK_fuart0>;
};

fuart: fuart@1F220400 {
    compatible = "sstar,uart";
    reg = <0x1F2204000 x100>, <0x1F2206000 x100>;
    interrupts = <GIC_SPI INT_IRQ_FUART IRQ_TYPE_LEVEL_HIGH>, <GIC_SPI INT_IRQ_URDMA IRQ_TYPE_LEVEL_HIGH>, <GIC_SPI INT_IRQ_FUART_EMPTY IRQ_TYPE_LEVEL_HIGH>;
    dma = <1>;
    sctp_enable = <0>;
    rx_fifo_level = <0>;
    tx_fifo_level = <0>;
    digmux = <0XFF>;
    tolerance = <3>;
    status = "ok";
    clocks = <&CLK_fuart>;
};

pm_uart: pm_uart@1F006A00 {
    compatible = "sstar,uart";
    reg = <0X1F006A000 x100>;
    interrupts = <GIC_SPI INT_IRQ_PM_UART IRQ_TYPE_LEVEL HIGH>;
    rx_pin = <PAD_PM_GPIO0>;
    status = "ok";
    clocks = <&CLK_pm_uart>;
};

节点属性含义如下：

属性	描述	备注
compatible	用于匹配驱动进行驱动注册，需与代码中一致	禁止修改
reg	用于指定 UART (和 URDMA) 寄存器 bank 地址	不需要修改
interrupts	用于指定使用的硬件中断号及属性	不需要修改
clocks	用于指定 UART 使用的时钟源	不需要修改
sctp_enable	使能 FUART 的硬件流控，1 为开启	不需要修改
dma	使能 FUART 的 DMA 功能，1 为开启	可根据需要修改
tolerance	设置 UART 波特率可允许的误差范围，不能设置为 3	可根据需要修改
status	选择是否使能 UART 驱动	可根据需要修改
digmux	选择 UART TX pin 接到哪一组 digmux，每一组 UART 都会默认接到对应的 digmux 上；0xFF 表示驱动不会对该 UART 默认的 digmux 做修改	可根据需要修改，若无特殊需求可删除该属性
rx_fifo_level	选择 UART RX FIFO 等级，表现为接收到多少字节触发一次中断，超时也会触发中断，当前 FIFO 深度为 32 byte； "0" - 1 character in the FIFO; "1" - FIFO ¼ full; "2" - FIFO ½ full; "3" - FIFO 2 less than full	可根据需要修改，若无特殊需求可删除该属性
tx_fifo_level	选择 UART TX FIFO 等级，表现为接收到多少字节触发一次中断，超时也会触发中断，当前 FIFO 深度为 32 byte； "0" - FIFO empty; "1" - 1 character in the FIFO; "2" - FIFO ¼ full; "3" - FIFO ½ full	可根据需要修改，若无特殊需求可删除该属性

UART 支持的功能如下：

(1) URDMA 的功能是在 UART 接收到数据之后自动将数据读出放到内存的指定地址中，将写入到指定内存地址的数据分多次放入到 UART FIFO 中由 UART TX 发出。将 FUART 的设备树节点中的 dma 属性设置为 1 可以开启 FUART 的 DMA 功能。DMA 功能可以降低 UART 驱动的 CPU 占用率以及支持更高的波特率。

(2) 硬件流控功能也是一种防止数据丢失的方法，需要将 FUART 设备树节点中的 sctp_enable 属性设置为 1 开启。

(3) 波特率是指数据信号对载波的调制速率，它用单位时间内载波调制状态改变的次数来表示是 UART 的一个重要的指标。目前的硬件设计 UATR 实际输出的波特率由输入到 UART 的 CLK source 和设置的分频值共同确定。波特率 (BAUD) 、分频值 (DV) 以及输入的时钟频率 (CLK) 三者的关系如下：

DIV = CLK / (BAUD * 16)

由于给到 UART 的 CLK rate 并不是连续的，根据公式得出 UART 可以支持的波特率（误差3%）也不是连续的。目前可以支持 1M 以下的常用波特率，其他的波特率误差需要计算误差是否符合标准。

3.2. UART 接口说明¶

(1) int32_t sstar_uart_init(uint32_t uart_num)¶

功能描述：UART 初始化

参数：

uart_num : UART 通道号，通道号范围为 0 ~ 6

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(2) int32_t sstar_uart_deinit(uint32_t uart_num)¶

功能描述：UART 去初始化

参数：

uart_num : UART 通道号，通道号范围为 0 ~ 6

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(3) int32_t sstar_uart_set_attr(uint32_t uart_num, struct uart_attr* attr)¶

功能描述：设置 UART 通道的波特率、数据位、停止位和校验位

参数：

uart_num : UART 通道号，通道号范围为 0 ~ 6
attr : UART 参数配置，包括波特率、数据位、停止位和校验位。波特率表示为串口的传输速率，可选的波特率参考 termbits.h 文件，单位为 bps；数据位可以是 5-8 bit 位宽；停止位是一个数据的结束标志，可设置 1 位或 2 位停止位；校验位可以使用奇校验、偶校验或不校验，相关枚举和结构体内容如下：
```
// UART 数据位
enum uart_data_bit {
DATABIT_5,
DATABIT_6,
DATABIT_7,
DATABIT_8,
};

// UART 停止位
enum uart_stop_bit {
    STOPBIT_1,
    STOPBIT_2,
};

// UART 校验位
enum uart_parity {
    NON_PARITY,
    ODD_PARITY,
    EVEN_PARITY,
};

struct uart_attr {
    uint32_t buad;
    enum uart_data_bit data_bit;
    enum uart_stop_bit stop_bit;
    enum uart_parity parity;
};
```

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(4) int32_t sstar_uart_get_attr(uint32_t uart_num, struct uart_attr* attr)¶

功能描述：获取 UART 通道的波特率、数据位、停止位和校验位

参数：

uart_num : UART 通道号，通道号范围为 0 ~ 6
attr : UART 参数配置，包括波特率、数据位、停止位和校验位，参考 sstar_uart_set_attr 接口描述

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(5) int32_t sstar_uart_write(uint32_t uart_num, char* buf, uint32_t length)¶

功能描述：UART 写数据

参数：

uart_num : UART 通道号，通道号范围为 0 ~ 6
buf : 要写入的 buf 数据，传入的是 buf 地址
length : buf 长度

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(6) int32_t sstar_uart_read(uint32_t uart_num, char* buf, uint32_t length)¶

功能描述：UART 读数据

参数：

uart_num : UART 通道号，通道号范围为 0 ~ 6
buf : 要读取的 buf 数据，传入的是 buf 地址
length : buf 长度

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

3.3. UART 接口使用示例¶

int32_t ret;
uinit32_t uartnum = 0;
struct uart_attr set_attr = {B115200, DATABIT_8, STOPBIT_1, NON_PARITY};
struct uart_attr get_attr;
char tx_buf[3] = {0x01, 0x02, 0x03};
char rx_buf[1] = {0};

// 配置 uart 参数
ret = sstar_uart_set_attr(uart_num, &set_attr);
// 获取 uart 参数
ret = sstar_uart_get_attr(uart_num, &get_attr);
// uart 写数据
ret = sstar_uart_write(uart_num, tx_buf, sizeof(tx_buf));
// uart 读数据
ret = sstar_uart_read(uart_num, rx_buf, sizeof(rx_buf));

4. SPI 接口及功能介绍¶

4.1. SPI 概述¶

SPI (Serial Perripheral Interface) 是同步串行接口，可以连接各种外部设备。SPI driver 所需要配置的 config 为 CONFIG_SPI_SPIDEV 和 CONFIG_SS_MSPI 。目前 dev/ 路径下有 /dev/spidev0.0、/dev/spidev0.1、/dev/spidev1.0、/dev/spidev1.1 四个 SPI 设备节点。若要使用 /dev/spidev0.0 驱动设备，PADMAX 配置参考如下：

<PAD_SPI0_DO PINMUX_FOR_SPI0_MODE_1 MDRV_PUSE_SPI0_DO>
<PAD_SPI0_DI PINMUX_FOR_SPI0_MODE_1 MDRV_PUSE_SPI0_DI>
<PAD_SPI0_CK PINMUX_FOR_SPI0_MODE_1 MDRV_PUSE_SPI0_CK>
<PAD_SPI0_CZ PINMUX_FOR_SPI0_MODE_1 MDRV_PUSE_SPI0_CZ>

SPI master 驱动中支持配置的属性如下：

属性	描述	备注
compatible	用于匹配驱动进行驱动注册，需与代码中一致	禁止修改
reg	用于指定 SPI 寄存器 bank 地址	不需要修改
interrupts	用于指定使用的硬件中断号及属性	不需要修改
clocks	用于指定使用的时钟源	不需要修改
mspi-group	用于指定 SPI 外设编号序列号	不需要修改
use-dma	用于指定是否使能 DMA 模式	可根据需要修改
clk-out-mode	用于指定是否开启 clk-out-mode	可根据需要修改
cs-num	用于指定 Engine 自带的 cs pad 数量	可根据需要修改
cs-ext	用于指定 Engine 自带的 cs 外要使用的 pad index	和 cs-ext 配合使用
4to3-mode	用于指定是否开启 4 Wires 作为 3 Wrires 使用	可根据需要修改
status	用于选择是否使能 SPI master 驱动	可根据需要修改

SPI 功能支持如下：

(1) MSPI (Master SPI) 只能作为 master device，不能作为 slave device，支持 Motorola SPI 兼容时序 (CPHA / CPOL) 。

(2) 在 buffer mode 下支持全双工读写，DMA mode 下支持半双工读写，通过设备树节点的 user-dma 属性配置。当通信时发送或接收的数据量较少，可以考虑使用 buffer mode，工作效率较高。当数据量较大时会使提高 CPU 占用率，因此建议使用 DMA mode。

(3) 8 字节读写缓冲区 (FIFO mode) ，字节传输可配置 1bit ~ 15bit 位宽。

(4) 通信速率满足 50K ~ 72MHz 分档，如果设定的频率没有和分档一致，会自动选择小于设定值的最大档，分档如下：

档位	频率 (Hz)	档位	频率 (Hz)	档位	频率 (Hz)	档位	频率 (Hz)
1	46875	9	750000	17	3000000	25	13000000
2	93750	10	812500	18	3250000	26	13500000
3	187500	11	843750	19	3375000	27	18000000
4	210937	12	1125000	20	4500000	28	26000000
5	375000	13	1500000	21	6000000	29	27000000
6	406250	14	1625000	22	6500000	30	52000000
7	421875	15	1687500	23	6750000	31	54000000
8	562500	16	2250000	24	9000000	32	72000000

(5) 设备树可以预设多片选，目前 MSPI0 和 MSPI1 预设 2 路片选，所以 MSPI 设备节点有 /dev/spidev0.0、/dev/spidev0.1、/dev/spidev1.0、/dev/spidev1.1 四种。MSPI driver 会根据 cs-num 和 cs-ext 的合计数量注册设备节点，如果某个 SPI 节点下含有子节点，那么就会按照子节点的数量有限配置给 kernel space 使用，相应的 user space 节点就会注册失败。如需提供额外片选扩展，要在设备树节点的 cs-ext 属性中添加，同时应当将 CS 引脚对应的 pad 配置为 GPIO MODE。

(6) clk-out-mode 为 SigmaStar SPI Master 所支持的一种特殊模式。当 SPI Master 处于 clk-out-mode 时，SPI Master 的 MOSl 和 MISO 不再按给定的数据发送或接收数据，SPI Master 的 clock 信号会不断输出方波。此功的应用场景为使用 SP1 Master 输出的 clock 作为其他 Device 的工作时钟。clk-out-mode 属性的值用于指定输出 clock 的频率，配置 clk-out-mode 只需要在设备树中把 clk-out-mode 属性打开并设定波形频率就可以：

// 打开 clk-out-mode 功能，输出 3.75MHz 频率方波
clk-out-mode = <3750000>;

(7) 某些平台的 SPI Master3-wires mode 不支持 DMA mode，如果此时有 3-wires DMA mode的通讯需求时可以开启 4to3mode 模式。硬件上将 Master 的 MOSl 和 MlSO 短接并连接至 Device的SDAT，如下图所示。当驱动在读数据时，会将 MOSI 自动切换为 GPIO Input Mode 从而不干扰 MISO 的波形输入，从而达到将四线模式用作三线模式。如果要使用此功能，只要把dtsi节点当中的 4to3-mode 属性打开就可以。

4.2. SPI 接口说明¶

(1) int32_t sstar_spi_init(uinit32_t spi_num）¶

功能描述：SPI 初始化

参数：

spi_num ：SPI 主设备号，范围 0 ~ 1
dev_num ：SPI 从设备号，范围 0 ~ 1，根据设备树节点的 cs-num 和 cs-ext 波动

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(2) int32_t sstar_spi_deinit(uinit32_t spi_num）¶

功能描述：SPI 去初始化

参数：

spi_num ：SPI 主设备号，范围 0 ~ 1
dev_num ：SPI 从设备号，范围 0 ~ 1，根据设备树节点的 cs-num 和 cs-ext 波动

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(3) int32_t sstar_spi_set_attr(uinit32_t spi_num, uint32_t dev_num, struct spi_attr* attr)¶

功能描述：SPI 参数配置，包括 spi 模式、传输位宽、高位在前/低位在前、最大传输速率

参数：

spi_num ：SPI 主设备号，范围 0 ~ 1
dev_num ：SPI 从设备号，范围 0 ~ 1，根据设备树节点的 cs-num 和 cs-ext 波动

attr ：SPI 参数配置，包括 spi 模式、传输位宽、高位在前/低位在前、最大传输速率，相关枚举和结构体内容如下：

/**
* Set spi mode
* Spi mode 0 : CPOL=0, CPHA=0
* Spi mode 1 : CPOL=0, CPHA=1
* Spi mode 2 : CPOL=1, CPHA=0
* Spi mode 3 : CPOL=1, CPHA=1
*/
enum spi_mode {
    SPI_MODE0,
    SPI_MODE1,
    SPI_MODE2,
    SPI_MODE3,
};

/* spi LSB or MSB */
enum spi_firt_byte {
    MSB,
    LSB,
};

struct spi_attr {
    enum spi_mode mode;              // SPI 模式
    enum spi_first_byte first_byte;  // SPI LSB 或 MSB
    uint32_t bit_per_word;           // SPI 传输位宽
    uint32_t max_speed_hz;           // SPI 最大传输速率
}

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(4) int32_t sstar_spi_get_attr(uinit32_t spi_num, uint32_t dev_num, struct spi_attr* attr)¶

功能描述：SPI 参数配置，包括 spi 模式、传输位宽、高位在前/低位在前、最大传输速率

参数：

spi_num ：SPI 主设备号，范围 0 ~ 1
dev_num ：SPI 从设备号，范围 0 ~ 1，根据设备树节点的 cs-num 和 cs-ext 波动
attr ：SPI 参数配置，包括 spi 模式、传输位宽、高位在前/低位在前、最大传输速率，相关枚举和结构体参考 sstar_spi_set_attr 接口

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(5) int32_t sstar_spi_write(uinit32_t spi_num, uint32_t dev_num, char* buf, uint32_t length)¶

功能描述：SPI 写数据

参数：

spi_num ：SPI 主设备号，范围 0 ~ 1
dev_num ：SPI 从设备号，范围 0 ~ 1，根据设备树节点的 cs-num 和 cs-ext 波动
buf ：要写入的 buf 数据，传入的是 buf 地址
length : 要写入 buf 的长度

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(6) int32_t sstar_spi_read(uinit32_t spi_num, uint32_t dev_num, char* buf, uint32_t length)¶

功能描述：SPI 读数据

参数：

spi_num ：SPI 主设备号，范围 0 ~ 1
dev_num ：SPI 从设备号，范围 0 ~ 1，根据设备树节点的 cs-num 和 cs-ext 波动
buf ：要读取的 buf 数据，传入的是 buf 地址
length : 要读取 buf 的长度

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(7) int32_t sstar_spi_transfer(uinit32_t spi_num, uint32_t dev_num, char* tx_buf, char* rx_buf, uint32_t length)**¶

功能描述：SPI 双向通信

参数：

spi_num ：SPI 主设备号，范围 0 ~ 1
dev_num ：SPI 从设备号，范围 0 ~ 1，根据设备树节点的 cs-num 和 cs-ext 波动
tx_buf ：SPI 主设备发送给从设备的数据
rx_buf ：SPI 主设备接收来自从设备的数据
length : 发送或接收数据的最大长度

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

4.3. SPI 接口使用示例¶

int32_t ret;
uinit32_t spi_num = 0;
uinit32_t device_num = 0;
struct spi_attr set_attr = {SPI_MODE0, LSB, 8, 3000000};
struct spi_attr get_attr;
char tx_buf[3] = {0x01, 0x02, 0x03};
char rx_buf[10] = {0};

// 配置 SPI 参数
ret = sstar_spi_set_attr(spi_num, dev_num, &set_attr);
// 获取 SPI 参数
ret = sstar_spi_get_attr(spi_num, dev_num, &get_attr);
// SPI 双向通信，单向通信同理
ret = sstar_spi_transfer(spi_num, dev_num, tx_buf, rx_buf, sizeof(rx_buf));

5. GPIO 接口及功能介绍¶

5.1. GPIO 概述¶

General Purpose Input Output （通用输入/输出）简称为 GPIO。GPIO 采用标准的 LINUX 框架，能够使用统一的接口来操作 gpio 。

5.2. GPIO接口说明¶

(1) int32_t sstar_gpio_init(int32_t gpioNo)¶

功能描述：GPIO端口初始化，如果初始化成功，将在 /sys/class/gpio 下生成名为 ‘gpio+申请端口号’ 的目录

参数：

gpioNo ，GPIO 端口号

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(2) int32_t sstar_gpio_deinit(int32_t gpioNo)¶

功能描述：GPIO端口去初始化，如果去初始化成功，将移除在 /sys/class/gpio 路径下名为 ‘gpio+申请端口号’ 的目录

参数：

gpioNo : GPIO通道号

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(3) int32_t sstar_gpio_set_direction(int32_t gpioNo, enum gpio_direction dir)¶

功能描述：设置GPIO端口的方向

参数：

gpioNo : 要设置的GPIO端口号
dir : gpio_direction，表示要设置的gpio端口的方向，分别有 in、out、high、low 四种。值为in时，表示输入模式，value 不可写。值为 out 时，表示输出模式，value 可写，值为high 时，表示输出模式，默认高电平状态，value 可写。值为 low 时，表示输出模式，默认低电平状态，value 可写。enum gpio_direction 内容如下：
```
enum gpio_direction {
    GPIO_DIRECTION_IN,
    GPIO_DIRECTION_OUT,
    GPIO_DIRECTION_HIGH,
    GPIO_DIRECTION_LOW,
};
```

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(4) int32_t sstar_gpio_get_direction(int32_t gpioNo, enum gpio_direction* dir)¶

功能描述：获取 GPIO 端口的方向

参数：

gpioNo : 要获取的 GPIO 端口号
dir : gpio_direction，表示获取的 gpio 端口的方向，读取结果有 in 或 out 两种。值为 in时，表示输入模式，value 不可写。值为 out 时，表示输出模式，value 可写。

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(5) int32_t sstar_gpio_write(int32_t gpioNo, bool highVolt)**¶

功能描述：设置 GPIO 引脚的电平

参数：

gpioNo : 要设置的 GPIO 端口号
highVolt : true 代表写入高电平状态，false 表示写入低电平状态

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(6) int32_t sstar_gpio_read(int32_t gpioNo, bool* val)**¶

功能描述：读取 GPIO 引脚的电平

参数：

gpioNo : 要设置的 GPIO 端口号
val : true 代表高电平状态，false 表示低电平状态

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(7) int32_t sstar_gpio_set_edge(int32_t gpioNo, enum gpio_edge edge)¶

功能描述：设置是否使能 gpio 中断，并设置触发模式。支持上升沿触发、下降沿触发、双边沿触发。如果需要使能某只脚的中断，需要先将该脚设置为输入状态，并设置触发模式，则可以调用 poll(2) 函数监听该中断，中断触发后 poll(2) 函数就会返回。enum gpio_edge 内容如下：

        enum gpio_edge {
            GPIO_EDGE_NONE,
            GPIO_EDGE_RISING,
            GPIO_EDGE_FALLING,
            GPIO_EDGE_BOTH,
        };

参数：

gpioNo : 要设置的 GPIO 端口号
edge : none表示 disable gpio 中断，rising 表示使能 gpio 中断并设置为上升沿触发，falling 表示使能 gpio 中断并设置为下降沿触发，both 表示使能 gpio 中断并设置为双边沿触发

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(8) int32_t sstar_gpio_get_edge(int32_t gpioNo, enum gpio_edge* edge)¶

功能描述：获取某只引脚是否使能 gpio 中断和设置的触发模式。

参数：

gpioNo : 要获取的 GPIO 端口号
edge : 表示获取到的值，none 表示 disable gpio 中断，rising 表示使能 gpio 中断并设置为上升沿触发，falling 表示使能 gpio 中断并设置为下降沿触发，both 表示使能 gpio 中断并设置为双边沿触发

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

5.3. GPIO接口示例¶

int32_t gpioNo = 11;
enum gpio_direction dir = GPIO_DIRECTION_OUT;
bool Volt;

if(sstar_gpio_init(gpioNo) == 0){
    printf("sstar_gpio_init success");
}

if(sstar_gpio_set_direction(gpioNo,dir) == 0){
    printf("sstar_gpio_set_direction success");
}

if(sstar_gpio_read(gpioNo,&Volt) == 0){
    printf("sstar_gpio_read success");
}

if(sstar_gpio_deinit(gpioNo) == 0){
    printf("sstar_gpio_deinit success");
}

6. ADC 接口及功能介绍¶

6.1. ADC 概述¶

CHIP 有两部分的ADC，包括10bit 精度的 SAR-ADC 和12bit 精度的 PWM-ADC 。

SAR-ADC 有 2 个 Channel，获取到的值范围在 0~0x3ff 之间，参考电压有两个档位，分别为1.8V和1.0V。

PWM-ADC 有 24个 Channel ，获取到的值的范围在 0~0xFFF 之间，参考电压有两个档位。分别为3.3V和1.5V。

ADC 的主要功能是将连续变量的模拟信号转换为离散的数字信号，即可以将输入电压 V 转换为表示一定比例下的寄存器数值，当已知参考电压，计算公式为：

电压 = （寄存器数值 / 满量程）* 参考电压

因此 SAR-ADC 和 PWM-ADC 的主要功能都是模数转换，两者的区别在于：SAR-ADC 只支持Freerun 模式下的不间断采样，而 PWM-ADC 支持设定通道采样顺序、多种触发方式下的间断或不间断采样，并且允许 DMA 模式下的采样数值存储，具体展开如下：

Regular Channel / Inject Channel 采样，Regular Channel 的采样模式更多是在空闲状态下的电压采样，而 Inject Channel 的采样模式则更多是使用在某个特定时刻的电压检测，因为 Inject Channel 的采样会优先于 Regular Channel。
Regular Channel 的采样序列所能支持的最大通道数为23个ADC采样通道，Inject Channel 的采样序列所能支持的最大通道数为12个ADC采样通道。
在触发模式方面，Regular Channel / Inject Channel 采样都支持PWM触发、SW触发、External 触发，差异的地方是 Inject Channel 不支持 Freerun 模式，而 Regular Channel 支持，并且支持设置 Freerun 模式下每个通道之间的的采样间隔时间。
在采样模式方面，Regular Channel / Inject Channel 都支持 Single / Continuous 模式，即完成一个采样序列之后是选择继续采样还是停止采样。
为了应对高速采样模式下，寄存器数值不能及时存储的问题，支持开启 ADC 的 DMA 模式，可以将数据暂时存储于内存中，等到需要的时候再去对应地址获取。

6.2. Padmux配置¶

SAR-ADC 无需进行 padmux 的配置

PWM-ADC padmux 的配置：

1.    <PAD_SAR_ADC_0   PINMUX_FOR_ADC0_MODE_1   MDRV_PUSE_PWMADC0>,
2.    <PAD_SAR_ADC_1   PINMUX_FOR_ADC1_MODE_1   MDRV_PUSE_PWMADC1>,
3.    <PAD_SAR_ADC_2   PINMUX_FOR_ADC2_MODE_1   MDRV_PUSE_PWMADC2>,
4.    <PAD_SAR_ADC_3   PINMUX_FOR_ADC3_MODE_1   MDRV_PUSE_PWMADC3>,
5.    <PAD_SAR_ADC_4   PINMUX_FOR_ADC4_MODE_1   MDRV_PUSE_PWMADC4>,
6.    <PAD_SAR_ADC_5   PINMUX_FOR_ADC5_MODE_1   MDRV_PUSE_PWMADC5>,
7.    <PAD_SAR_ADC_6   PINMUX_FOR_ADC6_MODE_1   MDRV_PUSE_PWMADC6>,
8.    <PAD_SAR_ADC_7   PINMUX_FOR_ADC7_MODE_1   MDRV_PUSE_PWMADC7>,
9.    <PAD_SAR_ADC_8   PINMUX_FOR_ADC8_MODE_1   MDRV_PUSE_PWMADC8>,
10.    <PAD_SAR_ADC_9   PINMUX_FOR_ADC9_MODE_1   MDRV_PUSE_PWMADC9>,
11.    <PAD_SAR_ADC_10  PINMUX_FOR_ADC10_MODE_1  MDRV_PUSE_PWMADC10>,
12.    <PAD_SAR_ADC_11  PINMUX_FOR_ADC11_MODE_1  MDRV_PUSE_PWMADC11>,
13.    <PAD_SAR_ADC_12  PINMUX_FOR_ADC12_MODE_1  MDRV_PUSE_PWMADC12>,
14.    <PAD_SAR_ADC_13  PINMUX_FOR_ADC13_MODE_1  MDRV_PUSE_PWMADC13>,
15.    <PAD_SAR_ADC_14  PINMUX_FOR_ADC14_MODE_1  MDRV_PUSE_PWMADC14>,
16.    <PAD_SAR_ADC_15  PINMUX_FOR_ADC15_MODE_1  MDRV_PUSE_PWMADC15>,
17.    <PAD_SAR_ADC_16  PINMUX_FOR_ADC16_MODE_1  MDRV_PUSE_PWMADC16>,
18.    <PAD_SAR_ADC_17  PINMUX_FOR_ADC17_MODE_1  MDRV_PUSE_PWMADC17>,
19.    <PAD_SAR_ADC_18  PINMUX_FOR_ADC18_MODE_1  MDRV_PUSE_PWMADC18>,
20.    <PAD_SAR_ADC_19  PINMUX_FOR_ADC19_MODE_1  MDRV_PUSE_PWMADC19>,
21.    <PAD_SAR_ADC_20  PINMUX_FOR_ADC20_MODE_1  MDRV_PUSE_PWMADC20>,
22.    <PAD_SAR_ADC_21  PINMUX_FOR_ADC21_MODE_1  MDRV_PUSE_PWMADC21>,
23.    <PAD_SAR_ADC_22  PINMUX_FOR_ADC22_MODE_1  MDRV_PUSE_PWMADC22>,
24.    <PAD_SAR_ADC_23  PINMUX_FOR_ADC23_MODE_1  MDRV_PUSE_PWMADC23>,

6.3. SAR-ADC接口说明¶

(1) int32_t sstar_saradc_init()¶

功能描述：设置 SAR-ADC 的初始化。

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(1) int32_t sstar_saradc_deinit()¶

功能描述：设置 SAR-ADC 的去初始化。

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(1) int32_t sstar_saradc_set_refvol(int32_t level)¶

功能描述：设置 SAR-ADC 的参考电压档位，参考电压有两个档位，分别为1.8V和1.0V。

参数：

level : 设置的 SAR-ADC 参考电压档位，1表示1.8V，0表示1.0V

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(2) int32_t sstar_saradc_get_config(int32_t* config)¶

功能描述：获取 SAR-ADC 的参考电压档位，参考电压有两个档位，分别为1.8V和1.0V。

参数：

config : 获取的 SAR-ADC 参考电压档位，1表示1.8V，0表示1.0V

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(3) int32_t sstar_saradc_set_channel(int32_t adcNo)¶

功能描述：设置 SAR-ADC 的 Channel,SAR-ADC 有2个Channel , Channel 0 和 Channel 1。

参数：

adcNo : 设置的 SAR-ADC 的通道号，0表示 Channel 0，1表示 Channel 1。

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(4) int32_t sstar_saradc_get_value(int32_t* val)¶

功能描述：获取 SAR-ADC 的采样后的值。

参数：

val : 获取的 SAR-ADC 的采样后的值，获取到的值范围在0~0x3ff之间。

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

6.4. SAR-ADC接口示例¶

int32_t sarNo = 0;
int32_t sarVol = 1;
int32_t ret = 0;
enum gpio_direction dir = OUT;
bool Volt;

if(sstar_saradc_init() == 0){
    printf("sstar_saradc_init success");
}

if(sstar_saradc_set_refvol(sarVol) == 0){
    printf("sstar_saradc_set_refvol success");
}

if(sstar_saradc_set_channel(sarNo) == 0){
    printf("sstar_saradc_set_channel success");
}

if(sstar_saradc_get_value(&ret) == 0){
    printf("sstar_saradc_get_value success");
}

if(sstar_saradc_deinit() == 0){
    printf("sstar_saradc_deinit success");
}

6.5. PWM-ADC接口说明¶

(1) int32_t sstar_pwmadc_init()¶

功能描述：用于 enable PWM-ADC

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(2) int32_t sstar_pwmadc_deinit()¶

功能描述：用于 disable PWM-ADC

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(3) int32_t sstar_pwmadc_set_refvol(int32_t channel, int32_t level, int32_t rext)¶

功能描述：设置 PWM-ADC 的参考电压档位，参考电压有两个档位，1表示3.3V，0表示1.5V。当参考电压为3.3V的时候，需要输入外部电阻的阻值，单位为Ohm。

参数：

channel : 设置的 PWM-ADC 参考电压档位的通道号

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(4) int32_t sstar_pwmadc_get_config(int32_t* config)¶

功能描述：获取 PWM-ADC 的参考电压档位，参考电压有两个档位，1表示3.3V，0表示1.5V。当参考电压为3.3V的时候，需要输入外部电阻的阻值，单位为Ohm。

参数：

config : 获取的 PWM-ADC 参考电压档位。获取到1表示1.5V档位，获取到3表示3.3V的档位

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(5) int32_t sstar_pwmadc_set_regular_config(struct adc_config* config)¶

功能描述：设置 PWM-ADC 的 Regular Channel 采样相关的配置

参数：

config : PWM-ADC 采样相关的配置，struct adc_config 内容如下，其中关于Inject Channel 采样的项可以不用配置

struct adc_config {
    char inject_sequence[64];  // 设置Inject Channel采样的通道个数total_number和具体的通道序列，提供24个通道可以选择
    char regular_sequence[64]; // 设置Regular Channel采样的通道个数total_number和具体的通道序列，提供24个通道可以选择
    int32_t trigger_mode;      // 设置触发类型，0~11表示PWM_PN触发，12表示sw触发，13表示外部触发，14表示freerun
    int32_t trigger_method;    // 设置触发方法，1表示每次触发完成一个sequence的采样，0表示每次触发完成一个channel的采样
    int32_t regular_continuous;// 设置Regular Channel采样的模式，0表示single mode，当完成一个采样序列后会停止采样，1表示continuous mode，当完成一个采样序列之后不会停止采样，而是继续采样
    int32_t inject_continuous; // 设置Inject Channel采样的模式，0表示single mode，当完成一个采样序列后会停止采样，1表示continuous mode，当完成一个采样序列之后不会停止采样，而是继续采样
    int32_t regular_start;     // 开始/结束Regular Channel的采样，选择continuous mode的时候，可以通过设为0停止采样
    int32_t inject_start;      // 开始/结束Inject Channel的采样，选择continuous mode的时候，可以通过设为0停止采样
    int32_t sw_trigger;        // 选择sw触发类型的时候，通过sw_trigger进行触发，1表示Regular Channel的sw触发
};

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(6) int32_t sstar_pwmadc_set_inject_config(struct adc_config* config)¶

功能描述：设置PWM-ADC的Inject Channel采样相关的配置

参数：

config : PWM-ADC 采样相关的配置，struct adc_config 内容如下，其中关于Regular Channel 采样的项可以不用配置

struct adc_config {
    char inject_sequence[64];  // 设置Inject Channel采样的通道个数total_number和具体的通道序列，提供24个通道可以选择
    char regular_sequence[64]; // 设置Regular Channel采样的通道个数total_number和具体的通道序列，提供24个通道可以选择
    int32_t trigger_mode;      // 设置触发类型，0~11表示PWM_PN触发，12表示sw触发，13表示外部触发，14表示freerun
    int32_t trigger_method;    // 设置触发方法，1表示每次触发完成一个sequence的采样，0表示每次触发完成一个channel的采样
    int32_t regular_continuous;// 设置Regular Channel采样的模式，0表示single mode，当完成一个采样序列后会停止采样，1表示continuous mode，当完成一个采样序列之后不会停止采样，而是继续采样
    int32_t inject_continuous; // 设置Inject Channel采样的模式，0表示single mode，当完成一个采样序列后会停止采样，1表示continuous mode，当完成一个采样序列之后不会停止采样，而是继续采样
    int32_t regular_start;     // 开始/结束Regular Channel的采样，选择continuous mode的时候，可以通过设为0停止采样
    int32_t inject_start;      // 开始/结束Inject Channel的采样，选择continuous mode的时候，可以通过设为0停止采样
    int32_t sw_trigger;        // 选择sw触发类型的时候，通过sw_trigger进行触发，1表示Regular Channel的sw触发
};

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(7) int32_t sstar_pwmadc_get_value(int32_t adcNo, int32_t* value)¶

功能描述：输入 PWM-ADC 采样的通道号，获取 PWM-ADC 采样的值

参数：

adcNo : PWM-ADC 采样的通道号
value : PWM-ADC 采样获取的值

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(8) int32_t sstar_pwmadc_set_dma_config(int32_t align, int32_t enable, int32_t size)¶

功能描述：设置 ADC DMA Mode 相关的配置

参数：

align : 设置数据对齐方式，1表示左对齐，0表示右对齐
enable : 设置是否 enable DMA mode，1表示 enable，0表示 disable
size : 设置用于存储ADC数据的内存大小，单位Byte。例如设为100时，表示0x100

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(9) int32_t sstar_pwmadc_set_interval_config(int32_t count, int32_t time)¶

功能描述：设置采样间隔相关的配置

参数：

count : 设置每个通道的采样次数，支持四档的采样次数设置，0：1 time；1：4 times；2：8 times；3：16 times
time : 设置每个通道的采样的时间：time * 167 ns

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

6.6. 接口使用示例¶

    char in[] = {7, 0, 1, 2, 3, 4, 5, 6};
    struct adc_config adc;
    int ret;
    int length = in[0] + 1;
    for (int i = 0; i < length; i++) {
        adc.regular_sequence[i] = in[i];
    }
    adc.trigger_mode = 14;
    adc.trigger_method = 0;
    adc.regular_continuous = 1;
    adc.regular_start = 1;

    // 初始化PWM-ADC
    if(sstar_pwmadc_init() == 0){
        printf("sstar_pwmadc_init success");
    } else {
        printf("sstar_pwmadc_init error");
    }

    // 设定PWM-ADC相关的配置
    if (sstar_pwmadc_set_regular_config(&adc) == 0) {
        printf("sstar_pwmadc_set_regularconfig success");
    } else {
        printf("sstar_pwmadc_set_regularconfig error");
    }

    // 获取PWM-ADC channel 0 的值
    sstar_pwmadc_get_value(0，&ret)

    // 去初始化PWM-ADC
    if(sstar_pwmadc_deinit() == 0){
        printf("sstar_pwmadc_deinit success");
    } else {
        printf("sstar_pwmadc_deinit error");
    }

7. PWMIN 接口及功能介绍¶

7.1. PWMIN概述¶

PWMIN 主要用于电机的操控和电机转速状态反馈，PWMOUT输出PWM波形控制电机工作，PWMIN捕获 PWM 波形的周期占空比信息，以此形成反馈，得到电机当前的工作状态，包括周期、占空比、脉冲个数。

PWMIN driver 相应的 config 为 CONFIG_SSTAR_PWM_IN。若要将某个引脚复用成 PWMIN 功能，需要先在 vendor/sigmastar/alkaid/kernel/common/dtbo/pioneer5-xxxxxxx-xxxx-x.dts 文件（文件名与板子型号匹配）配置，重复配置回引起引脚复用失败，配置前需要将冲突注释掉，PWMIN PADMUX 参考示例：

<PAD_KEY0        PINMUX_FOR_PWM_IN0_MODE_1   MDRV_PUSE_PWMIN0>,
<PAD_KEY1        PINMUX_FOR_PWM_IN1_MODE_1   MDRV_PUSE_PWMIN1>,

PWM 在 dtsi 中的节点如下所示：

pwmin: pwmin
    compatible = "sstar,pwmin";
    reg = <0x1F201A00 0x200>;
    clocks = <&CLK_pwm_adc>;
    interrputs = <GIC_SPI INT_IRQ_PWM_CAPTURE IRQ_TYPE_LEVEL_HIGH>;
    status = "ok";
};

7.2. 驱动节点调试¶

以下为 PWMIN 周期和占空比的捕获功能调试：

disable channel$n 的 input capture 功能

echo $n 0 > /sys/devices/virtual/mstar/pwmin/pwm_in_en

设置为每 2^k 个脉冲再进行捕获波形的信息计算，k 越大计算精度越高，k 支持设置为 0、1、2、3、4。设置时需要先关闭 channel$n 的 input capture 功能。pwm_in_pul_div 节点可以不设置，默认 k 为 0。
```
echo $n k > /sys/devices/virtual/mstar/pwmin/pwm_in_pul_div
```

enable channel$n 的 input capture 功能

echo $n 1 > /sys/devices/virtual/mstar/pwmin/pwm_in_en

获取捕获信息

echo $n > /sys/devices/virtual/mstar/pwmin/pwm_in_get
cat /sys/devices/virtual/mstar/pwmin/pwm_in_get

以下为 PWMIN 脉冲捕获功能的调试：

disable channel$n 的 input capture 功能

echo $n 0 > /sys/devices/virtual/mstar/pwmin/pwm_in_en

选择 channel $n 计数的边沿类型，0 表示下边沿，1 表示上边沿，2 表示双边沿。设置时需要先关闭channel$ n的input capture功能。
```
echo $n enable edge > /sys/devices/virtual/mstar/pwmin/pwm_in_pul_cal
```

enable channel$n 的 input capture 功能

echo $n 1 > /sys/devices/virtual/mstar/pwmin/pwm_in_en

获取脉冲个数

echo $n > /sys/devices/virtual/mstar/pwmin/pwm_in_get_pul

7.3. PWMIN 接口说明¶

(1) int32_t sstar_pwm_in_init(uint32_t pwm_in_num)¶

功能描述：PWMIN 通道初始化

参数：

pwm_in_num : PWMIN 通道号，通道号范围为 0 ~ 7

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(2) int32_t sstar_pwm_in_deinit(uint32_t pwm_in_num)¶

功能描述：PWMIN 通道去初始化

参数：

pwm_in_num : PWMIN 通道号，通道号范围为 0 ~ 7

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(3) sstar_pwm_in_set_timeout(uint32_t pwm_in_num, uint32_t timeout)¶

功能描述：设置 PWMIN 捕获信号的超时时间，一般大于输入信号的预计最小周期，driver在超时时间内如果没有检测到脉冲变化，period、duty和pulse都会判断为0。timeout 参数建议要大于三倍的最小周期，避免误判

参数：

pwm_in_num : PWMIN 通道号，通道号范围为 0 ~ 7
timeout : 超时时间，单位为 us

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(4) int32_t sstar_pwm_in_set_pulse_div(uint32_t pwm_in_num, pwm_in_pulse_div div)¶

功能描述：PWMIN 通道设置采样精度，有五档可选，0: 1 div，1: 2 div， 2: 4 div， 3: 8 div， 4: 16 div。如果不设置 div，默认为 1 div。

参数：

pwm_in_num : PWMIN 通道号，通道号范围为 0 ~ 7

div : PWMIN 通道的采样精度。enum pwm_in_pulse_div 内容如下：

enum pwm_in_pulse_div {
    PULSE_DIV_O,
    PULSE_DIV_1,
    PULSE_DIV_2,
    PULSE_DIV_3,
    PULSE_DIV_4,
};

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(5) int32_t sstar_pwm_in_get_period_and_duty(uint32_t pwm_in_num, uint32_t* period, float* duty)¶

功能描述：获取 PWMIN 通道周期和占空比

参数：

pwm_in_num : PWMIN 通道号，通道号范围为 0 ~ 7
period : 返回获取的 PWMIN 周期
duty : 返回获取的 PWMIN 占空比

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(6) int32_t sstar_pwm_in_set_capture_edge(uint32_t pwm_in_num, pwm_in_capture_edge edge)¶

功能描述：PWMIN 脉冲捕获方式，有下降沿捕获、上升沿捕获和双边沿捕获可选。脉冲捕获之前必须要配置捕获方式。

参数：

pwm_in_num : PWMIN 通道号，通道号范围为 0 ~ 7

edge : PWMIN 通道的采样精度。enum pwm_in_capture_edge 内容如下：

enum pwm_in_capture_edge {
    FALLING_EDGE,
    RISING_EDGE,
    BOTH_EDGE,
};

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(7) int32_t sstar_pwm_in_get_pulse(uint32_t pwm_in_num, uint32_t* pulse)¶

功能描述：获取 PWMIN 通道脉冲计数

参数：

pwm_in_num : PWMIN 通道号，通道号范围为 0 ~ 7
pulse : 返回获取的 PWMIN 脉冲计数

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

7.3. PWMIN 接口示例¶

uint32_t channel = 3;
uint32_t div = 3;
uint32_t timeout = 6000;
uint32_t period;
float duty;
uint32_t pulse;

sstar_pwm_in_init(channel);
// 设置超时时间
sstar_pwm_in_set_timeout(channel, timeout);
// 捕获占空比和周期
sstar_pwm_in_set_pulse_div(channel, PULSE_DIV_2);  // 如果不设置 div，默认为 1 div
sstar_pwm_in_get_period_and_duty(channel, &period, &duty);
printf("get period = %d, duty = %f", period, duty);
// 捕获脉冲
sstar_pwm_in_set_capture_edge(channel, RISING_EDGE);  // 必须要设置捕获方式
sstar_pwm_in_get_pulse(channel, &pulse);
printf("get pulse = %d", pulse);
sstar_pwm_in_deinit(channel);

8. 其他接口及功能介绍¶

8.1. env 分区读写功能及接口¶

该功能是对 dev/block/by-name/env 存储设备进行读写。该分区存储环境变量，通过 fw_printenv 和 fw_setenv shell 命令可对其参数进行修改和保存。sstar_set_env 和 sstar_get_env 接口功能基本等同于 fw_printenv 和 fw_setenv。

8.1.1 接口说明¶

(1) int32_t sstar_set_env(const char* var, const char* value)

功能描述：设置指定 env 变量对应的参数。如果 value 输入字符为空，则表示删除该环境变量。

参数：

var : env 变量
value : env 变量对应的参数

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(2) int32_t sstar_get_env(const char* var, char* value)

功能描述：获取指定 env 变量对应的参数。如果 var 输入字符为空，则返回所有环境变量及其对应参数。

参数：

var : env 变量
value : 返回 env 变量对应的参数

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

8.1.2 接口示例¶

// 设置 baudrate 为 115200
sstar_set_env("baudrate", "115200");
// 删除 baudrate 变量
sstar_set_env("baudrate", "");

char* value = NULL;
value = (char*)malloc(sizeof(char) * ENVSIZE);
// 获取 bootargs 参数值
sstar_get_env("bootargs", value);
// 获取全部变量的参数值
sstar_get_env("", value);
free(value);

8.2. factory_raw 分区读写功能及接口¶

factory_raw 裸分区用于存放 serial number、mac address、HDCP key 等设备相关信息，

8.2.1 接口说明¶

(1) set_factory_raw_entry(enum factory_raw_entry_index index, const uint8_t* data, uint32_t len)

功能描述：设置 factory_raw 分区某一偏移位置的数据。

参数：

index : 将 factory_raw 分区按 512 byte 作为一个 block 进行划分，每个 block，index 代表 block 索引号。block 从低到高分别存储 serial number，LAN0/LAN1 端口信息，HDCP 1.4/2.2 密钥信息。enum factory_raw_entry_index 内容如下：

enum factory_raw_entry_index {
    /* 20 Bytes */
    FACTORY_RAW_ENTRY_SN = 0,
    /* 18 Bytes */
    FACTORY_RAW_ENTRY_LAN0 = 1,
    /* 18 Bytes */
    FACTORY_RAW_ENTRY_LAN1 = 2,
    /* 341 Bytes */
    FACTORY_RAW_ENTRY_HDCP14 = 3,
    /* 960 Bytes */
    FACTORY_RAW_ENTRY_HDCP22 = 4,
    FACTORY_RAW_ENTRY_MAX = 6,
};

data : 要写入的数据
len : 数据长度

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

(2) get_factory_raw_entry(enum factory_raw_entry_index index, uint8_t** data, uint32_t* len)

index : 将 factory_raw 分区索引号，详情如上述接口描述。
data : 返回存储数据的指针地址
len : 返回数据长度

返回值：

SSTAR_SUCCESS：0，SSTAR_FAILURE：-1

8.2.2 接口示例¶

// 设置 LAN0 地址为 00:00:83:76:00:01
uint8_t data[] = {'0', '0', ':', '0', '0', ':', '8', '3', ':', '7', '6', ':', '0', '0', ':', '0', '1', ':'};
set_factory_raw_entry(FACTORY_RAW_ENTRY_LAN0, data, sizeof(data));

// 获取 LAN0 地址
uint32_t num;
uint8_t* data = NULL;
get_factory_raw_entry(FACTORY_RAW_ENTRY_LAN0, &data, &num);
free(data);