esp_algorithm_image struct

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. 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| | | | | | | | | <---------(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 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 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 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 .bss start | | | | | |___________________________________________| | stub stack base | | | | | |___________________________________________| | | | | |___________________________________________| | | | | |___________________________________________| ___________________________________________ | code space working area start | | | | | |___________________________________________| | | | | |___________________________________________| For example on how to execute external code with memory arguments @see 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 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 @see 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 @see esp32_cmd_gcov() in ESP32 apptrace module. Algorithm image data. Helper struct to work with algorithms consisting of code and data segments.