API defined below allows executing pieces of code on target without breaking the execution of the running program. More...
Data Fields | |
| uint32_t | bss_size |
| BSS section size. More... | |
| uint32_t | dram_len |
| Total reserved DRAM size. More... | |
| uint32_t | dram_org |
| DRAM start address in the linker script. More... | |
| struct image | image |
| Image. More... | |
| uint32_t | iram_len |
| Total reserved IRAM size. More... | |
| uint32_t | iram_org |
| IRAM start address in the linker script. More... | |
| bool | reverse |
| IRAM DRAM address range reversed or not. More... | |
Detailed Description
API defined below allows executing pieces of code on target without breaking the execution of the running program.
This functionality can be useful for various debugging and maintenance procedures.
- Note
- ESP flashing code to load flasher stub on target and write/read/erase flash. Also ESP GCOV command uses some of these functions to run onboard routines to dump coverage info. Stub entry function can take up to 5 arguments and should be of the following form:
int stub_entry([uint32_t a1 [, uint32_t a2 [, uint32_t a3 [, uint32_t a4 [, uint32_t a5]]]]]);
The general scheme of stub code execution is shown below.
----— --------— (initial frame) -— | | ----—(registers, stub entry, stub args)---—> |trampoline | —(stub args)—> | | | | | | | | |OpenOCD| <-------—(stub-specific communications)------------------------------------—> |stub| | | | | | | | | <------—(target halted event, ret code)----— |tramp break| <—(ret code)-— | |
Procedure of executing stub on target includes: 1) User prepares struct esp_algorithm_run_data and calls one of algorithm_run_xxx() functions. 2) Routine allocates all necessary stub code and data sections. 3) If a user specifies an initializer func esp_algorithm_usr_func_init_t it is called just before the stub starts. 4) If user specifies stub communication func esp_algorithm_usr_func_t (
- See also
- esp_flash_write/read in ESP flash driver) it is called just after the stub starts. When communication with stub is finished this function must return. 5) OpenOCD waits for the stub to finish (hit exit breakpoint). 6) If the user specified arguments cleanup func esp_algorithm_usr_func_done_t, it is called just after the stub finishes.
There are two options to run code on target under OpenOCD control:
- Run externally compiled stub code.
- Run onboard pre-compiled code.
- Note
- For ESP chips debug stubs must be enabled in target code
- See also
- ESP IDF docs. The main difference between the execution of external stub code and target built-in functions is that in the latter case working areas can not be used to allocate target memory for code and data because they can overlap with code and data involved in onboard function execution. For example, if memory allocated in the working area for the stub stack will overlap with some on-board data used by the stub the stack will get overwritten. The same stands for allocations in target code space.
External Code Execution
To run external code on the target user should use esp_algorithm_run_func_image(). In this case all necessary memory (code/data) is allocated in working areas that have fixed configuration defined in target TCL file. Stub code is actually a standalone program, so all its segments must have known addresses due to position-dependent code nature. So stub must be linked in such a way that its code segment starts at the beginning of the working area for code space defined in TCL. The same restriction must be applied to stub's data segment and base addresses of working area for data space.
- See also
- ESP stub flasher LD scripts. Also in order to simplify memory allocation BSS section must follow the DATA section in the stub image. The size of the BSS section must be specified in the bss_size field of struct algorithm_image. Sample stub memory map is shown below.
data space working area start <stub .data segment> ___________________________________________ stub .bss start <stub .bss segment of size 'bss_size'> ___________________________________________ stub stack base <stub stack> ___________________________________________ <stub mem arg1> ___________________________________________ <stub mem arg2> ___________________________________________
code space working area start <stub .text segment> ___________________________________________ <stub trampoline with exit breakpoint> ___________________________________________
For example on how to execute external code with memory arguments
- See also
- esp_algo_flash_blank_check in ESP flash driver.
On-Board Code Execution
To run on-board code on the target user should use esp_algorithm_run_onboard_func(). On-board code execution process does not need to allocate target memory for stub code and data, Because the stub is pre-compiled to the code running on the target. But it still needs memory for stub trampoline, stack, and memory arguments. Working areas can not be used due to possible memory layout conflicts with on-board stub code and data. Debug stubs functionality provided by ESP IDF allows OpenOCD to overcome the above problem. It provides a special descriptor which provides info necessary to safely allocate memory on target.
- See also
- struct esp_dbg_stubs_desc. That info is also used to locate memory for stub trampoline code. User can execute target function at any address, but
- ESP IDF debug stubs also provide a way to pass to the host an entry address of pre-defined registered stub functions. For example of an on-board code execution
- esp32_cmd_gcov() in ESP32 apptrace module. Algorithm image data. Helper struct to work with algorithms consisting of code and data segments.
Definition at line 117 of file esp_algorithm.h.
Field Documentation
◆ bss_size
| uint32_t esp_algorithm_image::bss_size |
BSS section size.
Definition at line 121 of file esp_algorithm.h.
Referenced by esp_algorithm_load_func_image().
◆ dram_len
| uint32_t esp_algorithm_image::dram_len |
Total reserved DRAM size.
Definition at line 129 of file esp_algorithm.h.
◆ dram_org
| uint32_t esp_algorithm_image::dram_org |
DRAM start address in the linker script.
Definition at line 127 of file esp_algorithm.h.
Referenced by esp_algorithm_load_func_image(), and load_section_from_image().
◆ image
| struct image esp_algorithm_image::image |
Image.
Definition at line 409 of file esp_algorithm.h.
Referenced by esp_algorithm_exec_func_image_va(), esp_algorithm_load_func_image(), and load_section_from_image().
◆ iram_len
| uint32_t esp_algorithm_image::iram_len |
Total reserved IRAM size.
Definition at line 125 of file esp_algorithm.h.
Referenced by esp_algorithm_load_func_image().
◆ iram_org
| uint32_t esp_algorithm_image::iram_org |
IRAM start address in the linker script.
Definition at line 123 of file esp_algorithm.h.
Referenced by esp_algorithm_load_func_image().
◆ reverse
| bool esp_algorithm_image::reverse |
IRAM DRAM address range reversed or not.
Definition at line 131 of file esp_algorithm.h.
Referenced by esp_algorithm_load_func_image().
The documentation for this struct was generated from the following file:
