Hal (Hardware Abstraction Layer) - Espressif ESP32-S2 Programming Manual

Chapter 4. API Guides
}
static inline uint32_t
return hw->status_reg.rx_cnt;
}
The code snippet above illustrates typical LL functions for a peripheral xxx. LL functions typically have the following
characteristics:
• All LL functions are defined as static inline so that there is minimal overhead when calling these
functions due to compiler optimization.
• The first argument should be a pointer to a xxx_dev_t type. The xxx_dev_t type is a structure repre-
senting the peripheral's registers, thus the first argument is always a pointer to the starting address of the
peripheral's registers. Note that in some cases where the peripheral has multiple channels with identical
register layouts, xxx_dev_t *hw may point to the registers of a particular channel instead.
• LL functions should be short and in most cases are deterministic. In other words, the worst case runtime of
the LL function can be determined at compile time. Thus, any loops in LL functions should be finite bounded;
however, there are currently a few exceptions to this rule.
• LL functions are not thread safe, it is the responsibility of the upper layers (driver layer) to ensure that registers
or register fields are not accessed concurrently.

4.15.3 HAL (Hardware Abstraction Layer)

The HAL layer models the operational process of a peripheral as a set of general steps, where each step has an
associated function. For each step, the details of a peripheral' s register implementation (i.e., which registers need to
be set/read) are hidden (abstracted away) by the HAL. By modelling peripheral operation as a set of functional steps,
any minor hardware implementation differences of the peripheral between different targets or chip versions can be
abstracted away by the HAL (i.e., handled transparently). In other words, the HAL API for a particular peripheral
will remain mostly the same across multiple targets/chip versions.
The following HAL function examples are selected from the Watchdog Timer HAL as each function maps to one
of the steps in a WDT's operation life cycle, thus illustrating how a HAL abstracts a peripheral's operation into
functional steps.
// Initialize one of the WDTs
void wdt_hal_init(wdt_hal_context_t *hal, wdt_inst_t wdt_inst,
bool enable_intr);
→
// Configure a particular timeout stage of the WDT
void wdt_hal_config_stage(wdt_hal_context_t *hal, wdt_stage_t stage,
timeout, wdt_stage_action_t behavior);
→
// Start the WDT
void wdt_hal_enable(wdt_hal_context_t *hal);
// Feed (i.e., reset) the WDT
void wdt_hal_feed(wdt_hal_context_t *hal);
// Handle a WDT timeout
void wdt_hal_handle_intr(wdt_hal_context_t *hal);
// Stop the WDT
void wdt_hal_disable(wdt_hal_context_t *hal);
// De-initialize the WDT
void wdt_hal_deinit(wdt_hal_context_t *hal);
HAL functions will generally have the following characteristics:
Espressif Systems
xxx_ll_get_rx_byte_count(xxx_dev_t *hw) {
1368
Submit Document Feedback
(continued from previous page)
uint32_t prescaler,␣
uint32_t␣
Release v4.4