src/target/espressif/esp_algorithm.h

   1 /* SPDX-License-Identifier: GPL-2.0-or-later */
   2
   3 /***************************************************************************
   4  *   Espressif chips common algorithm API for OpenOCD                      *
   5  *   Copyright (C) 2022 Espressif Systems Ltd.                             *
   6  ***************************************************************************/
   7
   8 #ifndef OPENOCD_TARGET_ESP_ALGORITHM_H
   9 #define OPENOCD_TARGET_ESP_ALGORITHM_H
  10
  11 #include "helper/log.h"
  12 #include "helper/binarybuffer.h"
  13 #include <helper/time_support.h>
  14 #include <target/algorithm.h>
  15 #include <target/image.h>
  16
  17 /**
  18  * API defined below allows executing pieces of code on target without breaking the execution of the running program.
  19  * This functionality can be useful for various debugging and maintenance procedures.
  20  * @note ESP flashing code to load flasher stub on target and write/read/erase flash.
  21  * Also ESP GCOV command uses some of these functions to run onboard routines to dump coverage info.
  22  * Stub entry function can take up to 5 arguments and should be of the following form:
  23  *
  24  * int stub_entry([uint32_t a1 [, uint32_t a2 [, uint32_t a3 [, uint32_t a4 [, uint32_t a5]]]]]);
  25  *
  26  * The general scheme of stub code execution is shown below.
  27  *
  28  *  -------                                                    -----------   (initial frame)    ----
  29  * |       | -------(registers, stub entry, stub args)------> |trampoline | ---(stub args)---> |    |
  30  * |       |                                                  |           |                    |    |
  31  * |OpenOCD| <----------(stub-specific communications)---------------------------------------> |stub|
  32  * |       |                                                  |           |                    |    |
  33  * |       | <---------(target halted event, ret code)------- |tramp break| <---(ret code)---- |    |
  34  *  -------                                                    -----------                      ----
  35  *
  36  * Procedure of executing stub on target includes:
  37  * 1) User prepares struct esp_algorithm_run_data and calls one of algorithm_run_xxx() functions.
  38  * 2) Routine allocates all necessary stub code and data sections.
  39  * 3) If a user specifies an initializer func esp_algorithm_usr_func_init_t it is called just before the stub starts.
  40  * 4) If user specifies stub communication func esp_algorithm_usr_func_t (@see esp_flash_write/read in ESP flash driver)
  41  *    it is called just after the stub starts. When communication with stub is finished this function must return.
  42  * 5) OpenOCD waits for the stub to finish (hit exit breakpoint).
  43  * 6) If the user specified arguments cleanup func esp_algorithm_usr_func_done_t,
  44  *    it is called just after the stub finishes.
  45  *
  46  * There are two options to run code on target under OpenOCD control:
  47  * - Run externally compiled stub code.
  48  * - Run onboard pre-compiled code. @note For ESP chips debug stubs must be enabled in target code @see ESP IDF docs.
  49  * The main difference between the execution of external stub code and target built-in functions is that
  50  * in the latter case working areas can not be used to allocate target memory for code and data because they can overlap
  51  * with code and data involved in onboard function execution. For example, if memory allocated in the working area
  52  * for the stub stack will overlap with some on-board data used by the stub the stack will get overwritten.
  53  * The same stands for allocations in target code space.
  54  *
  55  * External Code Execution
  56  * -----------------------
  57  * To run external code on the target user should use esp_algorithm_run_func_image().
  58  * In this case all necessary memory (code/data) is allocated in working areas that have fixed configuration
  59  * defined in target TCL file. Stub code is actually a standalone program, so all its segments must have known
  60  * addresses due to position-dependent code nature. So stub must be linked in such a way that its code segment
  61  * starts at the beginning of the working area for code space defined in TCL. The same restriction must be applied
  62  * to stub's data segment and base addresses of working area for data space. @see ESP stub flasher LD scripts.
  63  * Also in order to simplify memory allocation BSS section must follow the DATA section in the stub image.
  64  * The size of the BSS section must be specified in the bss_size field of struct algorithm_image.
  65  * Sample stub memory map is shown below.
  66  *  ___________________________________________
  67  * | data space working area start             |
  68  * |                                           |
  69  * | <stub .data segment>                      |
  70  * |___________________________________________|
  71  * | stub .bss start                           |
  72  * |                                           |
  73  * | <stub .bss segment of size 'bss_size'>    |
  74  * |___________________________________________|
  75  * | stub stack base                           |
  76  * |                                           |
  77  * | <stub stack>                              |
  78  * |___________________________________________|
  79  * |                                           |
  80  * | <stub mem arg1>                           |
  81  * |___________________________________________|
  82  * |                                           |
  83  * | <stub mem arg2>                           |
  84  * |___________________________________________|
  85  *  ___________________________________________
  86  * | code space working area start             |
  87  * |                                           |
  88  * | <stub .text segment>                      |
  89  * |___________________________________________|
  90  * |                                           |
  91  * | <stub trampoline with exit breakpoint>    |
  92  * |___________________________________________|
  93  *
  94  * For example on how to execute external code with memory arguments @see esp_algo_flash_blank_check in
  95  * ESP flash driver.
  96  *
  97  * On-Board Code Execution
  98  * -----------------------
  99  * To run on-board code on the target user should use esp_algorithm_run_onboard_func().
 100  * On-board code execution process does not need to allocate target memory for stub code and data,
 101  * Because the stub is pre-compiled to the code running on the target.
 102  * But it still needs memory for stub trampoline, stack, and memory arguments.
 103  * Working areas can not be used due to possible memory layout conflicts with on-board stub code and data.
 104  * Debug stubs functionality provided by ESP IDF allows OpenOCD to overcome the above problem.
 105  * It provides a special descriptor which provides info necessary to safely allocate memory on target.
 106  * @see struct esp_dbg_stubs_desc.
 107  * That info is also used to locate memory for stub trampoline code.
 108  * User can execute target function at any address, but @see ESP IDF debug stubs also provide a way to pass to the host
 109  * an entry address of pre-defined registered stub functions.
 110  * For example of an on-board code execution @see esp32_cmd_gcov() in ESP32 apptrace module.
 111 */
 112
 113 /**
 114  * Algorithm image data.
 115  * Helper struct to work with algorithms consisting of code and data segments.
 116  */
 117 struct esp_algorithm_image {
 118         /** Image. */
 119         struct image image;
 120         /** BSS section size. */
 121         uint32_t bss_size;
 122         /** IRAM start address in the linker script */
 123         uint32_t iram_org;
 124         /** Total reserved IRAM size */
 125         uint32_t iram_len;
 126         /** DRAM start address in the linker script */
 127         uint32_t dram_org;
 128         /** Total reserved DRAM size */
 129         uint32_t dram_len;
 130         /** IRAM DRAM address range reversed or not */
 131         bool reverse;
 132 };
 133
 134 #define ESP_IMAGE_ELF_PHF_EXEC                  0x1
 135
 136 /**
 137  * Algorithm stub data.
 138  */
 139 struct esp_algorithm_stub {
 140         /** Entry addr. */
 141         target_addr_t entry;
 142         /** Working area for code segment. */
 143         struct working_area *code;
 144         /** Working area for data segment. */
 145         struct working_area *data;
 146         /** Working area for trampoline. */
 147         struct working_area *tramp;
 148         /** Working area for padding between code and data area. */
 149         struct working_area *padding;
 150         /** Address of the target buffer for stub trampoline. If zero tramp->address will be used. */
 151         target_addr_t tramp_addr;
 152         /** Tramp code area will be filled from dbus.
 153          *  We need to map it to the ibus to be able to initialize PC register to start algorithm execution from.
 154          */
 155         target_addr_t tramp_mapped_addr;
 156         /** Working area for stack. */
 157         struct working_area *stack;
 158         /** Address of the target buffer for stack. If zero tramp->address will be used. */
 159         target_addr_t stack_addr;
 160         /** Address of the log buffer */
 161         target_addr_t log_buff_addr;
 162         /** Size of the log buffer */
 163         uint32_t log_buff_size;
 164         /** Algorithm's arch-specific info. */
 165         void *ainfo;
 166 };
 167
 168 /**
 169  * Algorithm stub in-memory arguments.
 170  */
 171 struct esp_algorithm_mem_args {
 172         /** Memory params. */
 173         struct mem_param *params;
 174         /** Number of memory params. */
 175         uint32_t count;
 176 };
 177
 178 /**
 179  * Algorithm stub register arguments.
 180  */
 181 struct esp_algorithm_reg_args {
 182         /** Algorithm register params. User args start from user_first_reg_param */
 183         struct reg_param *params;
 184         /** Number of register params. */
 185         uint32_t count;
 186         /** The first several reg_params can be used by stub itself (e.g. for trampoline).
 187          * This is the index of the first reg_param available for user to pass args to algorithm stub. */
 188         uint32_t first_user_param;
 189 };
 190
 191 struct esp_algorithm_run_data;
 192
 193 /**
 194  * @brief Algorithm run function.
 195  *
 196  * @param target Pointer to target.
 197  * @param run    Pointer to algo run data.
 198  * @param arg    Function specific argument.
 199  *
 200  * @return ERROR_OK on success, otherwise ERROR_XXX.
 201  */
 202 typedef int (*esp_algorithm_func_t)(struct target *target, struct esp_algorithm_run_data *run, void *arg);
 203
 204 /**
 205  * @brief Host part of algorithm.
 206  *        This function will be called while stub is running on target.
 207  *        It can be used for communication with stub.
 208  *
 209  * @param target  Pointer to target.
 210  * @param usr_arg Function specific argument.
 211  *
 212  * @return ERROR_OK on success, otherwise ERROR_XXX.
 213  */
 214 typedef int (*esp_algorithm_usr_func_t)(struct target *target, void *usr_arg);
 215
 216 /**
 217  * @brief Algorithm's arguments setup function.
 218  *        This function will be called just before stub start.
 219  *        It must return when all operations with running stub are completed.
 220  *        It can be used to prepare stub memory parameters.
 221  *
 222  * @param target  Pointer to target.
 223  * @param run     Pointer to algo run data.
 224  * @param usr_arg Function specific argument. The same as for esp_algorithm_usr_func_t.
 225  *
 226  * @return ERROR_OK on success, otherwise ERROR_XXX.
 227  */
 228 typedef int (*esp_algorithm_usr_func_init_t)(struct target *target,
 229         struct esp_algorithm_run_data *run,
 230         void *usr_arg);
 231
 232 /**
 233  * @brief Algorithm's arguments cleanup function.
 234  *        This function will be called just after stub exit.
 235  *        It can be used to cleanup stub memory parameters.
 236  *
 237  * @param target  Pointer to target.
 238  * @param run     Pointer to algo run data.
 239  * @param usr_arg Function specific argument. The same as for esp_algorithm_usr_func_t.
 240  *
 241  * @return ERROR_OK on success, otherwise ERROR_XXX.
 242  */
 243 typedef void (*esp_algorithm_usr_func_done_t)(struct target *target,
 244         struct esp_algorithm_run_data *run,
 245         void *usr_arg);
 246
 247 struct esp_algorithm_hw {
 248         int (*algo_init)(struct target *target, struct esp_algorithm_run_data *run, uint32_t num_args, va_list ap);
 249         int (*algo_cleanup)(struct target *target, struct esp_algorithm_run_data *run);
 250         const uint8_t *(*stub_tramp_get)(struct target *target, size_t *size);
 251 };
 252
 253 /**
 254  * Algorithm run data.
 255  */
 256 struct esp_algorithm_run_data {
 257         /** Algorithm completion timeout in ms. If 0, default value will be used */
 258         uint32_t timeout_ms;
 259         /** Algorithm stack size. */
 260         uint32_t stack_size;
 261         /** Algorithm register arguments. */
 262         struct esp_algorithm_reg_args reg_args;
 263         /** Algorithm memory arguments. */
 264         struct esp_algorithm_mem_args mem_args;
 265         /** Algorithm arch-specific info. For Xtensa this should point to struct xtensa_algorithm. */
 266         void *arch_info;
 267         /** Algorithm return code. */
 268         int32_t ret_code;
 269         /** Stub. */
 270         struct esp_algorithm_stub stub;
 271         union {
 272                 struct {
 273                         /** Size of the pre-alocated on-board buffer for stub's code. */
 274                         uint32_t code_buf_size;
 275                         /** Address of pre-compiled target buffer for stub trampoline. */
 276                         target_addr_t code_buf_addr;
 277                         /** Size of the pre-alocated on-board buffer for stub's stack. */
 278                         uint32_t min_stack_size;
 279                         /** Pre-compiled target buffer's addr for stack. */
 280                         target_addr_t min_stack_addr;
 281                 } on_board;
 282                 struct esp_algorithm_image image;
 283         };
 284         /** Host side algorithm function argument. */
 285         void *usr_func_arg;
 286         /** Host side algorithm function. */
 287         esp_algorithm_usr_func_t usr_func;
 288         /** Host side algorithm function setup routine. */
 289         esp_algorithm_usr_func_init_t usr_func_init;
 290         /** Host side algorithm function cleanup routine. */
 291         esp_algorithm_usr_func_done_t usr_func_done;
 292         /** Algorithm run function: see algorithm_run_xxx for example. */
 293         esp_algorithm_func_t algo_func;
 294         /** HW specific API */
 295         const struct esp_algorithm_hw *hw;
 296 };
 297
 298 int esp_algorithm_load_func_image(struct target *target, struct esp_algorithm_run_data *run);
 299 int esp_algorithm_unload_func_image(struct target *target, struct esp_algorithm_run_data *run);
 300
 301 int esp_algorithm_exec_func_image_va(struct target *target,
 302         struct esp_algorithm_run_data *run,
 303         uint32_t num_args,
 304         va_list ap);
 305
 306 /**
 307  * @brief Loads and runs stub from specified image.
 308  *        This function should be used to run external stub code on target.
 309  *
 310  * @param target   Pointer to target.
 311  * @param run      Pointer to algo run data.
 312  * @param num_args Number of stub arguments that follow.
 313  *
 314  * @return ERROR_OK on success, otherwise ERROR_XXX. Stub return code is in run->ret_code.
 315  */
 316 static inline int esp_algorithm_run_func_image_va(struct target *target,
 317         struct esp_algorithm_run_data *run,
 318         uint32_t num_args,
 319         va_list ap)
 320 {
 321         int ret = esp_algorithm_load_func_image(target, run);
 322         if (ret != ERROR_OK)
 323                 return ret;
 324         ret = esp_algorithm_exec_func_image_va(target, run, num_args, ap);
 325         int rc = esp_algorithm_unload_func_image(target, run);
 326         return ret != ERROR_OK ? ret : rc;
 327 }
 328
 329 static inline int esp_algorithm_run_func_image(struct target *target,
 330         struct esp_algorithm_run_data *run,
 331         uint32_t num_args,
 332         ...)
 333 {
 334         va_list ap;
 335         va_start(ap, num_args);
 336         int retval = esp_algorithm_run_func_image_va(target, run, num_args, ap);
 337         va_end(ap);
 338         return retval;
 339 }
 340
 341 int esp_algorithm_load_onboard_func(struct target *target,
 342         target_addr_t func_addr,
 343         struct esp_algorithm_run_data *run);
 344 int esp_algorithm_unload_onboard_func(struct target *target, struct esp_algorithm_run_data *run);
 345 int esp_algorithm_exec_onboard_func_va(struct target *target,
 346         struct esp_algorithm_run_data *run,
 347         uint32_t num_args,
 348         va_list ap);
 349
 350 /**
 351  * @brief Runs pre-compiled on-board function.
 352  *        This function should be used to run on-board stub code.
 353  *
 354  * @param target     Pointer to target.
 355  * @param run        Pointer to algo run data.
 356  * @param func_entry Address of the function to run.
 357  * @param num_args   Number of function arguments that follow.
 358  *
 359  * @return ERROR_OK on success, otherwise ERROR_XXX. Stub return code is in run->ret_code.
 360  */
 361 static inline int esp_algorithm_run_onboard_func_va(struct target *target,
 362         struct esp_algorithm_run_data *run,
 363         target_addr_t func_addr,
 364         uint32_t num_args,
 365         va_list ap)
 366 {
 367         int ret = esp_algorithm_load_onboard_func(target, func_addr, run);
 368         if (ret != ERROR_OK)
 369                 return ret;
 370         ret = esp_algorithm_exec_onboard_func_va(target, run, num_args, ap);
 371         if (ret != ERROR_OK)
 372                 return ret;
 373         return esp_algorithm_unload_onboard_func(target, run);
 374 }
 375
 376 static inline int esp_algorithm_run_onboard_func(struct target *target,
 377         struct esp_algorithm_run_data *run,
 378         target_addr_t func_addr,
 379         uint32_t num_args,
 380         ...)
 381 {
 382         va_list ap;
 383         va_start(ap, num_args);
 384         int retval = esp_algorithm_run_onboard_func_va(target, run, func_addr, num_args, ap);
 385         va_end(ap);
 386         return retval;
 387 }
 388
 389 /**
 390  * @brief Set the value of an argument passed via registers to the stub main function.
 391  */
 392 static inline void esp_algorithm_user_arg_set_uint(struct esp_algorithm_run_data *run,
 393         int arg_num,
 394         uint64_t val)
 395 {
 396         struct reg_param *param = &run->reg_args.params[run->reg_args.first_user_param + arg_num];
 397
 398         assert(param->size <= 64);
 399
 400         if (param->size <= 32)
 401                 buf_set_u32(param->value, 0, param->size, val);
 402         else
 403                 buf_set_u64(param->value, 0, param->size, val);
 404 }
 405
 406 /**
 407  * @brief Get the value of an argument passed via registers from the stub main function.
 408  */
 409 static inline uint64_t esp_algorithm_user_arg_get_uint(struct esp_algorithm_run_data *run, int arg_num)
 410 {
 411         struct reg_param *param = &run->reg_args.params[run->reg_args.first_user_param + arg_num];
 412
 413         assert(param->size <= 64);
 414
 415         if (param->size <= 32)
 416                 return buf_get_u32(param->value, 0, param->size);
 417         return buf_get_u64(param->value, 0, param->size);
 418 }
 419
 420 #endif  /* OPENOCD_TARGET_ESP_ALGORITHM_H */