CN / EN
Doc Feedback
Thanks for your interest, welcome to contact us.
Thanks for your feedback
No matches were found 114page(s) matching the search query

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.

Table 5 General naming rules
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.

Table 6 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.

Note:
  • 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.

Table 7 Naming rules of HAL driver APIs for QSPI
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.

Table 8 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:
  • LL driver type, peripheral name, is_active/clear, _flag, and flag name. The segment of is_active and clear is used to judge the peripheral state or clear the flag.
  • LL driver type, peripheral name, get/clear, flag type, and _flag. The segment of get and clear is used to retrieve or clear a type of flag. Some peripherals do not contain a flag type.

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.

Note:
  • 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.

Table 9 Naming rules of LL driver APIs for UART
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.

Scan to follow

Open WeChat, use "Scan" to follow.