/* SPDX-License-Identifier: GPL-2.0-or-later */

#ifndef OPENOCD_TARGET_RISCV_RISCV_H
#define OPENOCD_TARGET_RISCV_RISCV_H

struct riscv_program;

#include <stdint.h>
#include "opcodes.h"
#include "gdb_regs.h"
#include "jtag/jtag.h"
#include "target/semihosting_common.h"
#include "target/target.h"
#include "target/register.h"
#include <helper/command.h>
#include <helper/bits.h>

#define RISCV_COMMON_MAGIC	0x52495356U

#define RISCV_MAX_HARTS  ((int)BIT(20))
#define RISCV_MAX_TRIGGERS 32
#define RISCV_MAX_HWBPS 16
#define RISCV_MAX_DMS 100

#define DEFAULT_COMMAND_TIMEOUT_SEC 5

#define RISCV_SATP_MODE(xlen)  ((xlen) == 32 ? SATP32_MODE : SATP64_MODE)
#define RISCV_SATP_PPN(xlen)  ((xlen) == 32 ? SATP32_PPN : SATP64_PPN)
#define RISCV_HGATP_MODE(xlen)  ((xlen) == 32 ? HGATP32_MODE : HGATP64_MODE)
#define RISCV_HGATP_PPN(xlen)  ((xlen) == 32 ? HGATP32_PPN : HGATP64_PPN)
#define RISCV_PGSHIFT 12
#define RISCV_PGSIZE BIT(RISCV_PGSHIFT)
#define RISCV_PGBASE(addr) ((addr) & ~(RISCV_PGSIZE - 1))
#define RISCV_PGOFFSET(addr) ((addr) & (RISCV_PGSIZE - 1))

#define PG_MAX_LEVEL 5

#define RISCV_BATCH_ALLOC_SIZE 128

extern struct target_type riscv011_target;
extern struct target_type riscv013_target;

/*
 * Definitions shared by code supporting all RISC-V versions.
 */
typedef uint64_t riscv_reg_t;
typedef uint32_t riscv_insn_t;
typedef uint64_t riscv_addr_t;

enum yes_no_maybe {
	YNM_MAYBE,
	YNM_YES,
	YNM_NO
};

enum riscv_mem_access_method {
	RISCV_MEM_ACCESS_PROGBUF,
	RISCV_MEM_ACCESS_SYSBUS,
	RISCV_MEM_ACCESS_ABSTRACT,
	RISCV_MEM_ACCESS_MAX_METHODS_NUM
};

enum riscv_virt2phys_mode {
	RISCV_VIRT2PHYS_MODE_HW,
	RISCV_VIRT2PHYS_MODE_SW,
	RISCV_VIRT2PHYS_MODE_OFF
};

const char *riscv_virt2phys_mode_to_str(enum riscv_virt2phys_mode mode);

enum riscv_halt_reason {
	RISCV_HALT_INTERRUPT,
	RISCV_HALT_EBREAK,
	RISCV_HALT_SINGLESTEP,
	RISCV_HALT_TRIGGER,
	RISCV_HALT_UNKNOWN,
	RISCV_HALT_GROUP,
	RISCV_HALT_ERROR
};

enum riscv_isrmasking_mode {
	/* RISCV_ISRMASK_AUTO,	*/ /* not supported yet */
	RISCV_ISRMASK_OFF,
	/* RISCV_ISRMASK_ON,	*/ /* not supported yet */
	RISCV_ISRMASK_STEPONLY,
};

enum riscv_hart_state {
	RISCV_STATE_NON_EXISTENT,
	RISCV_STATE_RUNNING,
	RISCV_STATE_HALTED,
	RISCV_STATE_UNAVAILABLE
};

/* RISC-V-specific data assigned to a register. */
typedef struct {
	struct target *target;
	/* Abstract command's regno for a custom register. */
	unsigned int custom_number;
} riscv_reg_info_t;

#define RISCV_SAMPLE_BUF_TIMESTAMP_BEFORE	0x80
#define RISCV_SAMPLE_BUF_TIMESTAMP_AFTER	0x81
struct riscv_sample_buf {
	uint8_t *buf;
	unsigned int used;
	unsigned int size;
};

typedef struct {
	bool enabled;
	struct {
		bool enabled;
		target_addr_t address;
		uint32_t size_bytes;
	} bucket[16];
} riscv_sample_config_t;

typedef struct {
	struct list_head list;
	uint16_t low, high;
	char *name;
} range_list_t;

#define DTM_DTMCS_VERSION_UNKNOWN ((unsigned int)-1)
#define RISCV_TINFO_VERSION_UNKNOWN (-1)

#define RISCV013_DTMCS_ABITS_MIN 7
#define RISCV013_DTMCS_ABITS_MAX 32

struct reg_name_table {
	unsigned int num_entries;
	char **reg_names;
};

struct riscv_mem_access_args {
	target_addr_t address;

	const uint8_t *write_buffer;
	uint8_t *read_buffer;

	uint32_t size;
	uint32_t count;
	uint32_t increment;
};

static inline bool
riscv_mem_access_is_valid(const struct riscv_mem_access_args args)
{
	return !args.read_buffer != !args.write_buffer;
}

static inline bool
riscv_mem_access_is_read(const struct riscv_mem_access_args args)
{
	assert(riscv_mem_access_is_valid(args));
	return !args.write_buffer && args.read_buffer;
}

static inline bool
riscv_mem_access_is_write(const struct riscv_mem_access_args args)
{
	assert(riscv_mem_access_is_valid(args));
	return !args.read_buffer && args.write_buffer;
}


struct riscv_info {
	unsigned int common_magic;

	unsigned int dtm_version;

	struct command_context *cmd_ctx;
	void *version_specific;

	struct reg_name_table custom_register_names;
	char **reg_names;

	/* It's possible that each core has a different supported ISA set. */
	int xlen;
	/* TODO: use the value from the register cache instead. */
	riscv_reg_t misa;
	/* TODO: use the value from the register cache instead.
	 * Cached value of vlenb. 0 indicates there is no vector support.
	 * Note that you can have vector support without misa.V set, because
	 * Zve* extensions implement vector registers without setting misa.V. */
	unsigned int vlenb;

	/* The number of triggers per hart. */
	unsigned int trigger_count;

	/* Data structure to record known unsupported tdata1+tdata2 trigger CSR values.
	 * This is to avoid repetitive attempts to set trigger configurations that are already
	 * known to be unsupported in the HW.
	 * A separate data structure is created for each trigger. */
	struct list_head *wp_triggers_negative_cache;

	/* record the tinfo of each trigger */
	unsigned int trigger_tinfo[RISCV_MAX_TRIGGERS];

	/* Version of the implemented Sdtrig extension */
	int tinfo_version;

	/* Record if single-step is needed prior to resuming
	 * from a software breakpoint or trigger.
	 * Single-step is needed if the instruction that
	 * caused the halt was not retired. That is,
	 * when we halted "before" that instruction.
	 */
	bool need_single_step;

	/* For each physical trigger contains:
	 * -1: the hwbp is available
	 * -4: The trigger is used by the itrigger command
	 * -5: The trigger is used by the etrigger command
	 * >= 0: unique_id of the breakpoint/watchpoint that is using it.
	 * Note that in RTOS mode the triggers are the same across all harts the
	 * target controls, while otherwise only a single hart is controlled. */
	int64_t trigger_unique_id[RISCV_MAX_HWBPS];

	/* The unique id of the trigger that caused the most recent halt. If the
	 * most recent halt was not caused by a trigger, then this is -1. */
	int64_t trigger_hit;

	/* The configured approach to translate virtual addresses to physical */
	enum riscv_virt2phys_mode virt2phys_mode;

	bool triggers_enumerated;

	/* Decremented every scan, and when it reaches 0 we clear the learned
	 * delays, causing them to be relearned. Used for testing. */
	int reset_delays_wait;

	/* This target has been prepped and is ready to step/resume. */
	bool prepped;
	/* This target was selected using hasel. */
	bool selected;

	/* Used by riscv_openocd_poll(). */
	bool halted_needs_event_callback;
	enum target_event halted_callback_event;
	unsigned int halt_group_repoll_count;

	enum riscv_isrmasking_mode isrmask_mode;

	/* Helper functions that target the various RISC-V debug spec
	 * implementations. */
	int (*select_target)(struct target *target);
	int (*get_hart_state)(struct target *target, enum riscv_hart_state *state);
	/* Resume this target, as well as every other prepped target that can be
	 * resumed near-simultaneously. Clear the prepped flag on any target that
	 * was resumed. */
	int (*resume_go)(struct target *target);
	int (*step_current_hart)(struct target *target);

	/* These get called from riscv_poll_hart(), which is a house of cards
	 * together with openocd_poll(), so be careful not to upset things too
	 * much. */
	int (*handle_became_halted)(struct target *target,
		enum riscv_hart_state previous_riscv_state);
	int (*handle_became_running)(struct target *target,
		enum riscv_hart_state previous_riscv_state);
	int (*handle_became_unavailable)(struct target *target,
		enum riscv_hart_state previous_riscv_state);

	/* Called periodically (no guarantees about frequency), while there's
	 * nothing else going on. */
	int (*tick)(struct target *target);

	/* Get this target as ready as possible to resume, without actually
	 * resuming. */
	int (*resume_prep)(struct target *target);
	int (*halt_prep)(struct target *target);
	int (*halt_go)(struct target *target);
	int (*on_step)(struct target *target);
	enum riscv_halt_reason (*halt_reason)(struct target *target);
	int (*write_progbuf)(struct target *target, unsigned int index, riscv_insn_t d);
	riscv_insn_t (*read_progbuf)(struct target *target, unsigned int index);
	int (*execute_progbuf)(struct target *target, uint32_t *cmderr);
	int (*invalidate_cached_progbuf)(struct target *target);
	unsigned int (*get_dmi_address_bits)(const struct target *target);
	void (*fill_dmi_write)(const struct target *target, uint8_t *buf, uint32_t a, uint32_t d);
	void (*fill_dmi_read)(const struct target *target, uint8_t *buf, uint32_t a);
	void (*fill_dm_nop)(const struct target *target, uint8_t *buf);

	int (*authdata_read)(struct target *target, uint32_t *value, unsigned int index);
	int (*authdata_write)(struct target *target, uint32_t value, unsigned int index);

	int (*dmi_read)(struct target *target, uint32_t *value, uint32_t address);
	int (*dmi_write)(struct target *target, uint32_t address, uint32_t value);

	bool (*get_impebreak)(const struct target *target);
	unsigned int (*get_progbufsize)(const struct target *target);

	/* Get the DMI address of target's DM's register.
	 * The function should return the passed address
	 * if the target is not assigned a DM yet.
	 */
	uint32_t (*get_dmi_address)(const struct target *target, uint32_t dm_address);

	int (*sample_memory)(struct target *target,
						 struct riscv_sample_buf *buf,
						 riscv_sample_config_t *config,
						 int64_t until_ms);

	int (*access_memory)(struct target *target, const struct riscv_mem_access_args args);

	unsigned int (*data_bits)(struct target *target);

	COMMAND_HELPER((*print_info), struct target *target);

	/* Storage for arch_info of non-custom registers. */
	riscv_reg_info_t shared_reg_info;

	/* Storage for vector register types. */
	struct reg_data_type_vector vector_uint8;
	struct reg_data_type_vector vector_uint16;
	struct reg_data_type_vector vector_uint32;
	struct reg_data_type_vector vector_uint64;
	struct reg_data_type_vector vector_uint128;
	struct reg_data_type type_uint8_vector;
	struct reg_data_type type_uint16_vector;
	struct reg_data_type type_uint32_vector;
	struct reg_data_type type_uint64_vector;
	struct reg_data_type type_uint128_vector;
	struct reg_data_type_union_field vector_fields[5];
	struct reg_data_type_union vector_union;
	struct reg_data_type type_vector;

	bool *reserved_triggers;

	/* Memory access methods to use, ordered by priority, highest to lowest. */
	enum riscv_mem_access_method mem_access_methods[RISCV_MEM_ACCESS_MAX_METHODS_NUM];

	unsigned int num_enabled_mem_access_methods;

	/* Different memory regions may need different methods but single configuration is applied
	 * for all. Following flags are used to warn only once about failing memory access method. */
	bool mem_access_warn[RISCV_MEM_ACCESS_MAX_METHODS_NUM];

	/* In addition to the ones in the standard spec, we'll also expose additional
	 * CSRs in this list. */
	struct list_head expose_csr;
	/* Same, but for custom registers.
	 * Custom registers are for non-standard extensions and use abstract register numbers
	 * from range 0xc000 ... 0xffff. */
	struct list_head expose_custom;

	/* The list of registers to mark as "hidden". Hidden registers are available
	 * but do not appear in gdb targets description or reg command output. */
	struct list_head hide_csr;

	riscv_sample_config_t sample_config;
	struct riscv_sample_buf sample_buf;

	/* Track when we were last asked to do something substantial. */
	int64_t last_activity;

	enum yes_no_maybe vsew64_supported;

	bool range_trigger_fallback_encountered;

	bool wp_allow_equality_match_trigger;
	bool wp_allow_napot_trigger;
	bool wp_allow_ge_lt_trigger;

	bool autofence;
};

enum riscv_priv_mode {
	RISCV_MODE_M,
	RISCV_MODE_S,
	RISCV_MODE_U,
	RISCV_MODE_VS,
	RISCV_MODE_VU,
	N_RISCV_MODE
};

struct riscv_private_config {
	bool dcsr_ebreak_fields[N_RISCV_MODE];
};

static inline struct riscv_private_config
*riscv_private_config(const struct target *target)
{
	assert(target->private_config);
	return target->private_config;
}

COMMAND_HELPER(riscv_print_info_line, const char *section, const char *key,
			   unsigned int value);

typedef struct {
	uint8_t tunneled_dr_width;
	struct scan_field tunneled_dr[4];
} riscv_bscan_tunneled_scan_context_t;

typedef struct {
	const char *name;
	int level;
	unsigned int va_bits;
	/* log2(PTESIZE) */
	unsigned int pte_shift;
	unsigned int vpn_shift[PG_MAX_LEVEL];
	unsigned int vpn_mask[PG_MAX_LEVEL];
	unsigned int pte_ppn_shift[PG_MAX_LEVEL];
	unsigned int pte_ppn_mask[PG_MAX_LEVEL];
	unsigned int pa_ppn_shift[PG_MAX_LEVEL];
	unsigned int pa_ppn_mask[PG_MAX_LEVEL];
} virt2phys_info_t;

bool riscv_virt2phys_mode_is_hw(const struct target *target);
bool riscv_virt2phys_mode_is_sw(const struct target *target);

/* Wall-clock timeout for a command/access. Settable via RISC-V Target commands.*/
int riscv_get_command_timeout_sec(void);

/* Everything needs the RISC-V specific info structure, so here's a nice macro
 * that provides that. */
static inline struct riscv_info *riscv_info(const struct target *target) __attribute__((unused));
static inline struct riscv_info *riscv_info(const struct target *target)
{
	assert(target->arch_info);
	return target->arch_info;
}
#define RISCV_INFO(R) struct riscv_info *R = riscv_info(target);

static inline bool is_riscv(const struct riscv_info *riscv_info)
{
	return riscv_info->common_magic == RISCV_COMMON_MAGIC;
}

extern struct scan_field select_dtmcontrol;
extern struct scan_field select_dbus;
extern struct scan_field select_idcode;

int dtmcs_scan(struct jtag_tap *tap, uint32_t out, uint32_t *in_ptr);

extern struct scan_field *bscan_tunneled_select_dmi;
extern uint32_t bscan_tunneled_select_dmi_num_fields;
typedef enum { BSCAN_TUNNEL_NESTED_TAP, BSCAN_TUNNEL_DATA_REGISTER } bscan_tunnel_type_t;
extern uint8_t bscan_tunnel_ir_width;

void select_dmi_via_bscan(struct jtag_tap *tap);

/*** OpenOCD Interface */
int riscv_openocd_poll(struct target *target);

int riscv_halt(struct target *target);

int riscv_openocd_step(
	struct target *target,
	bool current,
	target_addr_t address,
	bool handle_breakpoints
);

/*** RISC-V Interface ***/

bool riscv_supports_extension(const struct target *target, char letter);

/* Returns XLEN for the given (or current) hart. */
unsigned int riscv_xlen(const struct target *target);

/* Returns VLENB for the given (or current) hart. */
unsigned int riscv_vlenb(const struct target *target);

/*** Support functions for the RISC-V 'RTOS', which provides multihart support
 * without requiring multiple targets.  */

/* Checks the state of the current hart -- "is_halted" checks the actual
 * on-device register. */
int riscv_get_hart_state(struct target *target, enum riscv_hart_state *state);

/* These helper functions let the generic program interface get target-specific
 * information. */
unsigned int riscv_progbuf_size(struct target *target);

riscv_insn_t riscv_read_progbuf(struct target *target, int index);
int riscv_write_progbuf(struct target *target, unsigned int index, riscv_insn_t insn);
int riscv_execute_progbuf(struct target *target, uint32_t *cmderr);

void riscv_fill_dm_nop(const struct target *target, uint8_t *buf);
void riscv_fill_dmi_write(const struct target *target, uint8_t *buf, uint32_t a, uint32_t d);
void riscv_fill_dmi_read(const struct target *target, uint8_t *buf, uint32_t a);
unsigned int riscv_get_dmi_address_bits(const struct target *target);

uint32_t riscv_get_dmi_address(const struct target *target, uint32_t dm_address);

int riscv_enumerate_triggers(struct target *target);

int riscv_add_watchpoint(struct target *target, struct watchpoint *watchpoint);
int riscv_remove_watchpoint(struct target *target,
		struct watchpoint *watchpoint);

void riscv_semihosting_init(struct target *target);

enum semihosting_result riscv_semihosting(struct target *target, int *retval);

void riscv_add_bscan_tunneled_scan(struct jtag_tap *tap, const struct scan_field *field,
		riscv_bscan_tunneled_scan_context_t *ctxt);

int riscv_read_by_any_size(struct target *target, target_addr_t address, uint32_t size, uint8_t *buffer);
int riscv_write_by_any_size(struct target *target, target_addr_t address, uint32_t size, uint8_t *buffer);

#endif /* OPENOCD_TARGET_RISCV_RISCV_H */