CN / EN

全部 创新产品 应用与设计 文档中心 工具与软件 开发者社区 关于汇顶
文档反馈
感谢关注汇顶文档，期待您的宝贵建议！
感谢您的反馈，祝您愉快！
无匹配项 共计114个匹配页面
文档中心 > GR551x HAL及LL驱动用户手册/ HAL驱动/ HAL I2S通用驱动/ I2S驱动API描述 Copy URL

I2S驱动API描述

I2S驱动的API主要包括：

表 448 I2S驱动的APIs
API类别 API名称 描述
初始化 hal_i2s_init() 初始化I2S外设，配置参数。
hal_i2s_deinit() 反初始化I2S外设。
hal_i2s_msp_init() 初始化I2S外设所使用的GPIO引脚复用、NVIC中断、DMA通道。
hal_i2s_msp_deinit() 反初始化I2S外设所使用的GPIO引脚复用、NVIC中断、DMA通道。
IO操作 hal_i2s_transmit() 数据发送，轮询方式。
hal_i2s_receive() 数据接收，轮询方式。
hal_i2s_transmit_receive() 数据发送与接收，轮询方式。
hal_i2s_transmit_it() 数据发送，中断方式。
hal_i2s_receive_it() 数据接收，中断方式。
hal_i2s_transmit_receive_it() 数据发送与接收，中断方式。
hal_i2s_transmit_dma() 数据发送，DMA方式。
hal_i2s_receive_dma() 数据接收，DMA方式。
hal_i2s_transmit_receive_dma() 数据发送与接收，DMA方式。
hal_i2s_abort() 中止中断及DMA方式下的数据传输。
中断处理及回调函数 hal_i2s_irq_handler() 中断处理函数。
hal_i2s_tx_cplt_callback() 发送完成中断回调函数。
hal_i2s_rx_cplt_callback() 接收完成中断回调函数。
hal_i2s_error_callback() 错误中断回调函数。
状态及错误 hal_i2s_get_state() 获取驱动运行状态。
hal_i2s_get_error() 获取错误码。
时钟控制 hal_i2s_start_clock() 作为主模式的时候开始输出时钟。
hal_i2s_stop_clock() 作为主模式的时候停止输出时钟。
FIFO阈值操作函数 hal_i2s_set_tx_fifo_threshold 设置TX FIFO阈值。
hal_i2s_set_rx_fifo_threshold 设置RX FIFO阈值。
hal_i2s_get_tx_fifo_threshold 获取TX FIFO阈值。
hal_i2s_get_rx_fifo_threshold 获取RX FIFO阈值。
睡眠相关 hal_i2s_suspend_reg() 睡眠之前挂起和I2S配置相关的寄存器。
hal_i2s_resume_reg() 唤醒时恢复和I2S配置相关的寄存器。

下面章节将对各API进行详细描述。

hal_i2s_init

表 449 hal_i2s_init接口
函数原型

hal_status_t hal_i2s_init(i2s_handle_t *p_i2s)
功能说明

根据i2s_init_t中的指定参数初始化I2S和关联句柄。
输入参数

p_i2s：指向i2s_handle_t结构体变量的指针，该结构体变量包含指定的I2S的配置信息。
返回值

HAL状态。
备注

hal_i2s_deinit

表 450 hal_i2s_deinit接口
函数原型

hal_status_t hal_i2s_deinit(i2s_handle_t *p_i2s)
功能说明

反初始化I2S。
输入参数

p_i2s：指向i2s_handle_t结构体变量的指针，该结构体变量包含指定的I2S的配置信息。
返回值

HAL状态。
备注

hal_i2s_msp_init

表 451 hal_i2s_msp_init接口
函数原型

void hal_i2s_msp_init(i2s_handle_t *p_i2s)
功能说明

初始化I2S所使用的GPIO引脚复用、NVIC中断、DMA通道等配置。
输入参数

p_i2s：指向i2s_handle_t结构体变量的指针，该结构体变量包含指定的I2S的配置信息
返回值

无
备注

该函数为weak类型的空函数，开发者需重写该API完成GPIO引脚复用、NVIC中断、DMA通道的初始化。

hal_i2s_msp_deinit

表 452 hal_i2s_msp_deinit接口
函数原型

void hal_i2s_msp_deinit(i2s_handle_t *p_i2s)
功能说明

反初始化I2S所使用的GPIO引脚复用、NVIC中断、DMA通道等配置。
输入参数

p_i2s：指向i2s_handle_t结构体变量的指针，该结构体变量包含指定的I2S的配置信息
返回值

无
备注

该函数为weak类型的空函数，开发者需重写该API完成GPIO引脚复用、NVIC中断、DMA通道的反初始化。

hal_i2s_transmit

表 453 hal_i2s_transmit接口
函数原型

hal_status_t hal_i2s_transmit(i2s_handle_t *p_i2s, uint16_t *p_data, uint32_t length, uint32_t timeout)
功能说明

发送大量数据，轮询方式。
输入参数

p_i2s：指向i2s_handle_t结构体变量的指针，该结构体变量包含指定的I2S的配置信息。

p_data：指向数据缓冲区的指针。

length：待发送数据的长度，单声道的数据量，单位2 Bytes。

timeout：超时时间，单位ms。
返回值

HAL状态。
备注

返回HAL_ERROR时可调用hal_i2s_get_error()获取具体的错误码。

hal_i2s_receive

表 454 hal_i2s_receive接口
函数原型

hal_status_t hal_i2s_receive(i2s_handle_t *p_i2s, uint16_t *p_data, uint32_t length, uint32_t timeout)
功能说明

接收大量数据，轮询方式。
输入参数

p_i2s：指向i2s_handle_t结构体变量的指针，该结构体变量包含指定的I2S的配置信息。

p_data：指向数据缓冲区的指针。

length：待接收数据的长度，单声道的数据量，单位2 Bytes。

timeout：超时时间，单位ms。
返回值

HAL状态。
备注

返回HAL_ERROR时可调用hal_i2s_get_error()获取具体的错误码。

hal_i2s_transmit_receive

表 455 hal_i2s_transmit_receive接口
函数原型

hal_status_t hal_i2s_transmit_receive(i2s_handle_t *p_i2s, uint16_t *p_tx_data, uint16_t *p_rx_data, uint32_t length, uint32_t timeout)
功能说明

发送与接收大量数据，轮询方式。
输入参数

p_i2s：指向i2s_handle_t结构体变量的指针，该结构体变量包含指定的I2S的配置信息。

p_tx_data：指向发送数据缓冲区的指针。

p_rx_data：指向接收数据缓冲区的指针。

length：发送与接收数据的长度，单位Byte。

timeout：超时时间，单位ms。
返回值

HAL状态。
备注

返回HAL_ERROR时可调用hal_i2s_get_error()获取具体的错误码。

hal_i2s_transmit_it

表 456 hal_i2s_transmit_it接口
函数原型

hal_status_t hal_i2s_transmit_it(i2s_handle_t *p_i2s, uint16_t *p_data, uint32_t length)
功能说明

发送大量数据，中断方式。
输入参数

p_i2s：指向i2s_handle_t结构体变量的指针，该结构体变量包含指定的I2S的配置信息。

p_data：指向数据缓冲区的指针。

length：待发送数据的长度，单声道的数据量，单位2 Bytes。
返回值

HAL状态。
备注

hal_i2s_receive_it

表 457 hal_i2s_receive_it接口
函数原型

hal_status_t hal_i2s_receive_it(i2s_handle_t *p_i2s, uint16_t *p_data, uint32_t length)
功能说明

接收大量数据，中断方式。
输入参数

p_i2s：指向i2s_handle_t结构体变量的指针，该结构体变量包含指定的I2S的配置信息。

p_data：指向数据缓冲区的指针。

length：待接收数据的长度，单声道的数据量，单位2 Bytes。
返回值

HAL状态。
备注
  • 接收完成时，回调函数hal_i2s_rx_cplt_callback()会被调用。
  • 发送和接收过程中出现错误时，回调函数hal_i2s_error_callback()会被调用，开发者可在回调函数中调用hal_i2s_get_error()获取具体的错误码。
  • 回调函数hal_i2s_rx_cplt_callback()被调用前，请勿释放data指向的数据缓冲区的内存。

hal_i2s_transmit_receive_it

表 458 hal_i2s_transmit_receive_it接口
函数原型

hal_status_t hal_i2s_transmit_receive_it(i2s_handle_t *p_i2s, uint16_t *p_tx_data, uint16_t *p_rx_data, uint32_t length)
功能说明

发送与接收大量数据，中断方式。
输入参数

p_i2s：指向i2s_handle_t结构体变量的指针，该结构体变量包含指定的I2S的配置信息。

p_tx_data：指向发送数据缓冲区的指针。

p_rx_data：指向接收数据缓冲区的指针。

length：发送与接收数据的长度，单位Byte。
返回值

HAL状态。
备注

hal_i2s_abort

表 459 hal_i2s_abort接口
函数原型

hal_status_t hal_i2s_abort(i2s_handle_t *p_i2s)
功能说明

中止I2S中断或DMA方式的数据传输。
输入参数

p_i2s：指向i2s_handle_t结构体变量的指针，该结构体变量包含指定的I2S的配置信息。
返回值

HAL状态。
备注

该函数为轮询式函数，退出函数时，中止完成。

hal_i2s_transmit_dma

表 460 hal_i2s_transmit_dma接口
函数原型

hal_status_t hal_i2s_transmit_dma(i2s_handle_t *p_i2s, uint16_t *p_data, uint32_t length)
功能说明

发送大量数据，DMA方式。
输入参数

p_i2s：指向i2s_handle_t结构体变量的指针，该结构体变量包含指定的I2S的配置信息。

p_data：指向数据缓冲区的指针。

length：待发送数据的长度。
返回值

HAL状态。
备注

hal_i2s_receive_dma

表 461 hal_i2s_receive_dma接口
函数原型

hal_status_t hal_i2s_receive_dma(i2s_handle_t *p_i2s, uint16_t *p_data, uint32_t length)
功能说明

以DMA非轮询模式接收大量数据。
输入参数

p_i2s：指向i2s_handle_t结构体变量的指针，该结构体变量包含指定的I2S的配置信息。

p_data：指向数据缓冲区的指针。

length：待接收数据的长度。
返回值

HAL状态。
备注

hal_i2s_transmit_receive_dma

表 462 hal_i2s_transmit_receive_dma接口
函数原型

hal_status_t hal_i2s_transmit_receive_dma(i2s_handle_t *p_i2s, uint16_t *p_tx_data, uint16_t *p_rx_data, uint32_t length)
功能说明

发送与接收大量数据，DMA方式。
输入参数

p_i2s：指向i2s_handle_t结构体变量的指针，该结构体变量包含指定的I2S的配置信息。

p_tx_data：指向发送数据缓冲区的指针。

p_rx_data：指向接收数据缓冲区的指针。

length：发送与接收数据的长度，单位Byte。
返回值

HAL状态。
备注

hal_i2s_irq_handler

表 463 hal_i2s_irq_handler接口
函数原型

void hal_i2s_irq_handler(i2s_handle_t *p_i2s)
功能说明

处理I2S中断请求。
输入参数

p_i2s：指向i2s_handle_t结构体变量的指针，该结构体变量包含指定的I2S的配置信息。
返回值

无
备注

hal_i2s_tx_cplt_callback

表 464 hal_i2s_tx_cplt_callback接口
函数原型

void hal_i2s_tx_cplt_callback(i2s_handle_t *p_i2s)
功能说明

发送完成回调函数。
输入参数

p_i2s：指向i2s_handle_t结构体变量的指针，该结构体变量包含指定的I2S的配置信息。
返回值

无
备注

该函数为weak类型的空函数，当开发者需要使用该回调函数时，可重写该API。

hal_i2s_tx_rx_cplt_callback

表 465 hal_i2s_tx_rx_cplt_callback接口
函数原型

void hal_i2s_tx_rx_cplt_callback(i2s_handle_t *p_i2s)
功能说明

发送与接收完成回调函数。
输入参数

p_i2s：指向i2s_handle_t结构体变量的指针，该结构体变量包含指定的I2S的配置信息。
返回值

无
备注

该函数为weak类型的空函数，当开发者需要使用该回调函数时，可重写该API。

hal_i2s_rx_cplt_callback

表 466 hal_i2s_rx_cplt_callback接口
函数原型

void hal_i2s_rx_cplt_callback(i2s_handle_t *p_i2s)
功能说明

接收完成回调函数。
输入参数

p_i2s：指向i2s_handle_t结构体变量的指针，该结构体变量包含指定的I2S的配置信息。
返回值

无
备注

该函数为weak类型的空函数，当开发者需要使用该回调函数时，可重写该API。

hal_i2s_error_callback

表 467 hal_i2s_error_callback接口
函数原型

void hal_i2s_error_callback(i2s_handle_t *p_i2s)
功能说明

I2S错误回调函数。
输入参数

p_i2s：指向i2s_handle_t结构体变量的指针，该结构体变量包含指定的I2S的配置信息。
返回值

无
备注

该函数为weak类型的空函数，当开发者需要使用该回调函数时，可重写该API。

hal_i2s_get_state

表 468 hal_i2s_get_state接口
函数原型

hal_i2s_state_t hal_i2s_state_t hal_i2s_get_state(i2s_handle_t *p_i2s)
功能说明

获取I2S运行状态。
输入参数

p_i2s：指向i2s_handle_t结构体变量的指针，该结构体变量包含指定的I2S的配置信息。
返回值

I2S运行状态，该参数的取值可以是下列值中的任意一个：

  • HAL_I2S_STATE_RESET（未初始化）
  • HAL_I2S_STATE_READY（已初始化且空闲）
  • HAL_I2S_STATE_BUSY（忙）
  • HAL_I2S_STATE_BUSY_TX（正在发送）
  • HAL_I2S_STATE_BUSY_RX （正在接收）
  • HAL_I2S_STATE_BUSY_TX_RX （正在进行发送与接收）
  • HAL_I2S_STATE_ABORT（被中断）
  • HAL_I2S_STATE_ERROR（错误）
备注

hal_i2s_get_error

表 469 hal_i2s_get_error接口
函数原型

uint32_t hal_i2s_get_error(i2s_handle_t *p_i2s)
功能说明

返回I2S句柄错误码。
输入参数

p_i2s：指向i2s_handle_t结构体变量的指针，该结构体变量包含指定的I2S的配置信息。
返回值

I2S错误码，该参数的取值可以是下列值中的任意一个：

  • HAL_I2S_ERROR_NONE（无错误）
  • HAL_I2S_ERROR_TIMEOUT（超时）
  • HAL_I2S_ERROR_TRANSFER（传输错误）
  • HAL_I2S_ERROR_DMA（DMA传输错误）
  • HAL_I2S_ERROR_INVALID_PARAM（参数错误）
备注

hal_i2s_start_clock

表 470 hal_i2s_start_clock接口
函数原型

hal_status_t hal_i2s_start_clock(i2s_handle_t *p_i2s)
功能说明

开始输出时钟（作为主设备）。
输入参数

p_i2s：指向i2s_handle_t结构体变量的指针，该结构体变量包含指定的I2S的配置信息。
返回值

HAL状态。
备注

hal_i2s_stop_clock

表 471 hal_i2s_stop_clock接口
函数原型

hal_status_t hal_i2s_stop_clock(i2s_handle_t *p_i2s)
功能说明

停止输出时钟（作为主设备）。
输入参数

p_i2s：指向i2s_handle_t结构体变量的指针，该结构体变量包含指定的I2S的配置信息。
返回值

HAL状态。
备注

hal_i2s_set_tx_fifo_threshold

表 472 hal_i2s_set_tx_fifo_threshold接口
函数原型

hal_status_t hal_i2s_set_tx_fifo_threshold(i2s_handle_t *p_i2s, uint32_t threshold)
功能说明

设置TX FIFO阈值。
输入参数

p_i2s：指向i2s_handle_t结构体变量的指针，该结构体变量包含指定的I2S的配置信息。

threshold:待设置的阈值参数。
返回值

HAL状态。
备注

hal_i2s_set_rx_fifo_threshold

表 473 hal_i2s_set_rx_fifo_threshold接口
函数原型

hal_status_t hal_i2s_set_rx_fifo_threshold(i2s_handle_t *p_i2s, uint32_t threshold)
功能说明

设置RX FIFO阈值。
输入参数

p_i2s：指向i2s_handle_t结构体变量的指针，该结构体变量包含指定的I2S的配置信息。

threshold: 待设置的阈值参数。
返回值

HAL状态。
备注

hal_i2s_get_tx_fifo_threshold

表 474 hal_i2s_get_tx_fifo_threshold接口
函数原型

uint32_t hal_i2s_get_tx_fifo_threshold(i2s_handle_t *p_i2s)
功能说明

获取TX FIFO阈值。
输入参数

p_i2s：指向i2s_handle_t结构体变量的指针，该结构体变量包含指定的I2S的配置信息。
返回值

TX FIFO阈值。
备注

hal_i2s_get_rx_fifo_threshold

表 475 hal_i2s_get_rx_fifo_threshold接口
函数原型

uint32_t hal_i2s_get_tx_fifo_threshold(i2s_handle_t *p_i2s)
功能说明

获取RX FIFO阈值。
输入参数

p_i2s：指向i2s_handle_t结构体变量的指针，该结构体变量包含指定的I2S的配置信息。
返回值

RX FIFO阈值。
备注

hal_i2s_suspend_reg

表 476 hal_i2s_suspend_reg接口
函数原型 hal_status_t hal_i2s_suspend_reg(i2s_handle_t *p_i2s)
功能说明 睡眠之前挂起和I2S配置相关的寄存器
输入参数 p_i2s：指向i2s_handle_t结构体变量的指针，该结构体变量包含指定的I2S的配置信息。
返回值 HAL状态。
备注

hal_i2s_resume_reg

表 477 hal_i2s_resume_reg接口
函数原型 hal_status_t hal_i2s_resume_reg(i2s_handle_t *p_i2s)
功能说明 唤醒时恢复和I2S配置相关的寄存器
输入参数 p_i2s：指向i2s_handle_t结构体变量的指针，该结构体变量包含指定的I2S的配置信息。
返回值 HAL状态。
备注

扫描关注

打开微信，使用“扫一扫”即可关注。