linuxmsm/openocd
0
0
Fork 0
mirror of https://github.com/linux-msm/openocd.git synced 2026-02-25 13:15:07 -08:00
Code Issues Packages Projects Releases Wiki Activity

target/espressif: add algorithm support to execute code on target

Browse Source 
This functionality can be useful for;
1-ESP flashing code to load flasher stub on target and
write/read/erase flash.
2-ESP GCOV command uses some of these functions to run
onboard routines to dump coverage info.

This is high level api for the Espressif xtensa and riscv targets

Signed-off-by: Erhan Kurubas <erhan.kurubas@espressif.com>
Change-Id: I5e618b960bb6566ee618d4ba261f51af97a7cb0e
Reviewed-on: https://review.openocd.org/c/openocd/+/7759
Reviewed-by: Tomas Vanek <vanekt@fbl.cz>
Reviewed-by: Antonio Borneo <borneo.antonio@gmail.com>
Tested-by: jenkins
This commit is contained in:
Erhan Kurubas
2023-07-03 11:02:13 +02:00
committed by Antonio Borneo
parent ba16fdc1c6
commit d3ffcc784d
5 changed files with 1103 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
src/target/espressif/Makefile.am
View File

@@ -21,4 +21,6 @@ noinst_LTLIBRARIES += %D%/libespressif.la
%D%/esp32_sysview.h \
%D%/segger_sysview.h \
%D%/esp_semihosting.c \
%D%/esp_semihosting.h
%D%/esp_semihosting.h \
%D%/esp_algorithm.c \
%D%/esp_algorithm.h

595
src/target/espressif/esp_algorithm.c Normal file
View File

File diff suppressed because it is too large Load Diff

420
src/target/espressif/esp_algorithm.h Normal file
View File

@@ -0,0 +1,420 @@
/* SPDX-License-Identifier: GPL-2.0-or-later */
/***************************************************************************
* Espressif chips common algorithm API for OpenOCD *
* Copyright (C) 2022 Espressif Systems Ltd. *
***************************************************************************/
#ifndef OPENOCD_TARGET_ESP_ALGORITHM_H
#define OPENOCD_TARGET_ESP_ALGORITHM_H
#include "helper/log.h"
#include "helper/binarybuffer.h"
#include <helper/time_support.h>
#include <target/algorithm.h>
#include <target/image.h>
/**
* 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 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 .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 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.
*/
struct esp_algorithm_image {
/** Image. */
struct image image;
/** BSS section size. */
uint32_t bss_size;
/** IRAM start address in the linker script */
uint32_t iram_org;
/** Total reserved IRAM size */
uint32_t iram_len;
/** DRAM start address in the linker script */
uint32_t dram_org;
/** Total reserved DRAM size */
uint32_t dram_len;
/** IRAM DRAM address range reversed or not */
bool reverse;
};
#define ESP_IMAGE_ELF_PHF_EXEC 0x1
/**
* Algorithm stub data.
*/
struct esp_algorithm_stub {
/** Entry addr. */
target_addr_t entry;
/** Working area for code segment. */
struct working_area *code;
/** Working area for data segment. */
struct working_area *data;
/** Working area for trampoline. */
struct working_area *tramp;
/** Working area for padding between code and data area. */
struct working_area *padding;
/** Address of the target buffer for stub trampoline. If zero tramp->address will be used. */
target_addr_t tramp_addr;
/** Tramp code area will be filled from dbus.
* We need to map it to the ibus to be able to initialize PC register to start algorithm execution from.
*/
target_addr_t tramp_mapped_addr;
/** Working area for stack. */
struct working_area *stack;
/** Address of the target buffer for stack. If zero tramp->address will be used. */
target_addr_t stack_addr;
/** Address of the log buffer */
target_addr_t log_buff_addr;
/** Size of the log buffer */
uint32_t log_buff_size;
/** Algorithm's arch-specific info. */
void *ainfo;
};
/**
* Algorithm stub in-memory arguments.
*/
struct esp_algorithm_mem_args {
/** Memory params. */
struct mem_param *params;
/** Number of memory params. */
uint32_t count;
};
/**
* Algorithm stub register arguments.
*/
struct esp_algorithm_reg_args {
/** Algorithm register params. User args start from user_first_reg_param */
struct reg_param *params;
/** Number of register params. */
uint32_t count;
/** The first several reg_params can be used by stub itself (e.g. for trampoline).
* This is the index of the first reg_param available for user to pass args to algorithm stub. */
uint32_t first_user_param;
};
struct esp_algorithm_run_data;
/**
* @brief Algorithm run function.
*
* @param target Pointer to target.
* @param run Pointer to algo run data.
* @param arg Function specific argument.
*
* @return ERROR_OK on success, otherwise ERROR_XXX.
*/
typedef int (*esp_algorithm_func_t)(struct target *target, struct esp_algorithm_run_data *run, void *arg);
/**
* @brief Host part of algorithm.
* This function will be called while stub is running on target.
* It can be used for communication with stub.
*
* @param target Pointer to target.
* @param usr_arg Function specific argument.
*
* @return ERROR_OK on success, otherwise ERROR_XXX.
*/
typedef int (*esp_algorithm_usr_func_t)(struct target *target, void *usr_arg);
/**
* @brief Algorithm's arguments setup function.
* This function will be called just before stub start.
* It must return when all operations with running stub are completed.
* It can be used to prepare stub memory parameters.
*
* @param target Pointer to target.
* @param run Pointer to algo run data.
* @param usr_arg Function specific argument. The same as for esp_algorithm_usr_func_t.
*
* @return ERROR_OK on success, otherwise ERROR_XXX.
*/
typedef int (*esp_algorithm_usr_func_init_t)(struct target *target,
struct esp_algorithm_run_data *run,
void *usr_arg);
/**
* @brief Algorithm's arguments cleanup function.
* This function will be called just after stub exit.
* It can be used to cleanup stub memory parameters.
*
* @param target Pointer to target.
* @param run Pointer to algo run data.
* @param usr_arg Function specific argument. The same as for esp_algorithm_usr_func_t.
*
* @return ERROR_OK on success, otherwise ERROR_XXX.
*/
typedef void (*esp_algorithm_usr_func_done_t)(struct target *target,
struct esp_algorithm_run_data *run,
void *usr_arg);
struct esp_algorithm_hw {
int (*algo_init)(struct target *target, struct esp_algorithm_run_data *run, uint32_t num_args, va_list ap);
int (*algo_cleanup)(struct target *target, struct esp_algorithm_run_data *run);
const uint8_t *(*stub_tramp_get)(struct target *target, size_t *size);
};
/**
* Algorithm run data.
*/
struct esp_algorithm_run_data {
/** Algorithm completion timeout in ms. If 0, default value will be used */
uint32_t timeout_ms;
/** Algorithm stack size. */
uint32_t stack_size;
/** Algorithm register arguments. */
struct esp_algorithm_reg_args reg_args;
/** Algorithm memory arguments. */
struct esp_algorithm_mem_args mem_args;
/** Algorithm arch-specific info. For Xtensa this should point to struct xtensa_algorithm. */
void *arch_info;
/** Algorithm return code. */
int32_t ret_code;
/** Stub. */
struct esp_algorithm_stub stub;
union {
struct {
/** Size of the pre-alocated on-board buffer for stub's code. */
uint32_t code_buf_size;
/** Address of pre-compiled target buffer for stub trampoline. */
target_addr_t code_buf_addr;
/** Size of the pre-alocated on-board buffer for stub's stack. */
uint32_t min_stack_size;
/** Pre-compiled target buffer's addr for stack. */
target_addr_t min_stack_addr;
} on_board;
struct esp_algorithm_image image;
};
/** Host side algorithm function argument. */
void *usr_func_arg;
/** Host side algorithm function. */
esp_algorithm_usr_func_t usr_func;
/** Host side algorithm function setup routine. */
esp_algorithm_usr_func_init_t usr_func_init;
/** Host side algorithm function cleanup routine. */
esp_algorithm_usr_func_done_t usr_func_done;
/** Algorithm run function: see algorithm_run_xxx for example. */
esp_algorithm_func_t algo_func;
/** HW specific API */
const struct esp_algorithm_hw *hw;
};
int esp_algorithm_load_func_image(struct target *target, struct esp_algorithm_run_data *run);
int esp_algorithm_unload_func_image(struct target *target, struct esp_algorithm_run_data *run);
int esp_algorithm_exec_func_image_va(struct target *target,
struct esp_algorithm_run_data *run,
uint32_t num_args,
va_list ap);
/**
* @brief Loads and runs stub from specified image.
* This function should be used to run external stub code on target.
*
* @param target Pointer to target.
* @param run Pointer to algo run data.
* @param num_args Number of stub arguments that follow.
*
* @return ERROR_OK on success, otherwise ERROR_XXX. Stub return code is in run->ret_code.
*/
static inline int esp_algorithm_run_func_image_va(struct target *target,
struct esp_algorithm_run_data *run,
uint32_t num_args,
va_list ap)
{
int ret = esp_algorithm_load_func_image(target, run);
if (ret != ERROR_OK)
return ret;
ret = esp_algorithm_exec_func_image_va(target, run, num_args, ap);
int rc = esp_algorithm_unload_func_image(target, run);
return ret != ERROR_OK ? ret : rc;
}
static inline int esp_algorithm_run_func_image(struct target *target,
struct esp_algorithm_run_data *run,
uint32_t num_args,
...)
{
va_list ap;
va_start(ap, num_args);
int retval = esp_algorithm_run_func_image_va(target, run, num_args, ap);
va_end(ap);
return retval;
}
int esp_algorithm_load_onboard_func(struct target *target,
target_addr_t func_addr,
struct esp_algorithm_run_data *run);
int esp_algorithm_unload_onboard_func(struct target *target, struct esp_algorithm_run_data *run);
int esp_algorithm_exec_onboard_func_va(struct target *target,
struct esp_algorithm_run_data *run,
uint32_t num_args,
va_list ap);
/**
* @brief Runs pre-compiled on-board function.
* This function should be used to run on-board stub code.
*
* @param target Pointer to target.
* @param run Pointer to algo run data.
* @param func_entry Address of the function to run.
* @param num_args Number of function arguments that follow.
*
* @return ERROR_OK on success, otherwise ERROR_XXX. Stub return code is in run->ret_code.
*/
static inline int esp_algorithm_run_onboard_func_va(struct target *target,
struct esp_algorithm_run_data *run,
target_addr_t func_addr,
uint32_t num_args,
va_list ap)
{
int ret = esp_algorithm_load_onboard_func(target, func_addr, run);
if (ret != ERROR_OK)
return ret;
ret = esp_algorithm_exec_onboard_func_va(target, run, num_args, ap);
if (ret != ERROR_OK)
return ret;
return esp_algorithm_unload_onboard_func(target, run);
}
static inline int esp_algorithm_run_onboard_func(struct target *target,
struct esp_algorithm_run_data *run,
target_addr_t func_addr,
uint32_t num_args,
...)
{
va_list ap;
va_start(ap, num_args);
int retval = esp_algorithm_run_onboard_func_va(target, run, func_addr, num_args, ap);
va_end(ap);
return retval;
}
/**
* @brief Set the value of an argument passed via registers to the stub main function.
*/
static inline void esp_algorithm_user_arg_set_uint(struct esp_algorithm_run_data *run,
int arg_num,
uint64_t val)
{
struct reg_param *param = &run->reg_args.params[run->reg_args.first_user_param + arg_num];
assert(param->size <= 64);
if (param->size <= 32)
buf_set_u32(param->value, 0, param->size, val);
else
buf_set_u64(param->value, 0, param->size, val);
}
/**
* @brief Get the value of an argument passed via registers from the stub main function.
*/
static inline uint64_t esp_algorithm_user_arg_get_uint(struct esp_algorithm_run_data *run, int arg_num)
{
struct reg_param *param = &run->reg_args.params[run->reg_args.first_user_param + arg_num];
assert(param->size <= 64);
if (param->size <= 32)
return buf_get_u32(param->value, 0, param->size);
return buf_get_u64(param->value, 0, param->size);
}
#endif /* OPENOCD_TARGET_ESP_ALGORITHM_H */

78
src/target/espressif/esp_xtensa_smp.c
View File

@@ -16,6 +16,7 @@
#include <target/semihosting_common.h>
#include "esp_xtensa_smp.h"
#include "esp_xtensa_semihosting.h"
#include "esp_algorithm.h"
/*
Multiprocessor stuff common:
@@ -495,6 +496,83 @@ int esp_xtensa_smp_watchpoint_remove(struct target *target, struct watchpoint *w
return ERROR_OK;
}
int esp_xtensa_smp_run_func_image(struct target *target, struct esp_algorithm_run_data *run, uint32_t num_args, ...)
{
struct target *run_target = target;
struct target_list *head;
va_list ap;
uint32_t smp_break = 0;
int res;
if (target->smp) {
/* find first HALTED and examined core */
foreach_smp_target(head, target->smp_targets) {
run_target = head->target;
if (target_was_examined(run_target) && run_target->state == TARGET_HALTED)
break;
}
if (!head) {
LOG_ERROR("Failed to find HALTED core!");
return ERROR_FAIL;
}
res = esp_xtensa_smp_smpbreak_disable(run_target, &smp_break);
if (res != ERROR_OK)
return res;
}
va_start(ap, num_args);
int algo_res = esp_algorithm_run_func_image_va(run_target, run, num_args, ap);
va_end(ap);
if (target->smp) {
res = esp_xtensa_smp_smpbreak_restore(run_target, smp_break);
if (res != ERROR_OK)
return res;
}
return algo_res;
}
int esp_xtensa_smp_run_onboard_func(struct target *target,
struct esp_algorithm_run_data *run,
uint32_t func_addr,
uint32_t num_args,
...)
{
struct target *run_target = target;
struct target_list *head;
va_list ap;
uint32_t smp_break = 0;
int res;
if (target->smp) {
/* find first HALTED and examined core */
foreach_smp_target(head, target->smp_targets) {
run_target = head->target;
if (target_was_examined(run_target) && run_target->state == TARGET_HALTED)
break;
}
if (!head) {
LOG_ERROR("Failed to find HALTED core!");
return ERROR_FAIL;
}
res = esp_xtensa_smp_smpbreak_disable(run_target, &smp_break);
if (res != ERROR_OK)
return res;
}
va_start(ap, num_args);
int algo_res = esp_algorithm_run_onboard_func_va(run_target, run, func_addr, num_args, ap);
va_end(ap);
if (target->smp) {
res = esp_xtensa_smp_smpbreak_restore(run_target, smp_break);
if (res != ERROR_OK)
return res;
}
return algo_res;
}
int esp_xtensa_smp_init_arch_info(struct target *target,
struct esp_xtensa_smp_common *esp_xtensa_smp,
struct xtensa_debug_module_config *dm_cfg,

8
src/target/espressif/esp_xtensa_smp.h
View File

@@ -9,6 +9,7 @@
#define OPENOCD_TARGET_XTENSA_ESP_SMP_H
#include "esp_xtensa.h"
#include "esp_algorithm.h"
struct esp_xtensa_smp_chip_ops {
int (*poll)(struct target *target);
@@ -47,7 +48,12 @@ int esp_xtensa_smp_init_arch_info(struct target *target,
struct xtensa_debug_module_config *dm_cfg,
const struct esp_xtensa_smp_chip_ops *chip_ops,
const struct esp_semihost_ops *semihost_ops);
int esp_xtensa_smp_run_func_image(struct target *target, struct esp_algorithm_run_data *run, uint32_t num_args, ...);
int esp_xtensa_smp_run_onboard_func(struct target *target,
struct esp_algorithm_run_data *run,
uint32_t func_addr,
uint32_t num_args,
...);
extern const struct command_registration esp_xtensa_smp_command_handlers[];
extern const struct command_registration esp_xtensa_smp_xtensa_command_handlers[];
extern const struct command_registration esp_xtensa_smp_esp_command_handlers[];