doc: Update English pages with generic target name
This commit is contained in:
Marius Vikhammer
committed by
Angus Gratton
Angus Gratton
parent
c848aa74ac
commit
9352899d69
@@ -4,7 +4,7 @@ App Image Format
|
||||
An application image consists of the following structures:
|
||||
|
||||
1. The :cpp:type:`esp_image_header_t` structure describes the mode of SPI flash and the count of memory segments.
|
||||
2. The :cpp:type:`esp_image_segment_header_t` structure describes each segment, its length, and its location in ESP32's memory, followed by the data with a length of ``data_len``. The data offset for each segment in the image is calculated in the following way:
|
||||
2. The :cpp:type:`esp_image_segment_header_t` structure describes each segment, its length, and its location in {IDF_TARGET_NAME}'s memory, followed by the data with a length of ``data_len``. The data offset for each segment in the image is calculated in the following way:
|
||||
|
||||
* offset for 0 Segment = sizeof(:cpp:type:`esp_image_header_t`) + sizeof(:cpp:type:`esp_image_segment_header_t`).
|
||||
* offset for 1 Segment = offset for 0 Segment + length of 0 Segment + sizeof(:cpp:type:`esp_image_segment_header_t`).
|
||||
@@ -17,7 +17,7 @@ To get the list of your image segments, please run the following command:
|
||||
|
||||
::
|
||||
|
||||
esptool.py --chip esp32 image_info build/app.bin
|
||||
esptool.py --chip {IDF_TARGET_PATH_NAME} image_info build/app.bin
|
||||
|
||||
::
|
||||
|
||||
@@ -58,8 +58,8 @@ You can also see the information on segments in the IDF logs while your applicat
|
||||
I (971) esp_image: segment 11: paddr=0x000a9b74 vaddr=0x50000004 size=0x00000 ( 0) load
|
||||
I (1012) esp_image: segment 12: paddr=0x000a9b7c vaddr=0x50000004 size=0x00000 ( 0) load
|
||||
|
||||
For more details on the type of memory segments and their address ranges, see the ESP32 Technical Reference Manual, Section 1.3.2 *Embedded Memory*.
|
||||
|
||||
For more details on the type of memory segments and their address ranges, see the {IDF_TARGET_NAME} Technical Reference Manual, Section 1.3.2 *Embedded Memory*.
|
||||
|
||||
3. The image has a single checksum byte after the last segment. This byte is written on a sixteen byte padded boundary, so the application image might need padding.
|
||||
4. If the ``hash_appended`` field from :cpp:type:`esp_image_header_t` is set then a SHA256 checksum will be appended. The value of SHA256 is calculated on the range from first byte and up to this field. The length of this field is 32 bytes.
|
||||
5. If the options :ref:`CONFIG_SECURE_SIGNED_APPS_NO_SECURE_BOOT` or :ref:`CONFIG_SECURE_BOOT_ENABLED` are enabled then the application image will have additional 68 bytes for an ECDSA signature, which includes:
|
||||
|
||||
@@ -4,7 +4,7 @@ Application Level Tracing
|
||||
Overview
|
||||
--------
|
||||
|
||||
IDF provides useful feature for program behaviour analysis: application level tracing. It is implemented in the corresponding library and can be enabled via menuconfig. This feature allows to transfer arbitrary data between host and ESP32 via JTAG interface with small overhead on program execution.
|
||||
IDF provides useful feature for program behaviour analysis: application level tracing. It is implemented in the corresponding library and can be enabled via menuconfig. This feature allows to transfer arbitrary data between host and {IDF_TARGET_NAME} via JTAG interface with small overhead on program execution.
|
||||
Developers can use this library to send application specific state of execution to the host and receive commands or other type of info in the opposite direction at runtime. The main use cases of this library are:
|
||||
|
||||
1. Collecting application specific data, see :ref:`app_trace-application-specific-tracing`
|
||||
|
||||
@@ -11,15 +11,27 @@ The eFuse Manager library is designed to structure access to eFuse bits and make
|
||||
Hardware description
|
||||
--------------------
|
||||
|
||||
The ESP32 has a number of eFuses which can store system and user parameters. Each eFuse is a one-bit field which can be programmed to 1 after which it cannot be reverted back to 0.
|
||||
Some of system parameters are using these eFuse bits directly by hardware modules and have special place (for example EFUSE_BLK0). For more details see `ESP32 Technical Reference Manual <https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>`_ in part 20 eFuse controller. Some eFuse bits are available for user applications.
|
||||
The {IDF_TARGET_NAME} has a number of eFuses which can store system and user parameters. Each eFuse is a one-bit field which can be programmed to 1 after which it cannot be reverted back to 0.
|
||||
Some of system parameters are using these eFuse bits directly by hardware modules and have special place (for example EFUSE_BLK0).
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
For more details see `ESP32 Technical Reference Manual <https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>`_ in part 20 eFuse controller. Some eFuse bits are available for user applications.
|
||||
|
||||
ESP32 has 4 eFuse blocks each of the size of 256 bits (not all bits are available):
|
||||
|
||||
* EFUSE_BLK0 is used entirely for system purposes;
|
||||
* EFUSE_BLK1 is used for flash encrypt key. If not using that Flash Encryption feature, they can be used for another purpose;
|
||||
* EFUSE_BLK2 is used for security boot key. If not using that Secure Boot feature, they can be used for another purpose;
|
||||
* EFUSE_BLK3 can be partially reserved for the custom MAC address, or used entirely for user application. Note that some bits are already used in IDF.
|
||||
|
||||
.. only:: esp32s2
|
||||
|
||||
For more details see `ESP32-S2 Technical Reference Manual <https://www.espressif.com/sites/default/files/documentation/esp32s2_technical_reference_manual_en.pdf>`_. Some eFuse bits are available for user applications.
|
||||
|
||||
{IDF_TARGET_NAME} has 11 eFuse blocks each of the size of 256 bits (not all bits are available):
|
||||
|
||||
ESP32 has 4 eFuse blocks each of the size of 256 bits (not all bits are available):
|
||||
|
||||
* EFUSE_BLK0 is used entirely for system purposes;
|
||||
* EFUSE_BLK1 is used for flash encrypt key. If not using that Flash Encryption feature, they can be used for another purpose;
|
||||
* EFUSE_BLK2 is used for security boot key. If not using that Secure Boot feature, they can be used for another purpose;
|
||||
* EFUSE_BLK3 can be partially reserved for the custom MAC address, or used entirely for user application. Note that some bits are already used in IDF.
|
||||
|
||||
Each block is divided into 8 32-bits registers.
|
||||
|
||||
@@ -62,7 +74,7 @@ bit_count
|
||||
|
||||
comment
|
||||
This param is using for comment field, it also move to C-header file. The comment field can be omitted.
|
||||
|
||||
|
||||
If a non-sequential bit order is required to describe a field, then the field description in the following lines should be continued without specifying a name, this will indicate that it belongs to one field. For example two fields MAC_FACTORY and MAC_FACTORY_CRC:
|
||||
|
||||
::
|
||||
@@ -76,7 +88,7 @@ If a non-sequential bit order is required to describe a field, then the field de
|
||||
, EFUSE_BLK0, 40, 8, Factory MAC addr [4]
|
||||
, EFUSE_BLK0, 32, 8, Factory MAC addr [5]
|
||||
MAC_FACTORY_CRC, EFUSE_BLK0, 80, 8, CRC8 for factory MAC address
|
||||
|
||||
|
||||
This field will available in code as ESP_EFUSE_MAC_FACTORY and ESP_EFUSE_MAC_FACTORY_CRC.
|
||||
|
||||
efuse_table_gen.py tool
|
||||
@@ -87,11 +99,11 @@ The tool is designed to generate C-source files from CSV file and validate field
|
||||
To generate a `common` files, use the following command ``idf.py efuse_common_table`` or:
|
||||
|
||||
::
|
||||
|
||||
cd $IDF_PATH/components/efuse/
|
||||
./efuse_table_gen.py esp32/esp_efuse_table.csv
|
||||
|
||||
After generation in the folder `esp32` create:
|
||||
cd $IDF_PATH/components/efuse/
|
||||
./efuse_table_gen.py {IDF_TARGET_PATH_NAME}/esp_efuse_table.csv
|
||||
|
||||
After generation in the folder `{IDF_TARGET_PATH_NAME}` create:
|
||||
|
||||
* `esp_efuse_table.c` file.
|
||||
* In `include` folder `esp_efuse_table.c` file.
|
||||
@@ -101,7 +113,7 @@ To generate a `custom` files, use the following command ``idf.py efuse_custom_ta
|
||||
::
|
||||
|
||||
cd $IDF_PATH/components/efuse/
|
||||
./efuse_table_gen.py esp32/esp_efuse_table.csv PROJECT_PATH/main/esp_efuse_custom_table.csv
|
||||
./efuse_table_gen.py {IDF_TARGET_PATH_NAME}/esp_efuse_table.csv PROJECT_PATH/main/esp_efuse_custom_table.csv
|
||||
|
||||
After generation in the folder PROJECT_PATH/main create:
|
||||
|
||||
@@ -124,7 +136,7 @@ eFuse have three coding schemes:
|
||||
* ``3/4`` (value 1).
|
||||
* ``Repeat`` (value 2).
|
||||
|
||||
The coding scheme affects only EFUSE_BLK1, EFUSE_BLK2 and EFUSE_BLK3 blocks. EUSE_BLK0 block always has a coding scheme ``None``.
|
||||
The coding scheme affects only EFUSE_BLK1, EFUSE_BLK2 and EFUSE_BLK3 blocks. EUSE_BLK0 block always has a coding scheme ``None``.
|
||||
Coding changes the number of bits that can be written into a block, the block length is constant 256, some of these bits are used for encoding and are not used.
|
||||
|
||||
When using a coding scheme, the length of the payload that can be written is limited (for more details ``20.3.1.3 System Parameter coding_scheme``):
|
||||
@@ -136,7 +148,7 @@ When using a coding scheme, the length of the payload that can be written is lim
|
||||
You can find out the coding scheme of your chip:
|
||||
|
||||
* run a ``espefuse.py -p COM4 summary`` command.
|
||||
* from ``esptool`` utility logs (during flashing).
|
||||
* from ``esptool`` utility logs (during flashing).
|
||||
* calling the function in the code :cpp:func:`esp_efuse_get_coding_scheme` for the EFUSE_BLK3 block.
|
||||
|
||||
eFuse tables must always comply with the coding scheme in the chip. There is an :envvar:`EFUSE_CODE_SCHEME_SELECTOR` option to select the coding type for tables in a Kconfig. When generating source files, if your tables do not follow the coding scheme, an error message will be displayed. Adjust the length or offset fields.
|
||||
@@ -181,7 +193,7 @@ How add a new field
|
||||
|
||||
::
|
||||
|
||||
$ ./efuse_table_gen.py esp32/esp_efuse_table.csv --info
|
||||
$ ./efuse_table_gen.py {IDF_TARGET_PATH_NAME}/esp_efuse_table.csv --info
|
||||
eFuse coding scheme: NONE
|
||||
# field_name efuse_block bit_start bit_count
|
||||
1 WR_DIS_FLASH_CRYPT_CNT EFUSE_BLK0 2 1
|
||||
@@ -226,23 +238,23 @@ How add a new field
|
||||
40 ADC2_TP_HIGH EFUSE_BLK3 119 9
|
||||
41 SECURE_VERSION EFUSE_BLK3 128 32
|
||||
42 MAC_CUSTOM_VER EFUSE_BLK3 184 8
|
||||
|
||||
|
||||
Used bits in eFuse table:
|
||||
EFUSE_BLK0
|
||||
[2 2] [7 9] [16 18] [20 27] [32 87] [96 97] [105 109] [111 111] [136 144] [188 191] [194 194] [196 196] [198 201]
|
||||
|
||||
|
||||
EFUSE_BLK1
|
||||
[0 255]
|
||||
|
||||
|
||||
EFUSE_BLK2
|
||||
[0 255]
|
||||
|
||||
|
||||
EFUSE_BLK3
|
||||
[0 55] [96 159] [184 191]
|
||||
|
||||
|
||||
Note: Not printed ranges are free for using. (bits in EFUSE_BLK0 are reserved for Espressif)
|
||||
|
||||
Parsing eFuse CSV input file $IDF_PATH/components/efuse/esp32/esp_efuse_table.csv ...
|
||||
|
||||
Parsing eFuse CSV input file $IDF_PATH/components/efuse/{IDF_TARGET_PATH_NAME}/esp_efuse_table.csv ...
|
||||
Verifying eFuse table...
|
||||
|
||||
|
||||
@@ -263,12 +275,12 @@ The Kconfig option :envvar:`CONFIG_EFUSE_VIRTUAL` will virtualize eFuse values i
|
||||
espefuse.py
|
||||
^^^^^^^^^^^
|
||||
|
||||
esptool includes a useful tool for reading/writing ESP32 eFuse bits - `espefuse.py <https://github.com/espressif/esptool/wiki/espefuse>`_.
|
||||
esptool includes a useful tool for reading/writing {IDF_TARGET_NAME} eFuse bits - `espefuse.py <https://github.com/espressif/esptool/wiki/espefuse>`_.
|
||||
|
||||
::
|
||||
|
||||
espefuse.py -p COM4 summary
|
||||
|
||||
|
||||
espefuse.py v2.3.1
|
||||
Connecting........_
|
||||
Security fuses:
|
||||
@@ -287,13 +299,13 @@ esptool includes a useful tool for reading/writing ESP32 eFuse bits - `espefuse.
|
||||
= 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W
|
||||
BLK3 Variable Block 3
|
||||
= 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 fa 87 02 91 00 00 00 00 00 00 00 00 00 00 00 00 R/W
|
||||
|
||||
|
||||
Efuse fuses:
|
||||
WR_DIS Efuse write disable mask = 0 R/W (0x0)
|
||||
RD_DIS Efuse read disablemask = 0 R/W (0x0)
|
||||
CODING_SCHEME Efuse variable block length scheme = 1 R/W (0x1) (3/4)
|
||||
KEY_STATUS Usage of efuse block 3 (reserved) = 0 R/W (0x0)
|
||||
|
||||
|
||||
Config fuses:
|
||||
XPD_SDIO_FORCE Ignore MTDI pin (GPIO12) for VDD_SDIO on reset = 0 R/W (0x0)
|
||||
XPD_SDIO_REG If XPD_SDIO_FORCE, enable VDD_SDIO reg on reset = 0 R/W (0x0)
|
||||
@@ -304,14 +316,14 @@ esptool includes a useful tool for reading/writing ESP32 eFuse bits - `espefuse.
|
||||
SPI_PAD_CONFIG_HD Override SD_DATA_2 pad (GPIO9/SPIHD) = 0 R/W (0x0)
|
||||
SPI_PAD_CONFIG_CS0 Override SD_CMD pad (GPIO11/SPICS0) = 0 R/W (0x0)
|
||||
DISABLE_SDIO_HOST Disable SDIO host = 0 R/W (0x0)
|
||||
|
||||
|
||||
Identity fuses:
|
||||
MAC MAC Address
|
||||
= 84:0d:8e:18:8e:44 (CRC ad OK) R/W
|
||||
CHIP_VER_REV1 Silicon Revision 1 = 1 R/W (0x1)
|
||||
CHIP_VERSION Reserved for future chip versions = 2 R/W (0x2)
|
||||
CHIP_PACKAGE Chip package identifier = 0 R/W (0x0)
|
||||
|
||||
|
||||
Calibration fuses:
|
||||
BLK3_PART_RESERVE BLOCK3 partially served for ADC calibration data = 1 R/W (0x1)
|
||||
ADC_VREF Voltage reference calibration = 1114 R/W (0x2)
|
||||
@@ -319,13 +331,13 @@ esptool includes a useful tool for reading/writing ESP32 eFuse bits - `espefuse.
|
||||
ADC1_TP_HIGH ADC1 850mV reading = 3285 R/W (0x5)
|
||||
ADC2_TP_LOW ADC2 150mV reading = 449 R/W (0x7)
|
||||
ADC2_TP_HIGH ADC2 850mV reading = 3362 R/W (0x1f5)
|
||||
|
||||
|
||||
Flash voltage (VDD_SDIO) determined by GPIO12 on reset (High for 1.8V, Low/NC for 3.3V).
|
||||
|
||||
To get a dump for all eFuse registers.
|
||||
|
||||
::
|
||||
|
||||
|
||||
espefuse.py -p COM4 dump
|
||||
|
||||
$ espefuse.py -p COM4 dump
|
||||
|
||||
@@ -280,7 +280,7 @@ To gather and analyse heap trace do the following on the host:
|
||||
|
||||
Using this file GDB will connect to the target, reset it, and start tracing when program hits breakpoint at :cpp:func:`heap_trace_start`. Trace data will be saved to ``/tmp/heap_log.svdat``. Tracing will be stopped when program hits breakpoint at :cpp:func:`heap_trace_stop`.
|
||||
|
||||
4. Run GDB using the following command ``xtensa-esp32-elf-gdb -x gdbinit </path/to/program/elf>``
|
||||
4. Run GDB using the following command ``xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb -x gdbinit </path/to/program/elf>``
|
||||
|
||||
5. Quit GDB when program stops at :cpp:func:`heap_trace_stop`. Trace data are saved in ``/tmp/heap.svdat``
|
||||
|
||||
|
||||
@@ -16,8 +16,8 @@ System API
|
||||
Heap Memory Allocation <mem_alloc>
|
||||
Heap Memory Debugging <heap_debug>
|
||||
High Resolution Timer <esp_timer>
|
||||
Himem (large external SPI RAM) API <himem>
|
||||
Inter-Processor Call <ipc>
|
||||
:esp32: Himem (large external SPI RAM) API <himem>
|
||||
:esp32: Inter-Processor Call <ipc>
|
||||
Call function with external stack <esp_expression_with_stack>
|
||||
Interrupt Allocation <intr_alloc>
|
||||
Logging <log>
|
||||
|
||||
@@ -4,9 +4,17 @@ Interrupt allocation
|
||||
Overview
|
||||
--------
|
||||
|
||||
The ESP32 has two cores, with 32 interrupts each. Each interrupt has a certain priority level, most (but not all) interrupts are connected
|
||||
to the interrupt mux. Because there are more interrupt sources than interrupts, sometimes it makes sense to share an interrupt in
|
||||
multiple drivers. The esp_intr_alloc abstraction exists to hide all these implementation details.
|
||||
.. only:: esp32
|
||||
|
||||
The {IDF_TARGET_NAME} has two cores, with 32 interrupts each. Each interrupt has a certain priority level, most (but not all) interrupts are connected
|
||||
to the interrupt mux. Because there are more interrupt sources than interrupts, sometimes it makes sense to share an interrupt in
|
||||
multiple drivers. The esp_intr_alloc abstraction exists to hide all these implementation details.
|
||||
|
||||
.. only.. esp32s2
|
||||
|
||||
The {IDF_TARGET_NAME} has one cores, with 32 interrupts each. Each interrupt has a certain priority level, most (but not all) interrupts are connected
|
||||
to the interrupt mux. Because there are more interrupt sources than interrupts, sometimes it makes sense to share an interrupt in
|
||||
multiple drivers. The esp_intr_alloc abstraction exists to hide all these implementation details.
|
||||
|
||||
A driver can allocate an interrupt for a certain peripheral by calling esp_intr_alloc (or esp_intr_alloc_sintrstatus). It can use
|
||||
the flags passed to this function to set the type of interrupt allocated, specifying a specific level or trigger method. The
|
||||
@@ -15,7 +23,7 @@ install the given interrupt handler and ISR to it.
|
||||
|
||||
This code has two different types of interrupts it handles differently: Shared interrupts and non-shared interrupts. The simplest
|
||||
of the two are non-shared interrupts: a separate interrupt is allocated per esp_intr_alloc call and this interrupt is solely used for
|
||||
the peripheral attached to it, with only one ISR that will get called. Shared interrupts can have multiple peripherals triggering
|
||||
the peripheral attached to it, with only one ISR that will get called. Shared interrupts can have multiple peripherals triggering
|
||||
it, with multiple ISRs being called when one of the peripherals attached signals an interrupt. Thus, ISRs that are intended for shared
|
||||
interrupts should check the interrupt status of the peripheral they service in order to see if any action is required.
|
||||
|
||||
@@ -24,7 +32,7 @@ only be level interrupts (because of the chance of missed interrupts when edge i
|
||||
used.)
|
||||
(The logic behind this: DevA and DevB share an int. DevB signals an int. Int line goes high. ISR handler
|
||||
calls code for DevA -> does nothing. ISR handler calls code for DevB, but while doing that,
|
||||
DevA signals an int. ISR DevB is done, clears int for DevB, exits interrupt code. Now an
|
||||
DevA signals an int. ISR DevB is done, clears int for DevB, exits interrupt code. Now an
|
||||
interrupt for DevA is still pending, but because the int line never went low (DevA kept it high
|
||||
even when the int for DevB was cleared) the interrupt is never serviced.)
|
||||
|
||||
@@ -34,7 +42,7 @@ Multicore issues
|
||||
|
||||
Peripherals that can generate interrupts can be divided in two types:
|
||||
|
||||
- External peripherals, within the ESP32 but outside the Xtensa cores themselves. Most ESP32 peripherals are of this type.
|
||||
- External peripherals, within the {IDF_TARGET_NAME} but outside the Xtensa cores themselves. Most {IDF_TARGET_NAME} peripherals are of this type.
|
||||
- Internal peripherals, part of the Xtensa CPU cores themselves.
|
||||
|
||||
Interrupt handling differs slightly between these two types of peripherals.
|
||||
@@ -89,7 +97,7 @@ Multiple Handlers Sharing A Source
|
||||
Several handlers can be assigned to a same source, given that all handlers are allocated using the ``ESP_INTR_FLAG_SHARED`` flag.
|
||||
They'll be all allocated to the interrupt, which the source is attached to, and called sequentially when the source is active.
|
||||
The handlers can be disabled and freed individually. The source is attached to the interrupt (enabled), if one or more handlers are enabled, otherwise detached.
|
||||
A handler will never be called when disabled, while **its source may still be triggered** if any one of its handler enabled.
|
||||
A handler will never be called when disabled, while **its source may still be triggered** if any one of its handler enabled.
|
||||
|
||||
Sources attached to non-shared interrupt do not support this feature.
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@ ESP-IDF applications use the common computer architecture patterns of *stack* (d
|
||||
|
||||
Because ESP-IDF is a multi-threaded RTOS environment, each RTOS task has its own stack. By default, each of these stacks is allocated from the heap when the task is created. (See :cpp:func:`xTaskCreateStatic` for the alternative where stacks are statically allocated.)
|
||||
|
||||
Because ESP32 uses multiple types of RAM, it also contains multiple heaps with different capabilities. A capabilities-based memory allocator allows apps to make heap allocations for different purposes.
|
||||
Because {IDF_TARGET_NAME} uses multiple types of RAM, it also contains multiple heaps with different capabilities. A capabilities-based memory allocator allows apps to make heap allocations for different purposes.
|
||||
|
||||
For most purposes, the standard libc ``malloc()`` and ``free()`` functions can be used for heap allocation without any special consideration.
|
||||
|
||||
@@ -18,7 +18,7 @@ capabilities-based heap memory allocator. If you want to have memory with certai
|
||||
Memory Capabilities
|
||||
-------------------
|
||||
|
||||
The ESP32 contains multiple types of RAM:
|
||||
The {IDF_TARGET_NAME} contains multiple types of RAM:
|
||||
|
||||
- DRAM (Data RAM) is memory used to hold data. This is the most common kind of memory accessed as heap.
|
||||
- IRAM (Instruction RAM) usually holds executable data only. If accessed as generic memory, all accesses must be :ref:`32-bit aligned<32-Bit Accessible Memory>`.
|
||||
@@ -26,7 +26,7 @@ The ESP32 contains multiple types of RAM:
|
||||
|
||||
For more details on these internal memory types, see :ref:`memory-layout`.
|
||||
|
||||
It's also possible to connect external SPI RAM to the ESP32 - :doc:`external RAM </api-guides/external-ram>` can be integrated into the ESP32's memory map using the flash cache, and accessed similarly to DRAM.
|
||||
It's also possible to connect external SPI RAM to the {IDF_TARGET_NAME} - :doc:`external RAM </api-guides/external-ram>` can be integrated into the {IDF_TARGET_NAME}'s memory map using the flash cache, and accessed similarly to DRAM.
|
||||
|
||||
DRAM uses capability ``MALLOC_CAP_8BIT`` (accessible in single byte reads and writes). When calling ``malloc()``, the ESP-IDF ``malloc()`` implementation internally calls ``heap_caps_malloc(size, MALLOC_CAP_8BIT)`` in order to allocate DRAM that is byte-addressable. To test the free DRAM heap size at runtime, call cpp:func:`heap_caps_get_free_size(MALLOC_CAP_8BIT)`.
|
||||
|
||||
@@ -57,7 +57,7 @@ The :ref:`idf.py size <idf.py-size>` command can be used to find the amount of I
|
||||
D/IRAM
|
||||
^^^^^^
|
||||
|
||||
Some memory in the ESP32 is available as either DRAM or IRAM. If memory is allocated from a D/IRAM region, the free heap size for both types of memory will decrease.
|
||||
Some memory in the {IDF_TARGET_NAME} is available as either DRAM or IRAM. If memory is allocated from a D/IRAM region, the free heap size for both types of memory will decrease.
|
||||
|
||||
Heap Sizes
|
||||
^^^^^^^^^^
|
||||
@@ -95,7 +95,7 @@ Use the ``MALLOC_CAP_DMA`` flag to allocate memory which is suitable for use wit
|
||||
|
||||
If a certain memory structure is only addressed in 32-bit units, for example an array of ints or pointers, it can be
|
||||
useful to allocate it with the ``MALLOC_CAP_32BIT`` flag. This also allows the allocator to give out IRAM memory; something
|
||||
which it can't do for a normal malloc() call. This can help to use all the available memory in the ESP32.
|
||||
which it can't do for a normal malloc() call. This can help to use all the available memory in the {IDF_TARGET_NAME}.
|
||||
|
||||
Memory allocated with ``MALLOC_CAP_32BIT`` can *only* be accessed via 32-bit reads and writes, any other type of access will
|
||||
generate a fatal LoadStoreError exception.
|
||||
@@ -105,7 +105,9 @@ External SPI Memory
|
||||
|
||||
When :doc:`external RAM </api-guides/external-ram>` is enabled, external SPI RAM under 4MiB in size can be allocated using standard ``malloc`` calls, or via ``heap_caps_malloc(MALLOC_CAP_SPIRAM)``, depending on configuration. See :ref:`external_ram_config` for more details.
|
||||
|
||||
To use the region above the 4MiB limit, you can use the :doc:`himem API</api-reference/system/himem>`.
|
||||
..only:: esp32
|
||||
|
||||
To use the region above the 4MiB limit, you can use the :doc:`himem API</api-reference/system/himem>`.
|
||||
|
||||
|
||||
API Reference - Heap Allocation
|
||||
|
||||
@@ -139,7 +139,7 @@ This function works if set :ref:`CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK` option. In
|
||||
A typical anti-rollback scheme is
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
- New firmware released with the elimination of vulnerabilities with the previous version of security.
|
||||
- New firmware released with the elimination of vulnerabilities with the previous version of security.
|
||||
- After the developer makes sure that this firmware is working. He can increase the security version and release a new firmware.
|
||||
- Download new application.
|
||||
- To make it bootable, run the function :cpp:func:`esp_ota_set_boot_partition`. If the security version of the new application is smaller than the version in the chip, the new application will be erased. Update to new firmware is not possible.
|
||||
@@ -148,7 +148,7 @@ A typical anti-rollback scheme is
|
||||
- New application booted. Then the application should perform diagnostics of the operation and if it is completed successfully, you should call :cpp:func:`esp_ota_mark_app_valid_cancel_rollback` function to mark the running application with the ``ESP_OTA_IMG_VALID`` state and update the secure version on chip. Note that if was called :cpp:func:`esp_ota_mark_app_invalid_rollback_and_reboot` function a rollback may not happend due to the device may not have any bootable apps then it will return ``ESP_ERR_OTA_ROLLBACK_FAILED`` error and stay in the ``ESP_OTA_IMG_PENDING_VERIFY`` state.
|
||||
- The next update of app is possible if a running app is in the ``ESP_OTA_IMG_VALID`` state.
|
||||
|
||||
Recommendation:
|
||||
Recommendation:
|
||||
|
||||
If you want to avoid the download/erase overhead in case of the app from the server has security version lower then running app you have to get ``new_app_info.secure_version`` from the first package of an image and compare it with the secure version of efuse. Use ``esp_efuse_check_secure_version(new_app_info.secure_version)`` function if it is true then continue downloading otherwise abort.
|
||||
|
||||
@@ -169,7 +169,7 @@ If you want to avoid the download/erase overhead in case of the app from the ser
|
||||
http_cleanup(client);
|
||||
task_fatal_error();
|
||||
}
|
||||
|
||||
|
||||
image_header_was_checked = true;
|
||||
|
||||
esp_ota_begin(update_partition, OTA_SIZE_UNKNOWN, &update_handle);
|
||||
@@ -189,7 +189,10 @@ Restrictions:
|
||||
``security_version``:
|
||||
|
||||
- In application image it is stored in ``esp_app_desc`` structure. The number is set :ref:`CONFIG_BOOTLOADER_APP_SECURE_VERSION`.
|
||||
- In ESP32 it is stored in efuse ``EFUSE_BLK3_RDATA4_REG``. (when a eFuse bit is programmed to 1, it can never be reverted to 0). The number of bits set in this register is the ``security_version`` from app.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
- In ESP32 it is stored in efuse ``EFUSE_BLK3_RDATA4_REG``. (when a eFuse bit is programmed to 1, it can never be reverted to 0). The number of bits set in this register is the ``security_version`` from app.
|
||||
|
||||
.. _secure-ota-updates:
|
||||
|
||||
@@ -267,13 +270,13 @@ The command-line interface of `otatool.py` has the following structure:
|
||||
otatool.py [command-args] [subcommand] [subcommand-args]
|
||||
|
||||
- command-args - these are arguments that are needed for executing the main command (parttool.py), mostly pertaining to the target device
|
||||
- subcommand - this is the operation to be performed
|
||||
- subcommand - this is the operation to be performed
|
||||
- subcommand-args - these are arguments that are specific to the chosen operation
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Erase otadata, resetting the device to factory app
|
||||
otatool.py --port "/dev/ttyUSB1" erase_otadata
|
||||
otatool.py --port "/dev/ttyUSB1" erase_otadata
|
||||
|
||||
# Erase contents of OTA app slot 0
|
||||
otatool.py --port "/dev/ttyUSB1" erase_ota_partition --slot 0
|
||||
|
||||
@@ -1,13 +1,13 @@
|
||||
Performance Monitor
|
||||
===================
|
||||
|
||||
The Performance Monitor component provides APIs to use ESP32 internal performance counters to profile functions and
|
||||
The Performance Monitor component provides APIs to use {IDF_TARGET_NAME} internal performance counters to profile functions and
|
||||
applications.
|
||||
|
||||
Application Example
|
||||
-------------------
|
||||
|
||||
An example which combines performance monitor is provided in ``examples/system/perfmon`` directory.
|
||||
An example which combines performance monitor is provided in ``examples/system/perfmon`` directory.
|
||||
This example initializes the performance monitor structure and execute them with printing the statistics.
|
||||
|
||||
High level API Reference
|
||||
|
||||
@@ -31,13 +31,8 @@ Dynamic frequency scaling (DFS) and automatic light sleep can be enabled in an a
|
||||
- ``min_freq_mhz``: Minimum CPU frequency in MHz, i.e., the frequency used when only the ``ESP_PM_APB_FREQ_MAX`` lock is acquired. This field can be set to the XTAL frequency value, or the XTAL frequency divided by an integer. Note that 10 MHz is the lowest frequency at which the default REF_TICK clock of 1 MHz can be generated.
|
||||
- ``light_sleep_enable``: Whether the system should automatically enter light sleep when no locks are acquired (``true``/``false``).
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
Alternatively, if you enable the option :ref:`CONFIG_PM_DFS_INIT_AUTO` in menuconfig, the maximum CPU frequency will be determined by the :ref:`CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ` setting, and the minimum CPU frequency will be locked to the XTAL frequency.
|
||||
|
||||
.. only:: esp32s2beta
|
||||
|
||||
Alternatively, if you enable the option :ref:`CONFIG_PM_DFS_INIT_AUTO` in menuconfig, the maximum CPU frequency will be determined by the :ref:`CONFIG_ESP32S2_DEFAULT_CPU_FREQ_MHZ` setting, and the minimum CPU frequency will be locked to the XTAL frequency.
|
||||
Alternatively, if you enable the option :ref:`CONFIG_PM_DFS_INIT_AUTO` in menuconfig, the maximum CPU frequency will be determined by the :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_DEFAULT_CPU_FREQ_MHZ` setting, and the minimum CPU frequency will be locked to the XTAL frequency.
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -55,14 +50,14 @@ Applications have the ability to acquire/release locks in order to control the p
|
||||
|
||||
Power management locks have acquire/release counters. If the lock has been acquired a number of times, it needs to be released the same number of times to remove associated restrictions.
|
||||
|
||||
ESP32 supports three types of locks described in the table below.
|
||||
{IDF_TARGET_NAME} supports three types of locks described in the table below.
|
||||
|
||||
============================ ======================================================
|
||||
Lock Description
|
||||
============================ ======================================================
|
||||
``ESP_PM_CPU_FREQ_MAX`` Requests CPU frequency to be at the maximum value set with :cpp:func:`esp_pm_configure`. For ESP32, this value can be set to 80 MHz, 160 MHz, or 240 MHz.
|
||||
``ESP_PM_CPU_FREQ_MAX`` Requests CPU frequency to be at the maximum value set with :cpp:func:`esp_pm_configure`. For {IDF_TARGET_NAME}, this value can be set to 80 MHz, 160 MHz, or 240 MHz.
|
||||
|
||||
``ESP_PM_APB_FREQ_MAX`` Requests the APB frequency to be at the maximum supported value. For ESP32, this is 80 MHz.
|
||||
``ESP_PM_APB_FREQ_MAX`` Requests the APB frequency to be at the maximum supported value. For {IDF_TARGET_NAME}, this is 80 MHz.
|
||||
|
||||
``ESP_PM_NO_LIGHT_SLEEP`` Disables automatic switching to light sleep.
|
||||
============================ ======================================================
|
||||
|
||||
@@ -4,13 +4,13 @@ Sleep Modes
|
||||
Overview
|
||||
--------
|
||||
|
||||
ESP32 is capable of light sleep and deep sleep power saving modes.
|
||||
{IDF_TARGET_NAME} is capable of light sleep and deep sleep power saving modes.
|
||||
|
||||
In light sleep mode, digital peripherals, most of the RAM, and CPUs are clock-gated, and supply voltage is reduced. Upon exit from light sleep, peripherals and CPUs resume operation, their internal state is preserved.
|
||||
|
||||
In deep sleep mode, CPUs, most of the RAM, and all the digital peripherals which are clocked from APB_CLK are powered off. The only parts of the chip which can still be powered on are: RTC controller, RTC peripherals (including ULP coprocessor), and RTC memories (slow and fast).
|
||||
|
||||
Wakeup from deep and light sleep modes can be done using several sources. These sources can be combined, in this case the chip will wake up when any one of the sources is triggered. Wakeup sources can be enabled using ``esp_sleep_enable_X_wakeup`` APIs and can be disabled using :cpp:func:`esp_sleep_disable_wakeup_source` API. Next section describes these APIs in detail. Wakeup sources can be configured at any moment before entering light or deep sleep mode.
|
||||
Wakeup from deep and light sleep modes can be done using several sources. These sources can be combined, in this case the chip will wake up when any one of the sources is triggered. Wakeup sources can be enabled using ``esp_sleep_enable_X_wakeup`` APIs and can be disabled using :cpp:func:`esp_sleep_disable_wakeup_source` API. Next section describes these APIs in detail. Wakeup sources can be configured at any moment before entering light or deep sleep mode.
|
||||
|
||||
Additionally, the application can force specific powerdown modes for the RTC peripherals and RTC memories using :cpp:func:`esp_sleep_pd_config` API.
|
||||
|
||||
@@ -29,7 +29,7 @@ Wakeup sources
|
||||
Timer
|
||||
^^^^^
|
||||
|
||||
RTC controller has a built in timer which can be used to wake up the chip after a predefined amount of time. Time is specified at microsecond precision, but the actual resolution depends on the clock source selected for RTC SLOW_CLK. See chapter "Reset and Clock" of the ESP32 Technical Reference Manual for details about RTC clock options.
|
||||
RTC controller has a built in timer which can be used to wake up the chip after a predefined amount of time. Time is specified at microsecond precision, but the actual resolution depends on the clock source selected for RTC SLOW_CLK. See chapter "Reset and Clock" of the {IDF_TARGET_NAME} Technical Reference Manual for details about RTC clock options.
|
||||
|
||||
This wakeup mode doesn't require RTC peripherals or RTC memories to be powered on during sleep.
|
||||
|
||||
@@ -40,7 +40,9 @@ Touch pad
|
||||
|
||||
RTC IO module contains logic to trigger wakeup when a touch sensor interrupt occurs. You need to configure the touch pad interrupt before the chip starts deep sleep.
|
||||
|
||||
Revisions 0 and 1 of the ESP32 only support this wakeup mode when RTC peripherals are not forced to be powered on (i.e. ESP_PD_DOMAIN_RTC_PERIPH should be set to ESP_PD_OPTION_AUTO).
|
||||
.. only:: esp32
|
||||
|
||||
Revisions 0 and 1 of the ESP32 only support this wakeup mode when RTC peripherals are not forced to be powered on (i.e. ESP_PD_DOMAIN_RTC_PERIPH should be set to ESP_PD_OPTION_AUTO).
|
||||
|
||||
:cpp:func:`esp_sleep_enable_touchpad_wakeup` function can be used to enable this wakeup source.
|
||||
|
||||
@@ -48,11 +50,13 @@ Revisions 0 and 1 of the ESP32 only support this wakeup mode when RTC peripheral
|
||||
External wakeup (ext0)
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
RTC IO module contains logic to trigger wakeup when one of RTC GPIOs is set to a predefined logic level. RTC IO is part of RTC peripherals power domain, so RTC peripherals will be kept powered on during deep sleep if this wakeup source is requested.
|
||||
RTC IO module contains logic to trigger wakeup when one of RTC GPIOs is set to a predefined logic level. RTC IO is part of RTC peripherals power domain, so RTC peripherals will be kept powered on during deep sleep if this wakeup source is requested.
|
||||
|
||||
Because RTC IO module is enabled in this mode, internal pullup or pulldown resistors can also be used. They need to be configured by the application using :cpp:func:`rtc_gpio_pullup_en` and :cpp:func:`rtc_gpio_pulldown_en` functions, before calling :cpp:func:`esp_sleep_start`.
|
||||
|
||||
In revisions 0 and 1 of the ESP32, this wakeup source is incompatible with ULP and touch wakeup sources.
|
||||
.. only:: esp32
|
||||
|
||||
In revisions 0 and 1 of the ESP32, this wakeup source is incompatible with ULP and touch wakeup sources.
|
||||
|
||||
:cpp:func:`esp_sleep_enable_ext0_wakeup` function can be used to enable this wakeup source.
|
||||
|
||||
@@ -73,7 +77,7 @@ This wakeup source is implemented by the RTC controller. As such, RTC peripheral
|
||||
gpio_pulldown_en(gpio_num);
|
||||
|
||||
.. warning:: After wake up from sleep, IO pad(s) used for wakeup will be configured as RTC IO. Before using these pads as digital GPIOs, reconfigure them using ``rtc_gpio_deinit(gpio_num)`` function.
|
||||
|
||||
|
||||
:cpp:func:`esp_sleep_enable_ext1_wakeup` function can be used to enable this wakeup source.
|
||||
|
||||
ULP coprocessor wakeup
|
||||
@@ -81,7 +85,9 @@ ULP coprocessor wakeup
|
||||
|
||||
ULP coprocessor can run while the chip is in sleep mode, and may be used to poll sensors, monitor ADC or touch sensor values, and wake up the chip when a specific event is detected. ULP coprocessor is part of RTC peripherals power domain, and it runs the program stored in RTC slow memory. RTC slow memory will be powered on during sleep if this wakeup mode is requested. RTC peripherals will be automatically powered on before ULP coprocessor starts running the program; once the program stops running, RTC peripherals are automatically powered down again.
|
||||
|
||||
Revisions 0 and 1 of the ESP32 only support this wakeup mode when RTC peripherals are not forced to be powered on (i.e. ESP_PD_DOMAIN_RTC_PERIPH should be set to ESP_PD_OPTION_AUTO).
|
||||
.. only:: esp32
|
||||
|
||||
Revisions 0 and 1 of the ESP32 only support this wakeup mode when RTC peripherals are not forced to be powered on (i.e. ESP_PD_DOMAIN_RTC_PERIPH should be set to ESP_PD_OPTION_AUTO).
|
||||
|
||||
:cpp:func:`esp_sleep_enable_ulp_wakeup` function can be used to enable this wakeup source.
|
||||
|
||||
@@ -95,7 +101,7 @@ In addition to EXT0 and EXT1 wakeup sources described above, one more method of
|
||||
UART wakeup (light sleep only)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
When ESP32 receives UART input from external devices, it is often required to wake up the chip when input data is available. UART peripheral contains a feature which allows waking up the chip from light sleep when a certain number of positive edges on RX pin are seen. This number of positive edges can be set using :cpp:func:`uart_set_wakeup_threshold` function. Note that the character which triggers wakeup (and any characters before it) will not be received by the UART after wakeup. This means that the external device typically needs to send an extra character to the ESP32 to trigger wakeup, before sending the data.
|
||||
When {IDF_TARGET_NAME} receives UART input from external devices, it is often required to wake up the chip when input data is available. UART peripheral contains a feature which allows waking up the chip from light sleep when a certain number of positive edges on RX pin are seen. This number of positive edges can be set using :cpp:func:`uart_set_wakeup_threshold` function. Note that the character which triggers wakeup (and any characters before it) will not be received by the UART after wakeup. This means that the external device typically needs to send an extra character to the {IDF_TARGET_NAME} to trigger wakeup, before sending the data.
|
||||
|
||||
:cpp:func:`esp_sleep_enable_uart_wakeup` function can be used to enable this wakeup source.
|
||||
|
||||
@@ -105,7 +111,9 @@ Power-down of RTC peripherals and memories
|
||||
|
||||
By default, :cpp:func:`esp_deep_sleep_start` and :cpp:func:`esp_light_sleep_start` functions will power down all RTC power domains which are not needed by the enabled wakeup sources. To override this behaviour, :cpp:func:`esp_sleep_pd_config` function is provided.
|
||||
|
||||
Note: in revision 0 of the ESP32, RTC fast memory will always be kept enabled in deep sleep, so that the deep sleep stub can run after reset. This can be overridden, if the application doesn't need clean reset behaviour after deep sleep.
|
||||
.. only:: esp32
|
||||
|
||||
Note: in revision 0 of the ESP32, RTC fast memory will always be kept enabled in deep sleep, so that the deep sleep stub can run after reset. This can be overridden, if the application doesn't need clean reset behaviour after deep sleep.
|
||||
|
||||
If some variables in the program are placed into RTC slow memory (for example, using ``RTC_DATA_ATTR`` attribute), RTC slow memory will be kept powered on by default. This can be overridden using :cpp:func:`esp_sleep_pd_config` function, if desired.
|
||||
|
||||
@@ -123,7 +131,7 @@ Entering deep sleep
|
||||
Configuring IOs
|
||||
---------------
|
||||
|
||||
Some ESP32 IOs have internal pullups or pulldowns, which are enabled by default. If an external circuit drives this pin in deep sleep mode, current consumption may increase due to current flowing through these pullups and pulldowns.
|
||||
Some {IDF_TARGET_NAME} IOs have internal pullups or pulldowns, which are enabled by default. If an external circuit drives this pin in deep sleep mode, current consumption may increase due to current flowing through these pullups and pulldowns.
|
||||
|
||||
To isolate a pin, preventing extra current draw, call :cpp:func:`rtc_gpio_isolate` function.
|
||||
|
||||
@@ -155,7 +163,7 @@ Previously configured wakeup source can be disabled later using :cpp:func:`esp_s
|
||||
|
||||
Application Example
|
||||
-------------------
|
||||
|
||||
|
||||
Implementation of basic functionality of deep sleep is shown in :example:`protocols/sntp` example, where ESP module is periodically waken up to retrieve time from NTP server.
|
||||
|
||||
More extensive example in :example:`system/deep_sleep` illustrates usage of various deep sleep wakeup triggers and ULP coprocessor programming.
|
||||
|
||||
@@ -26,7 +26,7 @@ Note that ESP-IDF supports multiple heaps with different capabilities. Functions
|
||||
Random number generation
|
||||
------------------------
|
||||
|
||||
ESP32 contains a hardware random number generator, values from it can be obtained using :cpp:func:`esp_random`.
|
||||
{IDF_TARGET_NAME} contains a hardware random number generator, values from it can be obtained using :cpp:func:`esp_random`.
|
||||
|
||||
When Wi-Fi or Bluetooth are enabled, numbers returned by hardware random number generator (RNG) can be considered true random numbers. Without Wi-Fi or Bluetooth enabled, hardware RNG is a pseudo-random number generator. At startup, ESP-IDF bootloader seeds the hardware RNG with entropy, but care must be taken when reading random values between the start of ``app_main`` and initialization of Wi-Fi or Bluetooth drivers.
|
||||
|
||||
@@ -38,32 +38,32 @@ These APIs allow querying and customizing MAC addresses for different network in
|
||||
|
||||
In ESP-IDF these addresses are calculated from *Base MAC address*. Base MAC address can be initialized with factory-programmed value from internal eFuse, or with a user-defined value. In addition to setting the base MAC address, applications can specify the way in which MAC addresses are allocated to devices. See `Number of universally administered MAC address`_ section for more details.
|
||||
|
||||
For ESP32:
|
||||
.. only:: esp32
|
||||
|
||||
+---------------+--------------------------------+----------------------------------+
|
||||
| Interface | MAC address | MAC address |
|
||||
| | (4 universally administered) | (2 universally administered) |
|
||||
+===============+================================+==================================+
|
||||
| Wi-Fi Station | base_mac | base_mac |
|
||||
+---------------+--------------------------------+----------------------------------+
|
||||
| Wi-Fi SoftAP | base_mac, +1 to the last octet | base_mac, first octet randomized |
|
||||
+---------------+--------------------------------+----------------------------------+
|
||||
| Bluetooth | base_mac, +2 to the last octet | base_mac, +1 to the last octet |
|
||||
+---------------+--------------------------------+----------------------------------+
|
||||
| Ethernet | base_mac, +3 to the last octet | base_mac, +1 to the last octet, |
|
||||
| | | first octet randomized |
|
||||
+---------------+--------------------------------+----------------------------------+
|
||||
+---------------+--------------------------------+----------------------------------+
|
||||
| Interface | MAC address | MAC address |
|
||||
| | (4 universally administered) | (2 universally administered) |
|
||||
+===============+================================+==================================+
|
||||
| Wi-Fi Station | base_mac | base_mac |
|
||||
+---------------+--------------------------------+----------------------------------+
|
||||
| Wi-Fi SoftAP | base_mac, +1 to the last octet | base_mac, first octet randomized |
|
||||
+---------------+--------------------------------+----------------------------------+
|
||||
| Bluetooth | base_mac, +2 to the last octet | base_mac, +1 to the last octet |
|
||||
+---------------+--------------------------------+----------------------------------+
|
||||
| Ethernet | base_mac, +3 to the last octet | base_mac, +1 to the last octet, |
|
||||
| | | first octet randomized |
|
||||
+---------------+--------------------------------+----------------------------------+
|
||||
|
||||
For ESP32-S2:
|
||||
.. only:: esp32s2
|
||||
|
||||
+---------------+--------------------------------+----------------------------------+
|
||||
| Interface | MAC address | MAC address |
|
||||
| | (2 universally administered) | (1 universally administered) |
|
||||
+===============+================================+==================================+
|
||||
| Wi-Fi Station | base_mac | base_mac |
|
||||
+---------------+--------------------------------+----------------------------------+
|
||||
| Wi-Fi SoftAP | base_mac, +1 to the last octet | base_mac, first octet randomized |
|
||||
+---------------+--------------------------------+----------------------------------+
|
||||
+---------------+--------------------------------+----------------------------------+
|
||||
| Interface | MAC address | MAC address |
|
||||
| | (2 universally administered) | (1 universally administered) |
|
||||
+===============+================================+==================================+
|
||||
| Wi-Fi Station | base_mac | base_mac |
|
||||
+---------------+--------------------------------+----------------------------------+
|
||||
| Wi-Fi SoftAP | base_mac, +1 to the last octet | base_mac, first octet randomized |
|
||||
+---------------+--------------------------------+----------------------------------+
|
||||
|
||||
Base MAC address
|
||||
^^^^^^^^^^^^^^^^
|
||||
@@ -101,7 +101,7 @@ Number of universally administered MAC address
|
||||
|
||||
Several MAC addresses (universally administered by IEEE) are uniquely assigned to the networking interfaces (Wi-Fi/BT/Ethernet). The final octet of each universally administered MAC address increases by one. Only the first one of them (which is called base MAC address) is stored in eFuse or external storage, the others are generated from it. Here, 'generate' means adding 0, 1, 2 and 3 (respectively) to the final octet of the base MAC address.
|
||||
|
||||
If the universally administered MAC addresses are not enough for all of the networking interfaces, locally administered MAC addresses which are derived from universally administered MAC addresses are assigned to the rest of networking interfaces.
|
||||
If the universally administered MAC addresses are not enough for all of the networking interfaces, locally administered MAC addresses which are derived from universally administered MAC addresses are assigned to the rest of networking interfaces.
|
||||
|
||||
See `this article <https://en.wikipedia.org/wiki/MAC_address#Universal_vs._local>`_ for the definition of local and universally administered MAC addresses.
|
||||
|
||||
@@ -136,7 +136,7 @@ To get the version at build time, additional version macros are provided. They c
|
||||
* :c:macro:`ESP_IDF_VERSION_MAJOR`, :c:macro:`ESP_IDF_VERSION_MINOR`, :c:macro:`ESP_IDF_VERSION_PATCH` are defined to integers representing major, minor, and patch version.
|
||||
|
||||
* :c:macro:`ESP_IDF_VERSION_VAL` and :c:macro:`ESP_IDF_VERSION` can be used when implementing version checks:
|
||||
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#include "esp_idf_version.h"
|
||||
@@ -148,7 +148,7 @@ To get the version at build time, additional version macros are provided. They c
|
||||
|
||||
App version
|
||||
-----------
|
||||
Application version is stored in :cpp:class:`esp_app_desc_t` structure. It is located in DROM sector and has a fixed offset from the beginning of the binary file.
|
||||
Application version is stored in :cpp:class:`esp_app_desc_t` structure. It is located in DROM sector and has a fixed offset from the beginning of the binary file.
|
||||
The structure is located after :cpp:class:`esp_image_header_t` and :cpp:class:`esp_image_segment_header_t` structures. The field version has string type and max length 32 chars.
|
||||
|
||||
To set version in your project manually you need to set ``PROJECT_VER`` variable in your project CMakeLists.txt/Makefile:
|
||||
|
||||
@@ -17,11 +17,11 @@ Interrupt watchdog
|
||||
|
||||
The interrupt watchdog makes sure the FreeRTOS task switching interrupt isn't blocked for a long time. This
|
||||
is bad because no other tasks, including potentially important ones like the WiFi task and the idle task,
|
||||
can't get any CPU runtime. A blocked task switching interrupt can happen because a program runs into an
|
||||
can't get any CPU runtime. A blocked task switching interrupt can happen because a program runs into an
|
||||
infinite loop with interrupts disabled or hangs in an interrupt.
|
||||
|
||||
The default action of the interrupt watchdog is to invoke the panic handler. causing a register dump and an opportunity
|
||||
for the programmer to find out, using either OpenOCD or gdbstub, what bit of code is stuck with interrupts
|
||||
for the programmer to find out, using either OpenOCD or gdbstub, what bit of code is stuck with interrupts
|
||||
disabled. Depending on the configuration of the panic handler, it can also blindly reset the CPU, which may be
|
||||
preferred in a production environment.
|
||||
|
||||
@@ -32,54 +32,54 @@ it will hard-reset the SOC.
|
||||
Task Watchdog Timer
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The Task Watchdog Timer (TWDT) is responsible for detecting instances of tasks
|
||||
running for a prolonged period of time without yielding. This is a symptom of
|
||||
The Task Watchdog Timer (TWDT) is responsible for detecting instances of tasks
|
||||
running for a prolonged period of time without yielding. This is a symptom of
|
||||
CPU starvation and is usually caused by a higher priority task looping without
|
||||
yielding to a lower-priority task thus starving the lower priority task from
|
||||
CPU time. This can be an indicator of poorly written code that spinloops on a
|
||||
peripheral, or a task that is stuck in an infinite loop.
|
||||
peripheral, or a task that is stuck in an infinite loop.
|
||||
|
||||
By default the TWDT will watch the Idle Tasks of each CPU, however any task can
|
||||
By default the TWDT will watch the Idle Tasks of each CPU, however any task can
|
||||
elect to be watched by the TWDT. Each watched task must 'reset' the TWDT
|
||||
periodically to indicate that they have been allocated CPU time. If a task does
|
||||
not reset within the TWDT timeout period, a warning will be printed with
|
||||
information about which tasks failed to reset the TWDT in time and which
|
||||
tasks are currently running on the ESP32 CPUs.
|
||||
And also there is a possibility to redefine the function `esp_task_wdt_isr_user_handler`
|
||||
periodically to indicate that they have been allocated CPU time. If a task does
|
||||
not reset within the TWDT timeout period, a warning will be printed with
|
||||
information about which tasks failed to reset the TWDT in time and which
|
||||
tasks are currently running on the {IDF_TARGET_NAME} CPUs.
|
||||
And also there is a possibility to redefine the function `esp_task_wdt_isr_user_handler`
|
||||
in the user code to receive this event.
|
||||
|
||||
The TWDT is built around the Hardware Watchdog Timer in Timer Group 0. The TWDT
|
||||
can be initialized by calling :cpp:func:`esp_task_wdt_init` which will configure
|
||||
the hardware timer. A task can then subscribe to the TWDT using
|
||||
:cpp:func:`esp_task_wdt_add` in order to be watched. Each subscribed task must
|
||||
periodically call :cpp:func:`esp_task_wdt_reset` to reset the TWDT. Failure by
|
||||
the hardware timer. A task can then subscribe to the TWDT using
|
||||
:cpp:func:`esp_task_wdt_add` in order to be watched. Each subscribed task must
|
||||
periodically call :cpp:func:`esp_task_wdt_reset` to reset the TWDT. Failure by
|
||||
any subscribed tasks to periodically call :cpp:func:`esp_task_wdt_reset`
|
||||
indicates that one or more tasks have been starved of CPU time or are stuck in a
|
||||
loop somewhere.
|
||||
|
||||
A watched task can be unsubscribed from the TWDT using
|
||||
:cpp:func:`esp_task_wdt_delete()`. A task that has been unsubscribed should no
|
||||
A watched task can be unsubscribed from the TWDT using
|
||||
:cpp:func:`esp_task_wdt_delete()`. A task that has been unsubscribed should no
|
||||
longer call :cpp:func:`esp_task_wdt_reset`. Once all tasks have unsubscribed
|
||||
form the TWDT, the TWDT can be deinitialized by calling
|
||||
form the TWDT, the TWDT can be deinitialized by calling
|
||||
:cpp:func:`esp_task_wdt_deinit()`.
|
||||
|
||||
By default :ref:`CONFIG_ESP_TASK_WDT` in :ref:`project-configuration-menu` be enabled causing
|
||||
the TWDT to be initialized automatically during startup. Likewise
|
||||
:ref:`CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU0` and
|
||||
:ref:`CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU0` and
|
||||
:ref:`CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU1` are also enabled by default causing
|
||||
the two Idle Tasks to be subscribed to the TWDT during startup.
|
||||
|
||||
JTAG and watchdogs
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
While debugging using OpenOCD, the CPUs will be halted every time a breakpoint
|
||||
is reached. However if the watchdog timers continue to run when a breakpoint is
|
||||
encountered, they will eventually trigger a reset making it very difficult to
|
||||
debug code. Therefore OpenOCD will disable the hardware timers of both the
|
||||
interrupt and task watchdogs at every breakpoint. Moreover, OpenOCD will not
|
||||
While debugging using OpenOCD, the CPUs will be halted every time a breakpoint
|
||||
is reached. However if the watchdog timers continue to run when a breakpoint is
|
||||
encountered, they will eventually trigger a reset making it very difficult to
|
||||
debug code. Therefore OpenOCD will disable the hardware timers of both the
|
||||
interrupt and task watchdogs at every breakpoint. Moreover, OpenOCD will not
|
||||
reenable them upon leaving the breakpoint. This means that interrupt watchdog
|
||||
and task watchdog functionality will essentially be disabled. No warnings or
|
||||
panics from either watchdogs will be generated when the ESP32 is connected to
|
||||
and task watchdog functionality will essentially be disabled. No warnings or
|
||||
panics from either watchdogs will be generated when the {IDF_TARGET_NAME} is connected to
|
||||
OpenOCD via JTAG.
|
||||
|
||||
|
||||
@@ -89,12 +89,12 @@ Interrupt Watchdog API Reference
|
||||
Header File
|
||||
^^^^^^^^^^^
|
||||
|
||||
* :component_file:`esp32/include/esp_int_wdt.h`
|
||||
* :component_file:`{IDF_TARGET_PATH_NAME}/include/esp_int_wdt.h`
|
||||
|
||||
|
||||
Functions
|
||||
---------
|
||||
|
||||
|
||||
.. doxygenfunction:: esp_int_wdt_init
|
||||
|
||||
Task Watchdog API Reference
|
||||
|
||||
Reference in New Issue
Block a user