Driver Naming Rules
The driver naming rules of GR551x SoCs comprise general naming rules, HAL API naming rules, and LL API naming rules.
General Naming Rules
The general naming rules apply to HAL and LL drivers, regulating files, modules, structures, and macros.
The rule details are listed in the table below.
Category | Name Format | Description | Example |
---|---|---|---|
File |
ccc_ddd_ppp.c/h ccc_ddd_ppp_ex.c/h |
Composed of SoC model, driver type, and peripheral name. For extension drivers, add a suffix, _ex, to the end of the name. |
gr55xx_hal_gpio.(c/h) gr55xx_hal_gpio_ex.(c/h) gr55xx_ll_gpio.(c/h) |
Module |
HAL_PPP_MODULE |
Composed of driver type and peripheral name ending with a suffix of _MODULE. |
HAL_I2C_MODULE |
Macro |
PPP_PARAM LL_PPP_PARAM |
A macro name should be in upper case. For LL driver macros, put LL_ before the peripheral name. |
UART_DATABITS_8 LL_UART_PARITY_NONE |
Structure |
ppp_sss_t ll_ppp_sss_t |
Composed of peripheral name and structure type with a suffix of _t. For LL driver structures, add ll_ to be beginning of the name. |
qspi_handle_t ll_uart_init_t |
Enum |
ddd_ppp_enumname_t |
Composed of driver type, peripheral name, and enumeration type ending with a suffix of _t. |
hal_uart_state_t |
Enumeration flag |
DDD_PPP_ENUM |
In upper case, composed of driver type, peripheral name, and flag meaning. |
HAL_UART_STATE_RESET |
Register |
REGISTERNAME |
A register name, in upper case, should comply with regulations in GR551x Datasheet (excessively long register names are presented in abbreviations). |
MODEM_CTRL |
Register structure |
ppp_regs_t |
Composed of peripheral name and a suffix of _regs_t. |
uart_regs_t |
Naming note:
- ccc: SoC family name. Example: gr55xx
- DDD/ddd: driver type. Example: HAL/hal and LL/ll
- PPP/ppp: peripheral name. Example: GPIO/gpio, QSPI/qspi, and UART/uart
- sss: structure type. Example: handle and init
- PARAM: peripheral parameter
- ENUM: enumeration flag
- REGISTERNAME: register name
Naming Rules of HAL Driver APIs
The table below lists the naming rules of HAL driver APIs.
API Type | Name Format | Description |
---|---|---|
Initialization |
hal_ppp_init hal_ppp_deinit |
An initialization API function name is composed of HAL driver type and peripheral name ending with _init or _deinit. |
I/O operation |
hal_ppp_operate |
Composed of HAL driver type, peripheral name, and operating mode (TX, RX, and callback). |
hal_ppp_command_operate |
For command-related APIs, add _command between the peripheral name and operating mode. |
|
hal_ppp_operate_it |
For I/O operation APIs in interrupt mode, add a suffix of _it. |
|
hal_ppp_operate_dma |
For I/O operation APIs in DMA mode, add a suffix of _dma. |
|
Interrupt handling and callback function |
hal_ppp_irq_handler |
Composed of HAL driver type and peripheral name ending with _irq_handler. |
hal_ppp_operate_cplt_callback |
For callback API functions that have been completed, add a suffix of _cplt_callback. |
|
hal_ppp_error_callback |
Composed of HAL driver type and peripheral name ending with _error_callback. |
|
Control |
hal_ppp_set_parameter hal_ppp_get_parameter |
Composed of HAL driver type, peripheral name, and parameter name. |
State and error |
hal_ppp_get_state hal_ppp_get_error |
Composed of HAL driver type, peripheral name, and state or error. |
- PPP/ppp: peripheral name. Example: QSPI/qspi and UART/uart
- operate: operating mode. Example: transmit/tx, receive/rx, and abort
- parameter: parameter name. Example: fifo_threshold and timeout
The table below is an example showing the HAL API naming rules when QSPI serves as a peripheral.
API Type | Function Name | Description |
---|---|---|
Initialization |
hal_qspi_init |
This function initializes QSPI and sets clocks and pin multiplexing. |
hal_qspi_deinit |
This function deinitializes QSPI and restores it to initial settings. |
|
hal_qspi_mspinit |
This function initializes GPIOs, NVIC interrupts, and DMA used by QSPI. |
|
hal_qspi_mspdeinit |
This function deinitializes GPIOs, NVIC interrupts, and DMA used by QSPI. |
|
I/O operation |
hal_qspi_command_transmit |
This function enables data transmission and reception in polling mode. |
hal_qspi_command_receive |
||
hal_qspi_command |
||
hal_qspi_transmit |
||
hal_qspi_receive |
||
hal_qspi_command_transmit_it |
This function enables data transmission and reception in interrupt mode. |
|
hal_qspi_command_receive_it |
||
hal_qspi_command_it |
||
hal_qspi_transmit_it |
||
hal_qspi_receive_it |
||
hal_qspi_command_transmit_dma |
This function enables data transmission and reception in DMA mode. |
|
hal_qspi_command_receive_dma |
||
hal_qspi_command_dma |
||
hal_qspi_transmit_dma |
||
hal_qspi_receive_dma |
||
hal_qspi_abort |
This function aborts ongoing data transmissions. |
|
hal_qspi_abort_it |
||
Interrupt handling and callback function |
hal_qspi_irq_handler |
Interrupt handler |
hal_qspi_tx_cplt_callback |
TX complete callback function |
|
hal_qspi_rx_cplt_callback |
RX complete callback function |
|
hal_qspi_error_callback |
Error detection callback function |
|
hal_qspi_abort_cplt_callback |
Abort complete callback function |
|
Control |
hal_qspi_set_timeout |
This function sets a timeout duration. |
hal_qspi_set_tx_fifo_threshold |
This function sets a FIFO threshold. |
|
hal_qspi_set_rx_fifo_threshold |
||
hal_qspi_get_tx_fifo_threshold |
This function reads a FIFO threshold. |
|
hal_qspi_get_rx_fifo_threshold |
||
State and error |
hal_qspi_get_state |
This function reads the peripheral state. |
hal_qspi_get_error |
This function reads error code. |
Naming Rules of LL Driver APIs
The table below lists the naming rules of LL driver APIs.
API Type | Name Format | Description |
---|---|---|
Initialization |
ll_ppp_init ll_ppp_deinit |
Composed of LL driver type and peripheral name ending with _init or _deinit. |
Feature enablement |
ll_ppp_enable_function ll_ppp_disable_function ll_ppp_is_enabled_function |
Composed of LL driver type, peripheral name, state (enable/disable/is_enabled), and function name. |
I/O operation |
ll_ppp_transmit_dataN ll_ppp_receive_dataN |
Composed of LL driver type, peripheral name, data transfer direction (transmit/receive), and data(bit width). |
Parameter setting |
ll_ppp_set_parameter ll_ppp_get_parameter |
Composed of LL driver type, peripheral name, parameter operation (set/get), and parameter name. |
Flag and state |
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 |
Two approaches are used to name a flag and state API:
|
Interrupt control |
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 |
Composed of LL driver type, peripheral name, state (enable/disable/is_enabled), it, and interrupt name. Functions without an interrupt name (example: ll_ppp_enable_it) can be used to control multiple interrupts. |
DMA control |
ll_ppp_enable_dma_req_tx/rx ll_ppp_disable_dma_req_tx/rx ll_ppp_is_enabled_dma_req_tx/rx |
Composed of LL driver type, peripheral name, state (enable/disable/is_enabled), and DMA request type. |
- PPP/ppp: peripheral name. Example: QSPI/qspi and UART/uart
- function: functionality name. Example: general_call (for I2C)
- N: data bit width, range: 8, 16, and 32
- parameter: parameter name. Example: fifo_threshold and timeout
- flagname: flag name. For example, the flag name of the STOP_DET interrupt in I2C is stop_det.
- flagtype: type of flag that needs to be cleared or got. Example: it and line_status
- itname: interrupt name. For example, the itname of the RDA interrupt in UART is rda.
The table below is an example showing the LL API naming rules when UART serves as a peripheral.
API Type | Function Name | Description |
---|---|---|
Initialization |
ll_uart_init |
This function initializes UART and sets parameters such as baud rate and data bit. |
ll_uart_deinit |
This function deinitializes UART and restores it to initial settings. |
|
Feature enablement |
ll_uart_enable_fifo |
This function controls and judges the FIFO enablement state. |
ll_uart_disable_fifo |
||
ll_uart_is_enabled_fifo |
||
I/O operation |
ll_uart_transmit_data8 |
This function enables the peripheral to transmit data by byte. |
ll_uart_receive_data8 |
This function enables the peripheral to receive data by byte. |
|
Parameter setting |
ll_uart_set_parity |
This function sets the odd-even parity bit. |
ll_uart_get_parity |
This function gets the odd-even parity bit. |
|
Flag and state |
ll_uart_is_active_flag_rff |
This function is used to judge whether the RFF flag is set. |
ll_uart_get_line_status_flag |
This function is used to get the line state. |
|
ll_uart_clear_line_status_flag |
This function is used to clear the line state. |
|
ll_uart_get_it_flag |
This function is used to get the interrupt state. |
|
Interrupt control |
ll_uart_enable_it_rda |
This function controls and judges the state of the received data available (RDA) interrupt. |
ll_uart_disable_it_rda |
||
ll_uart_is_enabled_it_rda |
||
ll_uart_enable_it |
This function controls and judges the states of multiple interrupts. |
|
ll_uart_disable_it |
||
ll_uart_is_enabled_it |
||
DMA control |
None |
The DMA requests of UART are managed by hardware. No settings are required on software. |