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`.
