STM32F1 HAL

Started by tha, June 14, 2022, 09:22:55 AM

Previous topic - Next topic

tha

3.5 HAL driver rules

3.5.1 HAL API naming rules
The following naming rules ถูกใช้ใน HAL drivers:

•   The PPP prefix อ้างอิงถึง the peripheral functional mode และไม่ถึง the peripheral มันเอง. ตัวอย่างเช่น, ถ้า the USART,
     PPP สามารถเป็น USART, IRDA, UART or SMARTCARD ขึ้นอยู่กับ the peripheral mode.
•   The constants ที่ใช้ใน one file ถูกกำหนดภายใน file นี้. A constant ที่ใช้ใน several files ถูกกำหนดใน a header file. ทุก
     constants ถูกเขียนด้วยตัวพิมพ์ใหญ่, ยกเว้นสำหรับ peripheral driver function parameters.
•   typedef variable names ควรถูกต่อท้ายด้วย _TypeDef.
•   Registers ที่ถือว่าเป็นค่าคงที่. ในกรณีส่วนใหญ่, ชื่อของพวกมันจะเป็นตัวพิมพ์ใหญ่และใช้ตัวย่อที่เหมือนกันกับใน the STM32F1
     reference manuals.
•   Peripheral registers ถูกประกาศใน the PPP_TypeDef structure (ตัวอย่างเช่น ADC_TypeDef) ใน the CMSIS header:
     stm32f1xxx.h ตรงกันกับ stm32f100xb.h, stm32f100xe.h, stm32f101x6.h, stm32f101xb.h,
     stm32f101xe.h, stm32f101xg.h, stm32f102x6.h, stm32f102xb.h, stm32f103x6.h, stm32f103xb.h,
     stm32f103xe.h, stm32f103xg.h, stm32f105xc.h and stm32f107xc.h.

tha

•   Peripheral function names จะขึ้นต้นโดย HAL_, จากนั้น the corresponding peripheral acronym ใน uppercase ถูกตามโดย
     an underscore. The first letter ของแต่ละคำจะเป็นตัวพิมพ์ใหญ่ (ตัวอย่างเช่น HAL_UART_Transmit()). เพียง one underscore
     ถูกยอมให้ใน a function name เพื่อแยก the peripheral acronym จากที่เหลือของ the function name.
•   The structure containing the PPP peripheral initialization parameters มีชื่อว่า PPP_InitTypeDef (ตัวอย่างเช่น
     ADC_InitTypeDef).
•   The structure containing the Specific configuration parameters for the PPP peripheral มีชื่อว่า
     PPP_xxxxConfTypeDef (ตัวอย่างเช่น ADC_ChannelConfTypeDef).
•   Peripheral handle structures มีชื่อว่า PPP_HandleTypedef (ตัวอย่างเช่น  DMA_HandleTypeDef)

tha

•   The functions ที่ใช้เพื่อกำหนดค่าเริ่มต้น the PPP peripheral สอดคล้องกันกับ parameters ที่ระบุใน PPP_InitTypeDef มีชื่อว่า
     HAL_PPP_Init (ตัวอย่างเช่น HAL_TIM_Init()).
•   The functions ที่ใช้เพื่อรีเซ็ต the PPP peripheral registers ไปเป็นค่าเริ่มต้นของมันมีชื่อว่า HAL_PPP_DeInit (e.g.
     HAL_TIM_DeInit()).
•   The MODE suffix หมายถึง the process mode, ซึ่งสามารถเป็น polling, interrupt or DMA. ตัวอย่างเช่น, เมื่อ the DMA ถูกใช้
     นอกเหนือจาก the native resources, the function นี้ควรถูกเรียก: HAL_PPP_Function_DMA().
•   The Feature prefix ควรอ้างอิงถึง the new feature.
     Example: HAL_ADC_Start() อ้างอิงถึง the injection mode


tha

3.5.2 HAL general naming rules
•   สำหรับ the shared and system peripherals, ไม่มี handle or instance object ถูกใช้. กฎนี้นำไปใช้กับ the following
     peripherals:
     –   GPIO
     –   SYSTICK
     –   NVIC
     –   RCC
     –   FLASH.

Example: The HAL_GPIO_Init() ต้องการเฉพาะ the GPIO address และ configuration parameters ของมัน.

tha

•   The macros ที่จัดการ interrupts and specific clock configurations ถูกกำหนดในแต่ละ peripheral/module driver. มาโคร
     เหล่านี้จะถูกส่งออกใน the peripheral driver header files ดังนั้นพวกมันสามารถถูกใช้โดย the extension file. รายการของมาโคร
     เหล่านี้ถูกกำหนดไว้ข้างล่าง:

Note:  รายการนี้ไม่ครบถ้วนสมบูรณ์ และมาโครอื่นที่เกี่ยวข้องกับ peripheral features สามารถถูกเพิ่ม, ดังนั้นพวกมันสามารถถูกใช้ใน the
          user application


tha

•   NVIC and SYSTICK คือ two Arm® Cortex® core features. The APIs ที่เกี่ยวข้องกับคุณลักษณะเหล่านี้ถูกวางอยู่ใน the
     stm32f1xx_hal_cortex.c file.
•   เมื่อ a status bit หรือ a flag ถูกอ่านจาก registers, มันถูกประกอบด้วย shifted values ขึ้นอยู่กับ the number of read values
     และขนาดของมัน. ในกรณีนี้, the returned status width เป็น 32 bits. Example : STATUS = XX | (YY << 16) or
     STATUS = XX | (YY << 8 ) | (YY << 16) | (YY << 24)".
•   The PPP handles ใช้ได้ก่อนการใช้ the HAL_PPP_Init() API. The init function ดำเนินการตรวจสอบก่อนการแก้ไข the handle
     fields.

•   The macros ที่กำหนดไว้ข้างล่างถูกใช้:
     –   Conditional macro:

     –   Pseudo-code macro (หลาย instructions macro):

tha

3.5.3 HAL interrupt handler and callback functions
นอกจาก the APIs, HAL peripheral drivers ยังรวมถึง:
•   HAL_PPP_IRQHandler() peripheral interrupt handler ที่ควรถูกเรียกจาก stm32f1xx_it.c
•   User callback functions.

The user callback functions ถูกกำหนดเป็น empty functions ด้วย "weak" attribute. พวกมันต้องถูกกำหนดใน the user code.

มีสามชนิดของ user callbacks functions:
•   Peripheral system level initialization/ de-Initialization callbacks: HAL_PPP_MspInit() and HAL_PPP_MspDeInit
•   Process complete callbacks : HAL_PPP_ProcessCpltCallback
•   Error callback: HAL_PPP_ErrorCallback.


tha

3.6 HAL generic APIs

The generic APIs จัดให้มี common generic functions นำไปใช้กับทุก STM32 devices. พวกมันประกอบด้วย four APIs groups:
•   Initialization and de-initialization functions:HAL_PPP_Init(), HAL_PPP_DeInit()
•   IO operation functions: HAL_PPP_Read(), HAL_PPP_Write(),HAL_PPP_Transmit(), HAL_PPP_Receive()
•   Control functions: HAL_PPP_Set (), HAL_PPP_Get ().
•   State and Errors functions: HAL_PPP_GetState (), HAL_PPP_GetError ()

สำหรับบาง peripheral/module drivers, กลุ่มเหล่านี้ถูกแก้ไขขึ้นอยู่กับ the peripheral/module implementation.

Example: ใน the timer driver, การจัดกลุ่ม API จะขึ้นอยู่กับ timer features (PWM, OC, IC...).

The initialization and de-initialization functions ช่วยให้การกำหนดค่าเริ่มต้น a peripheral และการกำหนดค่า the low-level resources, หลักๆ clocks, GPIO, alternate functions (AF) และบางที DMA and interrupts. The HAL_DeInit()function คืน the peripheral default state, ปล่อยฟรี the low-level resources และลบการพึ่งพาโดยตรงกับ the hardware.

The IO operation functions ดำเนินการ a row access ไปยัง the peripheral payload data ใน write and read modes.

The control functions ถูกใช้เพื่อเปลี่ยนแบบไดนามิกค์ the peripheral configuration และเซ็ต operating mode อื่น.

The peripheral state and errors functions ช่วยให้สามารถดึง the peripheral and data flow states ในขณะทำงาน, และระบุประเภทของ errors ที่เกิดขึ้น. ตัวอย่างข้างล่างอ้างอิงจาก the ADC peripheral. The list of generic APIs ไม่ได้ละเอียดถี่ถ้วน. มันถูกให้เป็นตัวอย่างเท่านั้น.