esp-idf/components/esp_gdbstub/private_include/esp_gdbstub_common.h

/*
 * SPDX-FileCopyrightText: 2020-2022 Espressif Systems (Shanghai) CO LTD
 *
 * SPDX-License-Identifier: Apache-2.0
 */

#pragma once

#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>

#include "gdbstub_target_config.h"
#include "esp_gdbstub_arch.h"
#include "sdkconfig.h"

#ifdef CONFIG_ESP_GDBSTUB_SUPPORT_TASKS
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "freertos/task_snapshot.h"
#endif // CONFIG_ESP_GDBSTUB_SUPPORT_TASKS

/* Internal error codes used by the routines that parse the incoming gdb packet */
#define GDBSTUB_ST_ENDPACKET -1
#define GDBSTUB_ST_ERR -2
#define GDBSTUB_ST_OK -3
#define GDBSTUB_ST_CONT -4

/* Special task index values */
#define GDBSTUB_CUR_TASK_INDEX_UNKNOWN -1

/* Cab be set to a lower value in gdbstub_target_config.h */
#ifndef GDBSTUB_CMD_BUFLEN
#define GDBSTUB_CMD_BUFLEN 512
#endif

#if CONFIG_ESP_GDBSTUB_SUPPORT_TASKS
typedef enum {
    GDBSTUB_NOT_STARTED,
    GDBSTUB_STARTED,
    GDBSTUB_TASK_SUPPORT_DISABLED
} esp_gdbstub_state_t;

#define GDBSTUB_TASKS_NUM  CONFIG_ESP_GDBSTUB_MAX_TASKS

#endif // CONFIG_ESP_GDBSTUB_SUPPORT_TASKS

/* gdbstub temporary run-time data, stored in .bss to reduce stack usage */
typedef struct {
    esp_gdbstub_gdb_regfile_t regfile;
    int signal;
#if CONFIG_ESP_GDBSTUB_SUPPORT_TASKS
    esp_gdbstub_state_t state;
    int task_count;
    int paniced_task_index;
    int current_task_index;
    int thread_info_index;                             //!< index of the last task passed to qsThreadInfo
    esp_gdbstub_frame_t paniced_frame;
    TaskSnapshot_t tasks[GDBSTUB_TASKS_NUM];           // TODO: add an API to get snapshots one by one
#endif // CONFIG_ESP_GDBSTUB_SUPPORT_TASKS
} esp_gdbstub_scratch_t;

extern esp_gdbstub_scratch_t s_scratch;
/**** Functions provided by the architecture specific part ****/

/**
 * @param frame exception frame pointer
 * @return the appropriate "signal" number for the given exception cause
 */
int esp_gdbstub_get_signal(const esp_gdbstub_frame_t *frame);

/**
 * Write registers from the exception frame to the GDB register file
 * @param frame  exception frame to parse
 * @param dst  pointer to the GDB register file
 */
void esp_gdbstub_frame_to_regfile(const esp_gdbstub_frame_t *frame, esp_gdbstub_gdb_regfile_t *dst);

#if CONFIG_ESP_GDBSTUB_SUPPORT_TASKS
/**
 * Write registers from the saved frame of a given task to the GDB register file
 * @param tcb  pointer to the TCB of the task
 * @param dst  pointer to the GDB register file
 */
void esp_gdbstub_tcb_to_regfile(TaskHandle_t tcb, esp_gdbstub_gdb_regfile_t *dst);
#endif // CONFIG_ESP_GDBSTUB_SUPPORT_TASKS



/**** Functions provided by the target specific part ****/

/**
 * Do target-specific initialization before gdbstub can start communicating.
 * This may involve, for example, configuring the UART.
 */
void esp_gdbstub_target_init(void);

/**
 * Receive a byte from the GDB client. Blocks until a byte is available.
 * @return received byte
 */
int esp_gdbstub_getchar(void);

/**
 * Send a byte to the GDB client
 * @param c  byte to send
 */
void esp_gdbstub_putchar(int c);

/**
 * Read a byte from target memory
 * @param ptr  address
 * @return  byte value, or GDBSTUB_ST_ERR if the address is not readable
 */
int esp_gdbstub_readmem(intptr_t addr);

/**
 * Make sure all bytes sent using putchar() end up at the host.
 * (Usually stubbed for UART, but can be useful for other channels)
 */
void esp_gdbstub_flush(void);

/**
 * Write a byte to target memory
 * @param addr  address
 * @param data  data byte
 * @return 0 in case of success, -1 in case of error
 */
int esp_gdbstub_writemem(unsigned int addr, unsigned char data);

/**
 * Read a data from fifo and detect start symbol
 * @return  1 if break symbol was detected, or 0 if not
 */
int esp_gdbstub_getfifo(void);

/**** GDB packet related functions ****/

/** Begin a packet */
void esp_gdbstub_send_start(void);

/** Send a character as part of the packet */
void esp_gdbstub_send_char(char c);

/** Send a string as part of the packet */
void esp_gdbstub_send_str(const char *s);

/** Send a hex value as part of the packet */
void esp_gdbstub_send_hex(int val, int bits);

/** Finish sending the packet */
void esp_gdbstub_send_end(void);

/** Send a packet with a string as content */
void esp_gdbstub_send_str_packet(const char *str);

/** Get a hex value from the gdb packet */
uint32_t esp_gdbstub_gethex(const unsigned char **ptr, int bits);

/** Read, unescape, and validate the incoming GDB command */
int esp_gdbstub_read_command(unsigned char **out_cmd, size_t *out_size);

/** Handle a command received from gdb */
int esp_gdbstub_handle_command(unsigned char *cmd, int len);

void esp_gdbstub_init_dports(void);
void esp_gdbstub_stall_other_cpus_start(void);
void esp_gdbstub_stall_other_cpus_end(void);

void esp_gdbstub_clear_step(void);
void esp_gdbstub_do_step(void);
void esp_gdbstub_trigger_cpu(void);

/**
 * Write a value to register in frame
 * @param frame  gdbstub frame
 * @param reg_index  register index, depends on architecture
 * @param value  32 bit data value
 */
void esp_gdbstub_set_register(esp_gdbstub_frame_t *frame, uint32_t reg_index, uint32_t value);