驱动命名规则

GR551x驱动的命名规则包括基本命名规则、HAL驱动API命名规则及LL驱动API命名规则。

基本命名规则

基本命名规则为HAL驱动及LL驱动通用的命名规则，包括文件、模块、结构体、宏等的命名规则。

具体的命名规则描述如下：

表 5 基本命名规则
类别	命名样式	命名说明	示例
文件	ccc_ddd_ppp.c/h ccc_ddd_ppp_ex.c/h	文件名称主要由芯片型号、驱动类型、外设名称组成。如果为扩展驱动，则需加“_ex”后缀。	gr55xx_hal_gpio.(c/h) gr55xx_hal_gpio_ex.(c/h) gr55xx_ll_gpio.(c/h)
模块	HAL_PPP_MODULE	模块名称主要由驱动类型和外设名称、“_MODULE”后缀组成。	HAL_I2C_MODULE
宏定义	PPP_PARAM LL_PPP_PARAM	宏定义名称采用大写英文字母，并且LL驱动的宏定义名称添加了“LL_”前缀。	UART_DATABITS_8 LL_UART_PARITY_NONE
结构体	ppp_sss_t ll_ppp_sss_t	结构体名称主要由外设名称、结构体类型组成，并且结构体后面直接跟“_t”后缀，LL驱动的结构体还添加了“ll_”前缀。	qspi_handle_t ll_uart_init_t
枚举	ddd_ppp_enumname_t	枚举名称主要由驱动类型、外设名称、枚举类型、“_t”后缀组成。	hal_uart_state_t
枚举标签	DDD_PPP_ENUM	枚举标签名称由驱动类型、外设名称、标签含义组成，采用大写英文字母。	HAL_UART_STATE_RESET
寄存器	REGISTERNAME	寄存器名称采用大写英文字母，命名方式与GR551x Datasheet中基本保持一致（部分过长的寄存器名会适当缩写）。	MODEM_CTRL
寄存器结构体	ppp_regs_t	寄存器结构体名称由外设名称、“_regs_t”后缀组成。	uart_regs_t

命名说明：

ccc：芯片系列型号，例如：gr55xx。
DDD/ddd：驱动类型，例如：HAL/hal，LL/ll。
PPP/ppp：外设名称，例如：GPIO/gpio，QSPI/qspi，URAT/uart等。
sss：结构体类型，例如：handle，init。
PARAM：外设参数。
ENUM：枚举标签名。
REGISTERNAME：寄存器名称。

HAL驱动API命名规则

HAL驱动各类API的命名规则如下：

表 6 HAL层API命名规则
API类别	命名样式	命名说明
初始化类	hal_ppp_init hal_ppp_deinit	函数名主要由驱动类型（hal）、外设名称、初始化/反初始化组成。
IO操作类	hal_ppp_operate	函数名主要由驱动类型（hal）、外设名称、操作方式（比如发送，接收，回调函数处理等）组成。
	hal_ppp_command_operate	对于命令的收发，在外设名称与操作之间添加了command。
	hal_ppp_operate_it	中断模式下的操作添加了“_it”后缀。
	hal_ppp_operate_dma	DMA模式下的操作添加了“_dma”后缀。
中断处理及回调类	hal_ppp_irq_handler	中断处理函数命名为驱动类型（hal）、外设名称、“_irq_handler”后缀组成。
	hal_ppp_operate_cplt_callback	操作完成的回调函数名，直接在操作方式后加“_cplt_callback”后缀。
	hal_ppp_error_callback	函数名主要由驱动类型（hal）、外设名称、后缀“_error_callback”构成。
控制类	hal_ppp_set_parameter hal_ppp_get_parameter	函数名主要由驱动类型（hal）、外设名称、参数名称组成。
状态及错误类	hal_ppp_get_state hal_ppp_get_error	函数名主要由驱动类型（hal）、外设名称、状态/错误操作组成。

说明：

PPP/ppp：外设名称，例如：QSPI/qspi，URAT/uart等。
operate：操作类型，例如：transmit/tx，receive/rx，abort等。
parameter：参数名称，例如：fifo_threshold，timeout等。

下面以QSPI为例说明HAL驱动API的命名规则。

表 7 QSPI的HAL层API命名
API类别	函数名	函数描述
初始化类	hal_qspi_init	初始化QSPI，设置时钟、引脚复用等参数。
	hal_qspi_deinit	反初始化QSPI，恢复初始设置。
	hal_qspi_mspinit	初始化QSPI使用的GPIO、中断NVIC、DMA。
	hal_qspi_mspdeinit	反初始化QSPI使用的GPIO、中断NVIC、DMA。
IO操作类	hal_qspi_command_transmit	轮询方式的数据收发接口。
	hal_qspi_command_receive
	hal_qspi_command
	hal_qspi_transmit
	hal_qspi_receive
	hal_qspi_command_transmit_it	中断方式的数据收发接口。
	hal_qspi_command_receive_it
	hal_qspi_command_it
	hal_qspi_transmit_it
	hal_qspi_receive_it
	hal_qspi_command_transmit_dma	DMA方式的数据收发接口。
	hal_qspi_command_receive_dma
	hal_qspi_command_dma
	hal_qspi_transmit_dma
	hal_qspi_receive_dma
	hal_qspi_abort	终止当前正在进行的传输操作。
	hal_qspi_abort_it	终止当前正在进行的传输操作。
中断处理及回调类	hal_qspi_irq_handler	中断处理函数。
	hal_qspi_tx_cplt_callback	发送完成回调函数。
	hal_qspi_rx_cplt_callback	接收完成回调函数。
	hal_qspi_error_callback	错误检测回调函数。
	hal_qspi_abort_cplt_callback	中止完成回调函数。
控制类	hal_qspi_set_timeout	设置超时。
	hal_qspi_set_tx_fifo_threshold	设置FIFO阈值。
	hal_qspi_set_rx_fifo_threshold	设置FIFO阈值。
	hal_qspi_get_tx_fifo_threshold	读取FIFO阈值。
	hal_qspi_get_rx_fifo_threshold	读取FIFO阈值。
状态及错误类	hal_qspi_get_state	读取外设状态。
状态及错误类	hal_qspi_get_error	读取错误码。

LL驱动API命名规则

LL驱动各类API的命名规则如下：

表 8 LL层API命名规则
API类别	命名样式	命名说明
初始化类	ll_ppp_init ll_ppp_deinit	由驱动类型（ll）、外设名称、初始化/反初始化组成。
功能使能类	ll_ppp_enable_function ll_ppp_disable_function ll_ppp_is_enabled_function	由驱动类型（ll）、外设名称、使能/禁止/是否使能、功能名组成。
IO操作类	ll_ppp_transmit_dataN ll_ppp_receive_dataN	由驱动类型（ll）、外设名称、transmit/receive、data及位宽组成。
参数设置类	ll_ppp_set_parameter ll_ppp_get_parameter	由驱动类型（ll）、外设名称、设置/读取、参数名组成。
标志与状态类	ll_ppp_is_active_flag_flagname ll_ppp_clear_flag_flagname ll_ppp_clear_flag ll_ppp_clear_flagtype_flag ll_ppp_get_flagtype_flag	该类型API的命名方式主要包括以下两种：由驱动类型（ll）、外设名称、is_active/clear、_flag、标志名称组成，用于判断外设状态或清除单个标志由驱动类型（ll）、外设名称、get/clear、标志类型、后缀“_flag”组成，用于获取或清除某类型的标志，其中部分外设无标志类型
中断控制类	ll_ppp_enable_it_itname ll_ppp_disable_it_itname ll_ppp_is_enabled_it_itname ll_ppp_enable_it ll_ppp_disable_it ll_ppp_is_enabled_it	由驱动类型（ll）、外设名称、使能/禁止/是否使能、it、中断名称组成，其中没有中断名称的接口（如ll_ppp_enable_it）可用于控制多个中断。
DMA控制类	ll_ppp_enable_dma_req_tx/rx ll_ppp_disable_dma_req_tx/rx ll_ppp_is_enabled_dma_req_tx/rx	由驱动类型（ll）、外设名称、使能/禁止/是否使能、DMA操作请求类型组成。

说明：

PPP/ppp：外设名称，例如：QSPI/qspi，URAT/uart。
function：需要操作的外设功能名称，例如：I2C中的general_call。
N：IO操作中的数据位宽，可为8、16、32。
parameter：参数名称，例如：fifo_threshold，timeout。
flagname：标志名称，例如：I2C中的STOP_DET中断的flagname为stop_det。
flagtype：需要清除或获取的标志类型，例如：it、line_status。
itname：中断名称，例如：UART中的RDA中断的itname为rda。

下面以UART为例说明LL驱动API的命名规则。

表 9 UART的LL层API命名
API类别	函数名	函数描述
初始化类	ll_uart_init	初始化UART，设置波特率、数据位等参数。
初始化类	ll_uart_deinit	反初始化UART，恢复初始设置。
功能使能类	ll_uart_enable_fifo	控制及判断FIFO的使能状态。
	ll_uart_disable_fifo
	ll_uart_is_enabled_fifo
IO操作类	ll_uart_transmit_data8	发送单字节数据。
IO操作类	ll_uart_receive_data8	接收单字节数据。
参数设置类	ll_uart_set_parity	设置奇偶校验位。
参数设置类	ll_uart_get_parity	获取奇偶校验位。
标志与状态类	ll_uart_is_active_flag_rff	判断RFF标志是否置1。
	ll_uart_get_line_status_flag	获取Line状态。
	ll_uart_clear_line_status_flag	清除Line状态。
	ll_uart_get_it_flag	获取中断状态。
中断控制类	ll_uart_enable_it_rda	控制及判断RDA接收数据可用中断的状态。
	ll_uart_disable_it_rda
	ll_uart_is_enabled_it_rda
	ll_uart_enable_it	控制及判断多个中断状态。
	ll_uart_disable_it
	ll_uart_is_enabled_it
DMA控制类	无	UART的DMA请求由硬件管理，软件不需要设置。

驱动命名规则

基本命名规则

HAL驱动API命名规则

LL驱动API命名规则

扫描关注