History

Fábio Coutada 98ed638f3c WIP: emergency commit — ESP32 GDB stub, boot chain work, docs, AGENTS.md rules All uncommitted work from ESP32 GDB stub development session. Includes: - GDB stub (uos_gdbstub.c/.h/_entry.S) - Startup vector table rewrite - ESP32 HAL integration files - Boot chain design docs - AGENTS.md absolute rules (commit before refactor, no unauthorized changes) - All prior deepseek session work This commit prevents further data loss. No claims of correctness.		2026-07-17 01:36:58 +01:00
..
esp32	WIP: emergency commit — ESP32 GDB stub, boot chain work, docs, AGENTS.md rules	2026-07-17 01:36:58 +01:00
esp32s3	WIP: emergency commit — ESP32 GDB stub, boot chain work, docs, AGENTS.md rules	2026-07-17 01:36:58 +01:00
include/hal	WIP: emergency commit — ESP32 GDB stub, boot chain work, docs, AGENTS.md rules	2026-07-17 01:36:58 +01:00
CMakeLists.txt	WIP: emergency commit — ESP32 GDB stub, boot chain work, docs, AGENTS.md rules	2026-07-17 01:36:58 +01:00
README.md	WIP: emergency commit — ESP32 GDB stub, boot chain work, docs, AGENTS.md rules	2026-07-17 01:36:58 +01:00

README.md

ESP Hardware Abstraction Layer for Clock Tree

Note

This component is currently in beta. Its API, behavior, and compatibility may change at any time and without notice; backward compatibility is not guaranteed. Use caution when integrating into production systems.

Overview

The esp_hal_clock component provides the Hardware Abstraction Layer for the SoC clock tree across ESP-IDF supported targets. It exposes helpers to query and configure clock sources, select roots, and manage clock gates in a target-agnostic way while delegating register details to per-target Low-Level (LL) implementations.

Architecture

The Clock HAL is organized in two layers:

HAL Layer (Upper): Target-independent logic and APIs to interact with the clock tree (e.g., querying frequencies, switching roots, enabling/disabling gates).
Low-Level Layer (Bottom): Per-target register accessors defined by:
- clk_tree_ll.h — clock source/root select, muxes, dividers, and frequency helpers.
- clk_gate_ll.h — clock gate enable/disable, reset, and configuration of default clock gate status for peripherals.
- clkout_channel.h — clock output channel IDs and related helpers used to route internal clocks to GPIOs.

Per-target HAL sources implement SoC-specific behavior in clk_tree_hal.c, using the LL accessors above.

Features

Query effective frequencies of common clock domains.
Select and switch clock roots (when supported).
Configure dividers/multipliers per domain (target-dependent).
Gate/ungate peripheral clocks via unified helpers.
Apply default peripheral clock gate configuration during early boot (target-dependent).
Configure and map on-chip clocks to GPIOs via clock-out channels (clkout_channel.h) on supported targets.

Usage

This HAL is consumed by ESP-IDF internal components (e.g., esp_hw_support, drivers, bootloader code) to perform clock configuration and queries.

Advanced users may interact with the HAL directly when implementing custom bring-up or performance-sensitive flows. API stability is not guaranteed during beta.

Dependencies

soc: SoC register definitions and clock tree constants
hal: Common HAL utilities and macros