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

173 lines
5.0 KiB
C

// Copyright 2015-2019 Espressif Systems (Shanghai) PTE LTD
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
#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;
/**** 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);