Chapter 4. API Guides
• The first argument to a HAL function has the xxx_hal_context_t * type. The HAL context type is used
to store information about a particular instance of the peripheral (i.e. the context instance). A HAL context is
initialized by the xxx_hal_init() function and can store information such as the following:
– The channel number of this instance
– Pointer to the peripheral’s (or channel’s) registers (i.e., a xxx_dev_t * type)
– Information about an ongoing transaction (e.g., pointer to DMA descriptor list in use)
– Some configuration values for the instance (e.g., channel configurations)
– Variables to maintain state information regarding the instance (e.g., a flag to indicate if the instance is
waiting for transaction to complete)
• HAL functions should not contain any OS primitives such as queues, semaphores, mutexes, etc. All synchro-
nization/concurrency should be handled at higher layers (e.g., the driver).
• Some peripherals may have steps that cannot be further abstracted by the HAL, thus will end up being a direct
wrapper (or macro) for an LL function.
• Some HAL functions may be placed in IRAM thus may carry an IRAM_ATTR or be placed in a separate
xxx_hal_iram.c
source file.
4.16 High-Level Interrupts
The Xtensa architecture has support for 32 interrupts, divided over 8 levels, plus an assortment of exceptions. On
the ESP32-S2, the interrupt mux allows most interrupt sources to be routed to these interrupts using the interrupt
allocator. Normally, interrupts will be written in C, but ESP-IDF allows high-level interrupts to be written in assembly
as well, allowing for very low interrupt latencies.
4.16.1 Interrupt Levels
Level Symbol Remark
1 N/A Exception and level 0 interrupts. Handled by ESP-IDF
2-3 N/A Medium level interrupts. Handled by ESP-IDF
4 xt_highint4 Normally used by ESP-IDF debug logic
5 xt_highint5 Free to use
NMI xt_nmi Free to use
dbg xt_debugexception Debug exception. Called on e.g. a BREAK instruction.
Using these symbols is done by creating an assembly file (suffix .S) and defining the named symbols, like this:
.section .iram1,"ax"
.global xt_highint5
.type xt_highint5,@function
.align 4
xt_highint5:
... your code here
rsr a0, EXCSAVE_5
rfi 5
For a real-life example, see the esp_system/port/soc/esp32s2/highint_hdl.S file; the panic handler interrupt is imple-
mented there.
4.16.2 Notes
• Do not call C code from a high-level interrupt; because these interrupts still run in critical sections, this can
cause crashes. (The panic handler interrupt does call normal C code, but this is OK because there is no intention
of returning to the normal code flow afterwards.)
• Make sure your assembly code gets linked in. If the interrupt handler symbol is the only symbol the rest of the
code uses from this file, the linker will take the default ISR instead and not link the assembly file into the final
project. To get around this, in the assembly file, define a symbol, like this:
Espressif Systems 1369
Submit Document Feedback
Release v4.4
To Next Page
Loading...
Need help?
General