API GUIDE / DMA / LL

G32S10 DMA LL 接口

LL 层接口：功能说明：

1. LL 与基础辅助接口规范

1.1 LL 层实现边界

LL 层接口定义在 ll_dma.h。
LL 层公开接口均为 static inline。
LL 层接口首参数为 dma_regs_t *dma。
LL 层只做寄存器读写，不做参数合法性检查、通道分配、请求源分类、descriptor 构造或软件状态维护。
HAL 内部通过 LL 层访问 DMA MMIO 寄存器；descriptor RAM 字段由 HAL 直接访问。

1.2 LL 层公开宏和寄存器类型

类型/宏	说明
`dma_regs_t`	DMA 控制器寄存器块类型。
`dma_channel_regs_t`	DMA 单通道寄存器块类型。
`PDMA0`	HP-domain PDMA 控制器实例。
`PDMA1`	LP-domain PDMA 控制器实例。
`DMA_CONTROLLER_COUNT`	控制器数量，当前为 2。
`DMA_CHANNEL_COUNT`	单控制器通道数，当前为 32。

1.3 全局控制和中断状态

1.3.1 `ll_dma_global_enable`

static inline void ll_dma_global_enable(dma_regs_t *dma);

功能说明：

清除 DMAC_HLT_MASK/DMAC_AR_MASK 并置位 DMAC_DMAE_MASK，使能一个 DMA 控制器。

参数表：

参数	类型	方向	说明
`dma`	`dma_regs_t *`	输入/输出	DMA 控制器寄存器基地址。

返回值表：

返回值	说明
无	接口不返回状态码。

1.3.2 `ll_dma_global_disable`

static inline void ll_dma_global_disable(dma_regs_t *dma);

功能说明：

清除 DMAC_DMAE_MASK，关闭一个 DMA 控制器全局使能。

参数表：

参数	类型	方向	说明
`dma`	`dma_regs_t *`	输入/输出	DMA 控制器寄存器基地址。

返回值表：

返回值	说明
无	接口不返回状态码。

1.3.3 `ll_dma_get_irq_pending`

static inline uint32_t ll_dma_get_irq_pending(dma_regs_t *dma);

功能说明：

读取 DMA 控制器 pending interrupt 位图。

参数表：

参数	类型	方向	说明
`dma`	`dma_regs_t *`	输入	DMA 控制器寄存器基地址。

返回值表：

返回值	说明
`uint32_t`	`DIRQP` pending 位图。

1.3.4 Pending 查询和清除接口

static inline void ll_dma_clear_irq_pending(dma_regs_t *dma, uint32_t channel_mask);
static inline uint32_t ll_dma_get_descriptor_irq_pending(dma_regs_t *dma);
static inline void ll_dma_clear_descriptor_irq_pending(dma_regs_t *dma,
                                                       uint32_t channel_mask);

以上接口用于分别读取 descriptor pending、清除 normal pending 和清除 descriptor pending：

接口	寄存器操作	返回值
`ll_dma_clear_irq_pending()`	向 `DIRQP` 写入 `~channel_mask`，清除掩码选中的 normal pending。	无。
`ll_dma_get_descriptor_irq_pending()`	读取 `DIP`。	`uint32_t` descriptor pending 位图。
`ll_dma_clear_descriptor_irq_pending()`	向 `DIC` 写入 `~channel_mask`，清除掩码选中的 descriptor pending。	无。

参数说明：

参数	类型	说明
`dma`	`dma_regs_t *`	DMA 控制器寄存器基地址。
`channel_mask`	`uint32_t`	要清除 pending 的通道位图；bit n 为 1 表示选择通道 n。

两类清除操作都使用 W0C 编码：寄存器写 0 清除对应 pending，写 1 保留；LL 内部对调用方提供的正向 channel_mask 取反，不需要调用方提前取反。

1.4 通道控制

1.4.1 `ll_dma_clear_channel_status`

static inline void ll_dma_clear_channel_status(dma_regs_t *dma,
                                               uint32_t channel_id);

功能说明：

清除指定通道 DCS 控制/状态寄存器。

参数表：

参数	类型	方向	说明
`dma`	`dma_regs_t *`	输入/输出	DMA 控制器寄存器基地址。
`channel_id`	`uint32_t`	输入	通道号，范围 0 ~ DMA_CHANNEL_COUNT - 1。

返回值表：

返回值	说明
无	接口不返回状态码。

1.4.2 `ll_dma_get_channel_status`

static inline uint32_t ll_dma_get_channel_status(dma_regs_t *dma,
                                                 uint32_t channel_id);

功能说明：

读取指定通道 DCS 控制/状态寄存器。

参数表：

参数	类型	方向	说明
`dma`	`dma_regs_t *`	输入	DMA 控制器寄存器基地址。
`channel_id`	`uint32_t`	输入	通道号，范围 0 ~ DMA_CHANNEL_COUNT - 1。

返回值表：

返回值	说明
`uint32_t`	`DCS` 寄存器值。

1.4.3 `ll_dma_set_descriptor_addr`

static inline void ll_dma_set_descriptor_addr(dma_regs_t *dma,
                                              uint32_t channel_id,
                                              uint32_t desc_phys);

功能说明：

写入指定通道 DDA descriptor 起始地址。

参数表：

参数	类型	方向	说明
`dma`	`dma_regs_t *`	输入/输出	DMA 控制器寄存器基地址。
`channel_id`	`uint32_t`	输入	通道号，范围 0 ~ DMA_CHANNEL_COUNT - 1。
`desc_phys`	`uint32_t`	输入	descriptor 物理地址。

返回值表：

返回值	说明
无	接口不返回状态码。

1.4.4 `ll_dma_ring_doorbell`

static inline void ll_dma_ring_doorbell(dma_regs_t *dma,
                                        uint32_t channel_id);

功能说明：

写 DDBS 对指定通道触发 descriptor doorbell。

参数表：

参数	类型	方向	说明
`dma`	`dma_regs_t *`	输入/输出	DMA 控制器寄存器基地址。
`channel_id`	`uint32_t`	输入	通道号，范围 0 ~ DMA_CHANNEL_COUNT - 1。

返回值表：

返回值	说明
无	接口不返回状态码。

1.4.5 `ll_dma_start_descriptor_transfer`

static inline void ll_dma_start_descriptor_transfer(dma_regs_t *dma,
                                                    uint32_t channel_id);

功能说明：

向指定通道 DCS 写入 DCS_DES8_MASK | DCS_CTE_MASK，启动 8-word descriptor 模式传输。

参数表：

参数	类型	方向	说明
`dma`	`dma_regs_t *`	输入/输出	DMA 控制器寄存器基地址。
`channel_id`	`uint32_t`	输入	通道号，范围 0 ~ DMA_CHANNEL_COUNT - 1。

返回值表：

返回值	说明
无	接口不返回状态码。

1.4.6 `ll_dma_start_nondescriptor_transfer`

static inline void ll_dma_start_nondescriptor_transfer(dma_regs_t *dma,
                                                       uint32_t channel_id);

功能说明：

向指定通道 DCS 写入 DCS_NDES_MASK | DCS_CTE_MASK，启动非 descriptor 模式传输。

参数表：

参数	类型	方向	说明
`dma`	`dma_regs_t *`	输入/输出	DMA 控制器寄存器基地址。
`channel_id`	`uint32_t`	输入	通道号，范围 0 ~ DMA_CHANNEL_COUNT - 1。

返回值表：

返回值	说明
无	接口不返回状态码。

1.4.7 直接传输寄存器写入接口

以下 LL 接口用于非 descriptor 模式或通道寄存器直接配置，均只写对应通道寄存器，不做参数检查：

接口	写入寄存器	说明
`ll_dma_set_src_addr(dma, channel_id, addr)`	`DSA`	写通道源物理地址。
`ll_dma_set_dst_addr(dma, channel_id, addr)`	`DTA`	写通道目的物理地址。
`ll_dma_set_transfer_count(dma, channel_id, count)`	`DTC`	写通道 transfer count。
`ll_dma_set_request_type(dma, channel_id, request)`	`DRT`	写通道 request source。
`ll_dma_set_channel_command(dma, channel_id, command)`	`DCM`	写通道 command word。
`ll_dma_set_stride(dma, channel_id, stride)`	`DSD`	写通道 stride difference。

其中 channel_id 范围为 0 ~ DMA_CHANNEL_COUNT - 1，由调用方保证。

1.5 当前地址和 CAN RX compare 配置

1.5.1 `ll_dma_get_src_addr`

static inline uint32_t ll_dma_get_src_addr(dma_regs_t *dma,
                                           uint32_t channel_id);

功能说明：

读取指定通道当前源地址 DSA。

参数表：

参数	类型	方向	说明
`dma`	`dma_regs_t *`	输入	DMA 控制器寄存器基地址。
`channel_id`	`uint32_t`	输入	通道号，范围 0 ~ DMA_CHANNEL_COUNT - 1。

返回值表：

返回值	说明
`uint32_t`	当前源地址。

1.5.2 `ll_dma_get_dst_addr`

static inline uint32_t ll_dma_get_dst_addr(dma_regs_t *dma,
                                           uint32_t channel_id);

功能说明：

读取指定通道当前目的地址 DTA。

参数表：

参数	类型	方向	说明
`dma`	`dma_regs_t *`	输入	DMA 控制器寄存器基地址。
`channel_id`	`uint32_t`	输入	通道号，范围 0 ~ DMA_CHANNEL_COUNT - 1。

返回值表：

返回值	说明
`uint32_t`	当前目的地址。

1.5.3 `ll_dma_set_source_compare_addr`

static inline void ll_dma_set_source_compare_addr(dma_regs_t *dma,
                                                  uint32_t index,
                                                  uint32_t addr);

功能说明：

配置 SACIDX0 或 SACIDX1 的源地址 compare 低位字段。

参数表：

参数	类型	方向	说明
`dma`	`dma_regs_t *`	输入/输出	DMA 控制器寄存器基地址。
`index`	`uint32_t`	输入	`0` 选择 `SACIDX0`，`1` 选择 `SACIDX1`。
`addr`	`uint32_t`	输入	源 compare 地址。

返回值表：

返回值	说明
无	接口不返回状态码。

补充说明：

HAL 当前仅在 linked/cyclic CAN RX 场景下配置 SACIDX。
addr 写入时只保留 DMA_SACIDX_ADDR_MASK 对应低 16 bit 字段。

1.6 诊断寄存器读取

以下 LL 接口用于 HAL dump 或调试场景，均不修改硬件状态：

接口	返回寄存器/字段
`ll_dma_get_channel_dsa(dma, channel_id)`	通道 `DSA`。
`ll_dma_get_channel_dta(dma, channel_id)`	通道 `DTA`。
`ll_dma_get_channel_dtc(dma, channel_id)`	通道 `DTC`。
`ll_dma_get_channel_drt(dma, channel_id)`	通道 `DRT`。
`ll_dma_get_channel_dcm(dma, channel_id)`	通道 `DCM`。
`ll_dma_get_channel_dda(dma, channel_id)`	通道 `DDA`。
`ll_dma_get_channel_dsd(dma, channel_id)`	通道 `DSD`。
`ll_dma_get_sacidx0(dma)`	`SACIDX0`。
`ll_dma_get_sacidx1(dma)`	`SACIDX1`。
`ll_dma_get_dacidx0(dma)`	`DACIDX0`。
`ll_dma_get_dacidx1(dma)`	`DACIDX1`。

2. 寄存器映射与位域约定

2.1 寄存器映射

单通道寄存器块：

偏移	寄存器	说明
`0x000 + n * 0x20`	`DSA`	Channel source address。
`0x004 + n * 0x20`	`DTA`	Channel target address。
`0x008 + n * 0x20`	`DTC`	Channel transfer count。
`0x00C + n * 0x20`	`DRT`	Channel request source。
`0x010 + n * 0x20`	`DCS`	Channel control/status。
`0x014 + n * 0x20`	`DCM`	Channel command。
`0x018 + n * 0x20`	`DDA`	Channel descriptor address。
`0x01C + n * 0x20`	`DSD`	Channel stride difference。

控制器全局寄存器：

偏移	寄存器	说明
`0x000-0x3FF`	`channel[32]`	32 个通道寄存器块。
`0x1000`	`DMAC`	DMA control。
`0x1004`	`DIRQP`	DMA interrupt pending。
`0x1008`	`DDB`	DMA doorbell。
`0x100C`	`DDBS`	DMA doorbell set。
`0x1010`	`DIP`	Descriptor interrupt pending。
`0x1014`	`DIC`	Descriptor interrupt clear，写 0 清除。
`0x1060`	`SACIDX0`	Source address compare index 0。
`0x1064`	`SACIDX1`	Source address compare index 1。
`0x1068`	`DACIDX0`	Destination address compare index 0。
`0x106C`	`DACIDX1`	Destination address compare index 1。

2.2 主要寄存器和位域宏

dma_regs.h 中的位域组标题带有寄存器偏移，便于和硬件手册直接对照；普通完整地址寄存器如 DSA/DTA/DRT 没有可拆分位域，因此只在寄存器结构体中定义，不额外定义字段 mask。

寄存器/字段组	说明
`DCS__SHIFT` / `DCS__MASK`	通道 descriptor 模式、当前 descriptor offset、地址错误、终止、halt、传输使能等字段。
`DCM__SHIFT` / `DCM__MASK`	源/目的递增、wrap、请求间隔、端口宽度、传输大小、SACIDX、stride、传输中断、LINK 等字段。
`DDA__SHIFT` / `DDA__MASK`	Descriptor base address 和 descriptor offset address 字段。
`DSD__SHIFT` / `DSD__MASK`	源/目的 stride difference 字段。
`DMAC__SHIFT` / `DMAC__MASK`	控制器全局使能、地址错误、halt、burst、fast request 等字段。
`DTC_DTC_SHIFT` / `DTC_DTC_MASK`	通道 `DTC` / descriptor `dtc` word 中低 24 bit 的 transfer count 字段。
`DESC_DTC_DOA_SHIFT` / `DESC_DTC_DOA_MASK`	8-word descriptor `dtc` word 中高 8 bit 的 next descriptor DOA 字段。
`DMA_SACIDX_ADDR_SHIFT` / `DMA_SACIDX_ADDR_MASK`	SACIDX/DACIDX 地址字段。

2.3 寄存器访问约束

dma_regs.h 只定义寄存器布局和位域，不承载高层业务逻辑。
ll_dma.h 负责 DMA MMIO 寄存器读写。
HAL 可直接访问 descriptor RAM 字段，因为 descriptor 是普通内存，不是 MMIO 寄存器。
struct dma_regs 中的 reserved 数组只描述 MMIO 偏移，不会额外分配 RAM，除非显式实例化该结构体对象。

G32S10 DMA LL 接口

1. LL 与基础辅助接口规范

1.1 LL 层实现边界

1.2 LL 层公开宏和寄存器类型

1.3 全局控制和中断状态

1.3.1 ll_dma_global_enable

1.3.2 ll_dma_global_disable

1.3.3 ll_dma_get_irq_pending

1.3.4 Pending 查询和清除接口

1.4 通道控制

1.4.1 ll_dma_clear_channel_status

1.4.2 ll_dma_get_channel_status

1.4.3 ll_dma_set_descriptor_addr

1.4.4 ll_dma_ring_doorbell

1.4.5 ll_dma_start_descriptor_transfer

1.4.6 ll_dma_start_nondescriptor_transfer

1.4.7 直接传输寄存器写入接口

1.5 当前地址和 CAN RX compare 配置

1.5.1 ll_dma_get_src_addr

1.5.2 ll_dma_get_dst_addr

1.5.3 ll_dma_set_source_compare_addr

1.6 诊断寄存器读取

2. 寄存器映射与位域约定

2.1 寄存器映射

2.2 主要寄存器和位域宏

2.3 寄存器访问约束

1.3.1 `ll_dma_global_enable`

1.3.2 `ll_dma_global_disable`

1.3.3 `ll_dma_get_irq_pending`

1.4.1 `ll_dma_clear_channel_status`

1.4.2 `ll_dma_get_channel_status`

1.4.3 `ll_dma_set_descriptor_addr`

1.4.4 `ll_dma_ring_doorbell`

1.4.5 `ll_dma_start_descriptor_transfer`

1.4.6 `ll_dma_start_nondescriptor_transfer`

1.5.1 `ll_dma_get_src_addr`

1.5.2 `ll_dma_get_dst_addr`

1.5.3 `ll_dma_set_source_compare_addr`