esp_algorithm.h

Go to the documentation of this file.

/* 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>
 
struct esp_algorithm_image {
    struct image image;
    uint32_t bss_size;
    uint32_t iram_org;
    uint32_t iram_len;
    uint32_t dram_org;
    uint32_t dram_len;
    bool reverse;
};
 
#define ESP_IMAGE_ELF_PHF_EXEC          0x1
 
struct esp_algorithm_stub {
    target_addr_t entry;
    struct working_area *code;
    struct working_area *data;
    struct working_area *tramp;
    struct working_area *padding;
    target_addr_t tramp_addr;
    target_addr_t tramp_mapped_addr;
    struct working_area *stack;
    target_addr_t stack_addr;
    target_addr_t log_buff_addr;
    uint32_t log_buff_size;
    void *ainfo;
};
 
struct esp_algorithm_mem_args {
    struct mem_param *params;
    uint32_t count;
};
 
struct esp_algorithm_reg_args {
    struct reg_param *params;
    uint32_t count;
    uint32_t first_user_param;
};
 
struct esp_algorithm_run_data;
 
typedef int (*esp_algorithm_func_t)(struct target *target, struct esp_algorithm_run_data *run, void *arg);
 
typedef int (*esp_algorithm_usr_func_t)(struct target *target, void *usr_arg);
 
typedef int (*esp_algorithm_usr_func_init_t)(struct target *target,
    struct esp_algorithm_run_data *run,
    void *usr_arg);
 
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);
};
 
struct esp_algorithm_run_data {
    uint32_t timeout_ms;
    uint32_t stack_size;
    struct esp_algorithm_reg_args reg_args;
    struct esp_algorithm_mem_args mem_args;
    void *arch_info;
    int32_t ret_code;
    struct esp_algorithm_stub stub;
    union {
        struct {
            uint32_t code_buf_size;
            target_addr_t code_buf_addr;
            uint32_t min_stack_size;
            target_addr_t min_stack_addr;
        } on_board;
        struct esp_algorithm_image image;
    };
    void *usr_func_arg;
    esp_algorithm_usr_func_t usr_func;
    esp_algorithm_usr_func_init_t usr_func_init;
    esp_algorithm_usr_func_done_t usr_func_done;
    esp_algorithm_func_t algo_func;
    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);
 
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);
 
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;
}
 
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);
}
 
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 */