HAL

This section introduces the HAL driver APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, HAL function groups, enums, structures and functions. More...

Overview

This section introduces the HAL driver APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, HAL function groups, enums, structures and functions.

Terms and acronyms

Acronyms	Definition
ACCDET	Accessory detector
ADC	Analog-to-digital converter
AES	Advanced Encryption Standard
CMSIS	Cortex Microcontroller Software Interface Standard
CTP	Capacitive Touch Panel
EINT	External interrupt
GDMA	General direct memory access
GPC	General purpose counter
GPIO	General purpose Input Output
GPT	General purpose timer
I2C	Inter-integrated circuit
I2S	Inter-integrated sound
LCD	Liquid Crystal Display
LCM	LCD Module
MD5	Message-Digest Algorithm
MPU	Memory protect unit
PWM	Pulse Width Modulation
RTC	Real-time clock
SD	Secure Digital Memory Card
SDIO	Secure Digital Input and Output
SHA	Secure Hash Algorithm
SPI	Serial Peripheral Interface
UART	Universal asynchronous receiver/transmitter
USB	Universal Serial Bus
WDT	Watchdog timer
TRNG	True random number generator

Overview of HAL drivers

• Introduction
  MediaTek LinkIt™ SDK hardware abstraction layer (HAL) driver is embedded software ensuring maximized portability across IoT portfolio designed for MediaTek LinkIt for real-time OS (RTOS) development platform.
  The HAL driver includes:
  
  • Drivers for the peripheral modules, such as UART and I2C.
    
  • Drivers for the system modules, such as CACHE, MPU and FLASH.
    
  • APIs of the modules.
    The HAL driver has both standard and advanced features and is easy to use. It makes the upper hardware abstraction layer portable.
    The HAL layer provides a generic set of APIs to interact with the upper layers, such as application, middleware and the OS. The APIs are defined interfaces for MediaTek IoT portfolio, so the upper layer written with the HAL API is portable across the MediaTek IoT platforms.
    The HAL driver covers rich modules, including all peripheral modules, such as UART, I2C and SPI. It also includes number of system modules, such as CACHE, MPU, FLASH and DMA.
    The HAL complies with the general naming convention and common coding style. Each module of the HAL has its distinctive folder structure along with supporting examples.
• HAL driver architecture
  The HAL driver architecture is shown below:
  
  
• HAL folder structure and file inclusion model
  
  • HAL folder structure
    The HAL module folder structure is shown below:
    
    • Driver: All common driver files, such as board driver, HAL driver and CMSIS.
      
    • Driver/board: The driver files that are associated with the board, such as CTP or LCM.
      
    • Driver/chip/inc: The public header files of the HAL.
      
    • Driver/chip/mtxxxx: The driver files that are specific to the chipset, such as UART, I2C, GPT, PWM, WDT, etc.
      
    • Driver/CMSIS: The files that are associated with the CMSIS-CORE.
      
  • File inclusion model
    
    
• HAL driver rules
  
  • HAL file naming convention
    The HAL public header files are named as hal_{feature}.h, such as hal_adc.h.
    The HAL driver files are all in driver/chip/mtxxxx/inc and driver/chip/mtxxxx/src, they are named as hal_{feature}.c or hal_{feature}_{sub_feature}.c, such as hal_cache.c and hal_cache_internal.c.
    
  • HAL public API naming convention
    

    	naming convention
    function names	hal_{feature}_{sub_feature}(), such as hal_uart_init()
    enum names	Type name:hal_{feature}_{sub_feature}_t, such as hal_uart_baudrate_t. Enum member names:HAL_{FEATURE}_{SUB_FEATURE}, such as HAL_UART_BAUDRATE_110.
    struct name	Type name:hal_{feature}_{sub_feature}_t,such as hal_uart_config_t. Struct member names must be lowercase.
    macro names	HAL_{FEATURE}_{SUB_FEATURE}, such as HAL_NVIC_QUERY_EXCEPTION_NUMBER
    function pointer names	hal_{feature}_{sub_feature}_t(), such as void (*hal_uart_callback_t)().

• HAL configuration
  
  • hal_feature_config.h
    Every project should include hal_feature_config.h for HAL configuration.
    If certain HAL modules are not used, they can be removed from the feature options by undefining the macro, such as undefine the option of HAL_ADC_MODULE_ENABLED.
    For customized parameter settings, such as on the LinkIt 2523, if MTK_SYSTEM_CLOCK_208M, MTK_SYSTEM_CLOCK_104M or MTK_SYSTEM_CLOCK_26M is defined, the system MCU frequency will be set to 208MHz, 104MHz or 26MHz at the bootup.
    
  • hal_feature_config_template.h
    This is a template file in driver/chip/mtxxxx/inc. It can be referred to when creating a new hal_feature_config.h.
    
    

HAL Driver Model

Some of the drivers can operate in two modes: polling and interrupt. The UART HAL driver, for example, can operate in polling and interrupt modes during data communication. The polling mode is suitable for read and write operations of small amount of data in low frequency. The interrupt mode is suitable for read and write operations of small amount of data in high frequency. In UART DMA mode, for example, an interrupt is triggered once the DMA is complete.

• Polling mode architecture
  Most of the driver modules support the polling mode, which is the basic feature in HAL.
  For example, call the hal_gpt_delay_ms() API to apply a millisecond time delay in the GPT. The GPT HAL driver will poll the GPT hardware, if the time delay is reached.
  The polling mode driver architecture is shown below:
  

• Interrupt mode architecture
  To improve the portability, the HAL driver hides the OS dependence by preventing the upper layer to call the OS level services directly. The HAL drivers uses an interrupt handler to provide the upper layer with a callback mechanism.

  To use the interrupt handler of a driver module, a callback should be registered with the interrupt handler. When the interrupt occurs, the callback is invoked in Cortex-M4 handler mode. Call the hal_uart_send_dma() API to send data in the UART interrupt mode (UART DMA mode). The UART HAL driver will copy the data to DMA buffer and start the DMA operation while the DMA sends data to the UART hardware. When the DMA operation completes, the DMA interrupt is issued. The UART HAL driver will invoke the user callback in interrupt handler to notify that the data has been sent out by the UART. Another example of the interrupt is the GPT interrupt mode. Call the hal_gpt_start_timer_ms() API to start a timer. When the timer expires, the GPT hardware issues an interrupt. Then the GPT HAL driver will invoke the user callback in interrupt handler to notify that the timer has expired. The interrupt mode driver architecture is shown below:

  

  All HAL APIs are thread-safe and available for ISR. Developers may call HAL APIs in any FreeRTOS task or in an ISR.
  However, some hardware have limited resources, and the corresponding APIs return "ERROR_BUSY" status when there is a resource conflict due to the re-entrance. Developers should always check the return values from HAL APIs.
  For example, I2C master supports only one user at a time, so hal_i2c_master_init() returns HAL_I2C_STATUS_ERROR_BUSY when another user is using I2C master.
  

Modules
	ADC
	This section describes the programming interfaces of the ADC HAL driver.
	AES
	This section introduces the AES driver APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, AES function groups, enums, structures and functions.
	CACHE
	This section describes the programming interfaces of the CACHE controller.
	DES
	This section introduces the DES driver APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, DES function groups, enums, structures and functions.
	EINT
	This section introduces the External Interrupt Controller(EINT) APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, EINT function groups, enums, structures and functions.
	FLASH
	This section describes the programming interfaces of the FLASH driver.
	GDMA
	This section introduces the General Direct Memeory Access(GDMA) APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, GDMA function groups, enums, structures and functions.
	GPC
	This section introduces the General Purpose Counter(GPC) APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, GPC function groups, enums, structures and functions.
	GPIO
	This section provides introduction to the General Purpose Input Output (GPIO) APIs, including terms and acronyms, features, architecture, how to use APIs, the GPIO function groups, enums, structures and functions.
	GPT
	This section introduces the General Purpose Timer(GPT) driver APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, GPT function groups, enums, structures and functions.
	I2C_MASTER
	I2S
	This section introduces the I2S APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, I2S function groups, enums, structures and functions.
	IRRX
	This section introduces the Infrared Receiver(IRRX) APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, IRRX function groups, enums, structures and functions.
	IRTX
	This section introduces the Infrared Transmitter(IRTX) APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, IRTX function groups, enums, structures and functions.
	MD5
	This section introduces the MD5 driver APIs including terms and acronyms, supported features, software architecture, details on how to use this driver.
	NVIC
	This section introduces the NVIC HAL APIs including terms and acronyms, details on how to use this driver, supported features, enums, structures and functions.
	PWM
	This section introduces the Pulse-Width Modulation(PWM) APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, PWM function groups, enums, structures and functions.
	RTC
	This section introduces the Real-Time Clock (RTC) APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, enums, structures and functions.
	SHA
	This section introduces the SHA driver APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, SHA function groups, enums, structures and functions.
	SLEEP_MANAGER
	This section introduces the Sleep Manager driver APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, Sleep Manager function groups, enums, structures and functions.
	SPI_MASTER
	This section introduces the Serial Peripheral Interface Master (SPI_Master) APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, enums, structures and functions.
	SPI_SLAVE
	This section introduces the SPI Slave APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, enums, structures and functions.
	TRNG
	This section introduces the True Randam Number Generator(TRNG) APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, TRNG function groups, enums, structures and functions.
	UART
	This section introduces the Universal Asynchronous Receiver/Transmitter(UART) APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, UART function groups, enums, structures and functions.
	WDT