1. :ref:`hw-abstraction-architecture`
2. :ref:`hw-abstraction-ll-layer`
3. :ref:`hw-abstraction-hal-layer`

硬件抽象 API（不包括驱动程序和 ``xxx_types.h``）尚处于试验阶段，因此不能算作公共 API。硬件抽象 API 不遵守 ESP-IDF 版本控制方案的 API 名称更改规范。换言之，非主要 ESP-IDF 版本迭代时，硬件抽象 API 的名称可能会更改。

尽管本文档主要关注外设的硬件抽象，如 UART、SPI、I2C 等，但硬件抽象可以扩展到外设以外其他的硬件部分，如某些 CPU 功能也进行了部分抽象。

* - 包含 |br| 指令
  - 特定 |br| 目标
  - 描述
* - ``#include 'soc/xxx_caps.h"``
  - 是
  - 此头文件包含了 C 宏列表，指明 {IDF_TARGET_NAME} 外设 ``xxx`` 的各种功能。外设的硬件功能包括通道数量、DMA 支持、硬件 FIFO/缓冲区长度等。
* - ``#include "soc/xxx_struct.h"`` |br| ``#include "soc/xxx_reg.h"``
  - 是
  - 这两个头文件分别以 C 结构体和 C 宏的形式表示外设寄存器，支持通过其中任一头文件，在寄存器级别上操作外设。
* - ``#include "soc/xxx_pins.h"``
  - 是
  - 如果某些外设的信号映射到 {IDF_TARGET_NAME} 的特定管脚上，则该头文件中以 C 宏的形式定义了它们的映射关系。
* - ``#include "soc/xxx_periph.h"``
  - 否
  - 此头文件主要是为了方便，可以自动包含 ``xxx_caps.h``、``xxx_struct.h`` 和 ``xxx_reg.h``。
* - ``#include "hal/xxx_types.h``
  - 否
  - 此头文件包含了在 LL、HAL 和驱动层间共享的类型定义和宏。此外，作为公共 API，该头文件可以包含在应用层中。共享的类型和定义通常与具体的实现无关，例如：

      - 协议相关的类型/宏，如帧、模式、常见总线速度等。
      - ``xxx`` 外设可能存在的特性/特点，可能存在于任何实现上（与实现无关），例如通道、工作模式、信号放大或衰减强度等。
* - ``#include "hal/xxx_ll.h"``
  - 是
  - 此头文件包含了硬件抽象的 LL 层。LL 层 API 主要用于将寄存器操作抽象成可读的函数。
* - ``#include "hal/xxx_hal.h"``
  - 是
  - HAL 层用于将外设操作步骤抽象成函数，如读取缓冲区、启动传输、处理事件等。HAL 层构建在 LL 层之上。
* - ``#include "driver/xxx.h"``
  - 否
  - 驱动层是 ESP-IDF 硬件抽象的最高级别。驱动层 API 旨在从 ESP-IDF 应用程序中调用，并在内部使用操作系统的基本功能。因此，驱动层 API 由事件驱动，并可在多线程环境中使用。

//在 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;
    // 设置时钟选择字段
    hw->clk_div_reg.divider = clock_divider >> 4;
    // 设置时钟分频器字段
    hw->config.clk_sel = (source_clk == XXX_SCLK_APB) ? 0 : 1;
}

static inline uint32_t xxx_ll_get_rx_byte_count(xxx_dev_t *hw) {
    return hw->status_reg.rx_cnt;
}

// 初始化某个 WDT
void wdt_hal_init(wdt_hal_context_t *hal, wdt_inst_t wdt_inst, uint32_t prescaler, bool enable_intr);

// 配置 WDT 的特定超时阶段
void wdt_hal_config_stage(wdt_hal_context_t *hal, wdt_stage_t stage, uint32_t timeout, wdt_stage_action_t behavior);

// 启动 WDT
void wdt_hal_enable(wdt_hal_context_t *hal);

// 喂养（即重置）WDT
void wdt_hal_feed(wdt_hal_context_t *hal);

// 处理 WDT 超时
void wdt_hal_handle_intr(wdt_hal_context_t *hal);

// 停止 WDT
void wdt_hal_disable(wdt_hal_context_t *hal);

// 去初始化 WDT
void wdt_hal_deinit(wdt_hal_context_t *hal);

wdt_hal_context_t rtc_wdt_ctx = RWDT_HAL_CONTEXT_DEFAULT();
wdt_hal_write_protect_disable(&rtc_wdt_ctx);
wdt_hal_disable(&rtc_wdt_ctx);
wdt_hal_write_protect_enable(&rtc_wdt_ctx);

wdt_hal_context_t rtc_wdt_ctx = RWDT_HAL_CONTEXT_DEFAULT();
wdt_hal_write_protect_disable(&rtc_wdt_ctx);
wdt_hal_feed(&rtc_wdt_ctx);
wdt_hal_write_protect_enable(&rtc_wdt_ctx);