STM32F1 HAL

3.12.4.2 Error management
The HAL drivers จัดให้มีใช้ a check บนรายการต่อไปนี้:
•   Valid parameters: สำหรับบางขบวนการ the used parameters ควรถูกต้องและกำหนดไว้แล้ว, มิฉะนั้น the system อาจขัดข้องหรือเข้าสู่สถานะไม่ได้กำหนด พารามิเตอร์ที่สำคัญเหล่านี้ได้รับการตรวจสอบก่อนถูกใช้งาน (ดูตัวอย่างด้านล่าง).


•   Valid handle: the PPP peripheral handle เป็น the most important argument เนื่องจากมันเก็บ the PPP driver vital parameters. มันถูกตรวจเช็คเสมอในจุดเริ่มต้นของ the HAL_PPP_Init() function.


•   Timeout error: the following statement ถูกใช้เมื่อ a timeout error เกิดขึ้น:


เมื่อ an error เกิดขึ้นในระหว่าง a peripheral process, HAL_PPP_Process () ส่งคืนกลับด้วย a HAL_ERROR status. The HAL PPP driver จัดให้มีใช้ the HAL_PPP_GetError () เพื่อยอมให้การดึงที่มาของ the error.


ในทุก peripheral handles, a HAL_PPP_ErrorTypeDef ถูกกำหนดและถูกใช้เพื่อเก็บ the last error code.


The error state และ the peripheral global state ถูกอัฟเดตก่อนการส่งคืนกลับ an error เสมอ:


HAL_PPP_GetError () ต้องถูกใช้ใน interrupt mode ใน the error callback:

3.12.4.3 Run-time checking
The HAL จัดให้มีใช้ run-time failure detection โดยการตรวจเช็ค the input values ของทุก HAL driver functions. The runtime checking ถูกทำให้สำเร็จโดยการใช้ an assert_param macro. macro นี้ถูกใช้ในทุก the HAL driver functions ซึ่งมี an input parameter. มันช่วยให้ตรวจสอบได้ว่า the input value อยู่ภายใน the parameter allowed values.

เพื่อเปิดใช้งาน the run-time checking, ใช้ the assert_param macro, และทิ้ง the define USE_FULL_ASSERT ไว้ไม่คอมเม้นต์ออกใน stm32f1xx_hal_conf.h file.


ถ้า the expression ที่ส่งผ่านไปยัง the assert_param macro ล้มเหลว, the assert_failed function ถูกเรียกและส่งคืนกลับ the name of the source file และ the source line number ของ the call ที่ล้มเหลวนั้น. ถ้า the expression เป็นจริง, ไม่มีค่าใดถูกส่งคืนกลับ.

The assert_param macro ถูกจัดให้มีใช้ใน stm32f1xx_hal_conf.h:


The assert_failed function ถูกจัดให้มีใช้ใน the main.c file หรือใน any other user C file:


Note:   เนื่องจากนำสู่โอเวอร์เฮดของ run-time checking, ขอแนะนำให้ใช้มันในระหว่าง application code development and
           debugging, และเอามันออกจาก the final application เพื่อปรับปรุง code size and speed ให้ดีขึ้น.

4   Overview of low-layer drivers

The low-layer (LL) drivers ถูกออกแบบเพื่อนำเสนอ a fast light-weight expert-oriented layer ซึ่งจะใกล้ชิดกับ the hardware มากกว่า the HAL. ตรงกันข้ามกับ the HAL, LL APIs ไม่ถูกจัดให้มีสำหรับ peripherals ที optimized access ไม่ใช่ a key feature, หรือเหล่านั้นที่ต้องการ heavy software configuration และ/หรือ complex upper-level stack (อย่างเช่น USB).

The LL drivers feature:
•   A set of functions เพื่อกำหนดค่าเริ่มต้น peripheral main features สอดคล้องกันกับ the parameters ที่ระบุใน data structures
•   A set of functions ที่ใช้เพื่อเติมการกำหนดค่าเริ่มต้น data structures ด้วย the reset values ของแต่ละฟิลด์
•   Functions ดำเนินการ peripheral de-initialization (peripheral registers คืนกลับไปยังค่าเริ่มต้นของมัน)
•   A set of inline functions สำหรับ direct and atomic register access
•   เป็นอิสระอย่างเต็มที่จาก HAL เนื่องจาก LL drivers สามารถถูกใช้อย่างใดอย่างหนึ่ง in standalone mode (โดยไม่มี HAL drivers)
     หรือ in mixed mode (พร้อมด้วย HAL drivers)
•   ครอบคลุมอย่างเต็มที่ the supported peripheral features.

The low-layer drivers จัดให้มี hardware services ขึ้นอยู่กับ the available features ของ the STM32 peripherals. การบริการเหล่านี้สะท้อน the hardware capabilities อย่างชัดเจนและจัดให้มี one-shot operations ที่ต้องถูกเรียกตามติด the programming model ที่อธิบายใน the microcontroller line reference manual. ด้วยเหตุนี้, the LL services ไม่จัดให้มีใช้ขบวนการใดๆและไม่ต้องการ any additional memory resources เพื่อบันทึก states, counter หรือ data pointers ของพวกมัน: ทุก the operations ถูกดำเนินการโดยการเปลี่ยน the associated peripheral registers content.

4.1   Low-layer files

The low-layer drivers ถูกสร้างรอบๆ header/C files (หนึ่งต่อแต่ละ supported peripheral) บวก five header files สำหรับบาง System and Cortex related features.


Note:   ไม่มี configuration file สำหรับ the LL drivers.





Application files ต้องรวมเฉพาะ the used low-layer driver header files.

4.2 Overview of low-layer APIs and naming rules

4.2.1 Peripheral initialization functions
The LL drivers เสนอ three sets of initialization functions. พวกมันถูกกำหนดใน stm32f1xx_ll_ppp.c file:
•   A set of functions เพื่อกำหนดค่าเริ่มต้น peripheral main features สอดคล้องกันกับ the parameters ที่ระบุใน data structures
•   A set of functions ที่ใช้เพื่อเติมการกำหนดค่าเริ่มต้น data structures ด้วย the reset values ของแต่ละฟิลด์
•   Functions สำหรับ peripheral de-initialization (peripheral registers คืนกลับไปยังค่าเริ่มต้นของมัน)

The definition ของ LL initialization functions เหล่านี้และ associated resources (structure, literals and prototypes) มีข้อแม้โดย a compilation switch: USE_FULL_LL_DRIVER. เพื่อใช้ฟังชั่นเหล่านี้, switch นี้ต้องถูกเพิ่มใน the toolchain compiler preprocessor หรือไปยัง any generic header file ซึ่งถูกประมวลผลก่อน the LL drivers.

ตารางข้างล่างแสดงรายการของ the common functions ที่จัดให้มีสำหรับทุก the supported peripherals:


Additional functions มีให้ใช้งานสำหรับบาง peripherals (ดูที่ Table 18. Optional peripheral initialization functions ).

4.2.1.1 Run-time checking
เหมือนกับ HAL drivers, LL initialization functions จัดให้มีใช้ run-time failure detection โดยการตรวจเช็ค the input values ของทุก LL driver functions. สำหรับรายละเอียดที่มากขึ้นโปรดดู Section 3.12.4.3 Run-time checking.
เมื่อใช้ the LL drivers ใน standalone mode (โดยไม่มีการเรียก HAL functions), the following actions ถูกต้องการเพื่อใช้ run-time checking:
1.   ก๊อปปี้ stm32_assert_template.h ไปยัง the application folder และเปลี่ยนชื่อมันเป็น stm32_assert.h. ไฟล์นี้กำหนด the
      assert_param macro ซึ่งถูกใช้เมื่อ run-time checking ถูกเปิดใช้งาน.
2.   รวม stm32_assert.h file ไว้ภายใน the application main header file.
3.   เพิ่ม the USE_FULL_ASSERT compilation switch ใน the toolchain compiler preprocessor หรือใน any generic
      header file ซึ่งถูกประมวลผลก่อน the stm32_assert.h driver.

Note:   Run-time checking ไม่มีให้ใช้งานสำหรับ LL inline functions.

4.2.2 Peripheral register-level configuration functions
บนส่วนบนของ the peripheral initialization functions, the LL drivers นำเสนอ a set of inline functions สำหรับ direct atomic register access. รูปแบบของพวกมันเป็นดังต่อไปนี้:


The “Function” naming ถูกกำหนดขึ้นอยู่กับ the action category:
•   Specific Interrupt, DMA request and status flags management: Set/Get/Clear/Enable/Disable flags on
     interrupt and status registers



Note: BITNAME อ้างอิงถึง the peripheral register bit name ตามที่อธิบายใน the product line reference manual.

•   Peripheral clock activation/deactivation management: Enable/Disable/Reset a peripheral clock

Note: 'x' ตรงกันกับ the group index และอ้างอิงถึง the index of the modified register บน a given bus. 'bus' ตรงกันกับ the bus name.

•   Peripheral activation/deactivation management : Enable/disable a peripheral or activate/deactivate specific
     peripheral features


•   Peripheral configuration management : Set/get a peripheral configuration settings


•   Peripheral register management : Write/read the content of a register/retrun DMA relative register address

Note: The Propriety คือ a variable ที่ใช้เพื่อระบุ the DMA transfer direction หรือ the data register type.