README.md
1# Core Components
2
3## Overview
4
5This document contains details about what the core components are, what they contain, and how they are organized.
6
7## Organization
8
9The core components are organized into two groups.
10
11The first group (referred to as `G0` from now on) contains `hal`, `xtensa` and `riscv` (referred to as `arch` components from now on), `esp_rom`, `esp_common`, and `soc`. This
12group contain information about and low-level access to underlying hardware; or in the case of `esp_common`, hardware-agnostic code and utilities.
13These components can depend on each other, but as much as possible have no dependencies outside the group. The reason for this is that, due to the
14nature of what these components contain, the likelihood is high that a lot of other components will require these. Ideally, then, the dependency
15relationship only goes one way. This makes it easier for these components, as a group, to be usable in another project. One can conceivably implement
16a competing SDK to ESP-IDF on top of these components.
17
18The second group (referred to as `G1` from now on) sits at a higher level than the first group. This group contains the components `esp_hw_support`, `esp_system`, `newlib`, `spi_flash`,
19`freertos`, `log`, and `heap`. Like the first group, circular dependencies within the group are allowed; and being at a higher level, dependency on the first group
20is allowed. These components represent software mechanisms essential to building other components.
21
22## Descriptions
23
24The following is a short description of the components mentioned above.
25
26### `G0` Components
27
28#### `hal`
29
30Contains the hardware abstraction layer and low-level operation implementations for the various peripherals. The low-level functions assign meaningful names to register-level manipulations; the hardware abstraction provide operations one level above this, grouping these low-level functions
31into routines that achieve a meaningful action or state of the peripheral.
32
33Example:
34
35- `spi_flash_ll_set_address` is a low-level function part of the hardware abstraction `spi_flash_hal_read_block`
36
37#### `arch`
38
39Contains low-level architecture operations and definitions, including those for customizations (can be thought of on the same level as the low-level functions of `hal`).
40This can also contain files provided by the architecture vendor.
41
42Example:
43
44- `xt_set_exception_handler`
45- `riscv_global_interrupts_enable`
46- `ERI_PERFMON_MAX`
47
48#### `esp_common`
49
50Contains hardware-agnostic definitions, constants, macros, utilities, 'pure' and/or algorithmic functions that is useable by all other components (that is, barring there being a more appropriate component to put them in).
51
52Example:
53
54- `BIT(nr)` and other bit manipulation utilities in the future
55- `IDF_DEPRECATED(REASON)`
56- `ESP_IDF_VERSION_MAJOR`
57
58#### `soc`
59
60Contains description of the underlying hardware: register structure, addresses, pins, capabilities, etc.
61
62Example:
63
64- `DR_REG_DPORT_BASE`
65- `SOC_MCPWM_SUPPORTED`
66- `uart_dev_s`
67
68#### `esp_rom`
69
70Contains headers, linker scripts, abstraction layer, patches, and other related files to ROM functions.
71
72Example:
73
74- `esp32.rom.eco3.ld`
75- `rom/aes.h`
76
77### `G1` Components
78
79#### `spi_flash`
80
81SPI flash device access implementation.
82
83#### `freertos`
84
85FreeRTOS port to targets supported by ESP-IDF.
86
87#### `log`
88
89Logging library.
90
91#### `heap`
92
93Heap implementation.
94
95#### `newlib`
96
97Some functions n the standard library are implemented here, especially those needing other `G1` components.
98
99Example:
100
101- `malloc` is implemented in terms of the component `heap`'s functions
102- `gettimeofday` is implemented in terms of system time in `esp_system`
103
104#### `esp_system`
105
106Contains implementation of system services and controls system behavior. The implementations
107here may take hardware resources and/or decide on a hardware state needed for support of a system service/feature/mechanism.
108Currently, this encompasses the following, but not limited to:
109
110- Startup and initialization
111- Panic and debug
112- Reset and reset reason
113- Task and interrupt watchdogs
114
115#### `esp_hw_support`
116
117Contains implementations that provide hardware operations, arbitration, or resource sharing, especially those that
118is used in the system. Unlike `esp_system`, implementations here do not decide on a hardware state or takes hardware resource, acting
119merely as facilitator to hardware access. Currently, this encompasses the following, but not limited to:
120
121- Interrupt allocation
122- Sleep functions
123- Memory functions (external SPIRAM, async memory, etc.)
124- Clock and clock control
125- Random generation
126- CPU utilities
127- MAC settings
128
129### `esp_hw_support` vs `esp_system`
130
131This section details list some implementations and the reason for placing it in either `esp_hw_support` or `esp_system`.
132
133#### `task_wdt.c` (`esp_system`) vs `intr_alloc.c` (`esp_hw_support`)
134
135The task watchdog fits the definition of taking and configuring hardware resources (wdt, interrupt) for implementation of a system service/mechanism.
136
137This is in contrast with interrupt allocation that merely facilitates access to the underlying hardware for other implementations -
138drivers, user code, and even the task watchdog mentioned previously!
139
140#### `crosscore_int.c` (`esp_system`)
141
142The current implementation of crosscore interrupts is tightly coupled with a number of interrupt reasons
143associated with system services/mechanisms: REASON_YIELD (scheduler), REASON_FREQ_SWITCH (power management)
144REASON_PRINT_BACKTRACE (panic and debug).
145
146However, if an implementation exists that makes it possible to register an arbitrary interrupt reason - a
147lower level inter-processor call if you will, then this implementation is a good candidate for `esp_hw_support`.
148The current implementation in `esp_system` can then just register the interrupt reasons mentioned above.
149
150#### `esp_mac.h`, `esp_chip_info.h`, `esp_random.h` (`esp_hw_support`)
151
152The functions in these headers used to be in `esp_system.h`, but have been split-off.
153However, to maintain backward compatibility, `esp_system.h` includes these headers.
154
155The remaining functions in `esp_system.h` are those that deal with system behavior, such
156as `esp_register_shutdown_handler`, or are proxy for other system components's APIs such as
157`esp_get_free_heap_size`.
158
159The functions split-off from `esp_system.h` are much more hardware manipulation oriented such as:
160`esp_read_mac`, `esp_random` and `esp_chip_info`.
