M-HAL

This section introduces MT3620 CM4 common driver, including terms and acronyms, software architecture, file naming convention, API naming convention. More...

Overview

This section introduces MT3620 CM4 common driver, including terms and acronyms, software architecture, file naming convention, API naming convention.

Terms and acronyms

Acronyms	Definition
ADC	Analog-to-digital converter
EINT	External interrupt
DMA	Direct memory access
GPIO	General-Purpose Inputs-Outputs
GPIOIF	General-Purpose Inputs-Outputs Interface
GPT	Generic purpose timer
I2C	Inter-integrated circuit
I2S	Integrated Interchip Sound
PWM	Pulse-Width Modulation
SPI	Serial Peripheral Interface
UART	Universal asynchronous receiver/transmitter
WDT	Watchdog timer
MBOX	Mailbox

Overview of M-HAL SW Architecture

• Introduction
  MT3620 CM4 common driver has 5 layers as follows:
  User Application -> Framework -> OS-HAL -> M-HAL -> HDL
  • User Application: Performs a group of coordinated functions, tasks, or activities for the benefit of the user.
  • Framework: An abstraction in which software provides generic functionality to avoid HW design differences.
  • OS-HAL(OS Hardware Abstraction Layer): Provides high level APIs to upper layer(defined as OS-related driver).
  • M-HAL(MediaTek Hardware Abstraction Layer): Provides Fixed APIs(defined as Common Interface) to fully control the MediaTek HW.
  • HDL(Hardware Driving Layer): Handles low level related operations.
• M-HAL driver architecture
  
  • The M-HAL driver architecture is shown below:
    
    
  • The introduction of OSAI
    HDL and M-HAL are all defined to OS(operating system) disrelated, but these two layers still need to use OS interfaces, such as print log, read&write register, malloc/free buffer and so on.
    For these puposes, we define a software module and name it as OSAI(Operating System Abstract Interface).
    OSAI provides some fixed function group (which is OS disrelated) to help HW modules (such as SPI/I2C/UART/PWM...) to develop HDL and M-HAL SDK.
    Note:
    
    1. The function group which OSAI provided should not be called by OS-HAL and User Application.
    2. OSAI is the mapping of OS, it need to be reimplement if landing on a new OS.

File and API Naming Convention

• File naming convention
  
  • HDL
    The HDL header files are named as hdl_{module name}.h, such as hdl_spim.h.
    The HDL driver files are named as hdl_{module name}.c, such as hdl_spim.c.
    
  • M-HAL
    The M-HAL header files are named as mhal_{module name}.h, such as mhal_spim.h.
    The M-HAL driver files are named as mhal_{module name}.c, such as mhal_spim.c.
    
  • OS-HAL
    The OS-HAL header files are named as os_hal_{module name}.h, such as os_hal_spim.h.
    The OS-HAL driver files are named as os_hal_{module name}.c, such as os_hal_spim.c.
    
• API naming convention
  
  • External function names
    HDL: mtk_hdl_{module name}_xxx, such as mtk_hdl_spim_prepare_hw.
    M-HAL: mtk_mhal_{module name}_xxx, such as mtk_mhal_spim_prepare_hw.
    OS-HAL: mtk_os_hal_{module name}_xxx, such as mtk_os_hal_spim_ctlr_init.
    
  • Internal function names
    HDL: _mtk_hdl_{module name}_xxx.
    M-HAL: _mtk_mhal_{module name}_xxx.
    OS-HAL: _mtk_os_hal_{module name}_xxx.
    

Modules
	ADC
	This section describes the programming interfaces of the Analog-to-Digital Converter (ADC) M-HAL driver, including terms and acronyms, supported features, software architecture, details on how to use this driver, ADC define, enums, functions, structures and typedef.
	DMA
	This section introduces the Direct Memory Access (DMA) APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, 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 and functions.
	GPIO
	This section introduces the General-Purpose Input-Output (GPIO) APIs including terms and acronyms, supported features, software architecture details on how to use this driver, GPIO groups, enums and functions.
	GPIOIF
	This section introduces the General-Purpose Inputs-Outputs Interface (GPIOIF) APIs including terms and acronyms, supported features, software architecture details on how to use this driver, GPIOIF groups, enums and functions.
	GPT
	These sections introduce the Generic Purpose Timer (GPT), including terms and acronyms, supported features.
	I2C
	This section introduces the Inter-Integrated Circuit (I2C) APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, enums, structures and functions.
	I2S
	This section introduces the Integrated Interchip Sound (I2S) APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, enums, structures and functions.
	MBOX
	This section introduces the Mailbox (MBOX) APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, 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 defines, enums, functions and structures.
	SPIM
	This section introduces the Serial Peripheral Interface Master (SPIM) APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, enums, structures and functions.
	SPIS
	This section introduces the Serial Peripheral Interface Slave (SPIS) APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, 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, enums, structures and functions.
	WDT
	These sections introduce the Watchdog Timer (WDT), including terms and acronyms, supported features.