Espressif ESP32-S2 User Manual

Chapter 4. API Guides
Table 2: Hardware Abstraction Header Files
Include Directive Target
Spe-
cific
Description
#include 'soc/
xxx_caps.h"
Y This header contains a list of C macros specifying the various capabilities of
the ESP32-S2’s peripheral xxx. Hardware capabilities of a peripheral include
things such as the number of channels, DMA support, hardware FIFO/buffer
lengths, etc.
#include "soc/
xxx_struct.h"
#include "soc/
xxx_reg.h"
Y The two headers contain a representation of a peripheral’s registers in C struc-
ture and C macro format respectively. Users can operate a peripheral at the
register level via either of these two header files.
#include "soc/
xxx_pins.h"
Y If certain signals of a peripheral are mapped to a particular pin of the ESP32-
S2, their mappings are defined in this header as C macros.
#include "soc/
xxx_periph.h"
N This header is mainly used as a convenience header file to automatically include
xxx_caps.h, xxx_struct.h, and xxx_reg.h.
#include "hal/
xxx_types.h
N This header contains type definitions and macros that are shared among the
LL, HAL, and driver layers. Moreover, it is considered public API thus can
be included by the application level. The shared types and definitions usually
related to non-implementation specific concepts such as the following:
• Protocol related types/macros such a frames, modes, common bus
speeds, etc.
• Features/characteristics of an xxx peripheral that are likely to be present
on any implementation (implementation-independent) such as channels,
operating modes, signal amplification or attenuation intensities, etc.
#include "hal/
xxx_ll.h"
Y This header contains the Low Level (LL) Layer of hardware abstraction. LL
Layer API are primarily used to abstract away register operations into readable
functions.
#include "hal/
xxx_hal.h"
Y The Hardware Abstraction Layer (HAL) is used to abstract away peripheral
operation steps into functions (e.g., reading a buffer, starting a transmission,
handling an event, etc). The HAL is built on top of the LL Layer.
#include "driver/
xxx.h"
N The driver layer is the highest level of ESP-IDF’s hardware abstraction. Driver
layer API are meant to be called from ESP-IDF applications, and internally
utilize OS primitives. Thus, driver layer API are event-driven, and can used in
a multi-threaded environment.
4.15.2 LL (Low Level) Layer
The primary purpose of the LL Layer is to abstract away register field access into more easily understandable functions.
LL functions essentially translate various in/out arguments into the register fields of a peripheral in the form of get/set
functions. All the necessary bit shifting, masking, offsetting, and endianness of the register fields should be handled
by the LL functions.
//Inside xxx_ll.h
static inline void xxx_ll_set_baud_rate(xxx_dev_t *hw,
xxx_ll_clk_src_t clock_source,
uint32_t baud_rate) {
uint32_t src_clk_freq = (source_clk == XXX_SCLK_APB) ? APB_CLK_FREQ : REF_CLK_
,→FREQ;
uint32_t clock_divider = src_clk_freq / baud;
// Set clock select field
hw->clk_div_reg.divider = clock_divider >> 4;
// Set clock divider field
hw->config.clk_sel = (source_clk == XXX_SCLK_APB) ? 0 : 1;
(continues on next page)
Espressif Systems 1367
Submit Document Feedback
Release v4.4

Espressif ESP32-S2 Specifications

General

Brand	Espressif
Model	ESP32-S2
Category	Single board computers
Language	English