1*c42dbd0eSchristos /* This file defines the interface between the simulator and gdb. 2*c42dbd0eSchristos 3*c42dbd0eSchristos Copyright (C) 1993-2022 Free Software Foundation, Inc. 4*c42dbd0eSchristos 5*c42dbd0eSchristos This file is part of GDB. 6*c42dbd0eSchristos 7*c42dbd0eSchristos This program is free software; you can redistribute it and/or modify 8*c42dbd0eSchristos it under the terms of the GNU General Public License as published by 9*c42dbd0eSchristos the Free Software Foundation; either version 3 of the License, or 10*c42dbd0eSchristos (at your option) any later version. 11*c42dbd0eSchristos 12*c42dbd0eSchristos This program is distributed in the hope that it will be useful, 13*c42dbd0eSchristos but WITHOUT ANY WARRANTY; without even the implied warranty of 14*c42dbd0eSchristos MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15*c42dbd0eSchristos GNU General Public License for more details. 16*c42dbd0eSchristos 17*c42dbd0eSchristos You should have received a copy of the GNU General Public License 18*c42dbd0eSchristos along with this program. If not, see <http://www.gnu.org/licenses/>. */ 19*c42dbd0eSchristos 20*c42dbd0eSchristos #ifndef SIM_SIM_H 21*c42dbd0eSchristos #define SIM_SIM_H 1 22*c42dbd0eSchristos 23*c42dbd0eSchristos #ifdef __cplusplus 24*c42dbd0eSchristos extern "C" { 25*c42dbd0eSchristos #endif 26*c42dbd0eSchristos 27*c42dbd0eSchristos /* This file is used when building stand-alone simulators, so isolate this 28*c42dbd0eSchristos file from gdb. */ 29*c42dbd0eSchristos 30*c42dbd0eSchristos /* Pick up CORE_ADDR_TYPE if defined (from gdb), otherwise use same value as 31*c42dbd0eSchristos gdb does (unsigned int - from defs.h). */ 32*c42dbd0eSchristos 33*c42dbd0eSchristos #ifndef CORE_ADDR_TYPE 34*c42dbd0eSchristos typedef unsigned int SIM_ADDR; 35*c42dbd0eSchristos #else 36*c42dbd0eSchristos typedef CORE_ADDR_TYPE SIM_ADDR; 37*c42dbd0eSchristos #endif 38*c42dbd0eSchristos 39*c42dbd0eSchristos 40*c42dbd0eSchristos /* Semi-opaque type used as result of sim_open and passed back to all 41*c42dbd0eSchristos other routines. "desc" is short for "descriptor". 42*c42dbd0eSchristos It is up to each simulator to define `sim_state'. */ 43*c42dbd0eSchristos 44*c42dbd0eSchristos typedef struct sim_state *SIM_DESC; 45*c42dbd0eSchristos 46*c42dbd0eSchristos 47*c42dbd0eSchristos /* Values for `kind' arg to sim_open. */ 48*c42dbd0eSchristos 49*c42dbd0eSchristos typedef enum { 50*c42dbd0eSchristos SIM_OPEN_STANDALONE, /* simulator used standalone (run.c) */ 51*c42dbd0eSchristos SIM_OPEN_DEBUG /* simulator used by debugger (gdb) */ 52*c42dbd0eSchristos } SIM_OPEN_KIND; 53*c42dbd0eSchristos 54*c42dbd0eSchristos 55*c42dbd0eSchristos /* Return codes from various functions. */ 56*c42dbd0eSchristos 57*c42dbd0eSchristos typedef enum { 58*c42dbd0eSchristos SIM_RC_FAIL = 0, 59*c42dbd0eSchristos SIM_RC_OK = 1 60*c42dbd0eSchristos } SIM_RC; 61*c42dbd0eSchristos 62*c42dbd0eSchristos 63*c42dbd0eSchristos /* Some structs, as opaque types. */ 64*c42dbd0eSchristos 65*c42dbd0eSchristos struct bfd; 66*c42dbd0eSchristos struct host_callback_struct; 67*c42dbd0eSchristos 68*c42dbd0eSchristos 69*c42dbd0eSchristos /* Main simulator entry points. */ 70*c42dbd0eSchristos 71*c42dbd0eSchristos 72*c42dbd0eSchristos /* Create a fully initialized simulator instance. 73*c42dbd0eSchristos 74*c42dbd0eSchristos (This function is called when the simulator is selected from the 75*c42dbd0eSchristos gdb command line.) 76*c42dbd0eSchristos 77*c42dbd0eSchristos KIND specifies how the simulator shall be used. Currently there 78*c42dbd0eSchristos are only two kinds: stand-alone and debug. 79*c42dbd0eSchristos 80*c42dbd0eSchristos CALLBACK specifies a standard host callback (defined in callback.h). 81*c42dbd0eSchristos 82*c42dbd0eSchristos ABFD, when non NULL, designates a target program. The program is 83*c42dbd0eSchristos not loaded. 84*c42dbd0eSchristos 85*c42dbd0eSchristos ARGV is a standard ARGV pointer such as that passed from the 86*c42dbd0eSchristos command line. The syntax of the argument list is is assumed to be 87*c42dbd0eSchristos ``SIM-PROG { SIM-OPTION } [ TARGET-PROGRAM { TARGET-OPTION } ]''. 88*c42dbd0eSchristos The trailing TARGET-PROGRAM and args are only valid for a 89*c42dbd0eSchristos stand-alone simulator. 90*c42dbd0eSchristos 91*c42dbd0eSchristos On success, the result is a non NULL descriptor that shall be 92*c42dbd0eSchristos passed to the other sim_foo functions. While the simulator 93*c42dbd0eSchristos configuration can be parameterized by (in decreasing precedence) 94*c42dbd0eSchristos ARGV's SIM-OPTION, ARGV's TARGET-PROGRAM and the ABFD argument, the 95*c42dbd0eSchristos successful creation of the simulator shall not dependent on the 96*c42dbd0eSchristos presence of any of these arguments/options. 97*c42dbd0eSchristos 98*c42dbd0eSchristos Hardware simulator: The created simulator shall be sufficiently 99*c42dbd0eSchristos initialized to handle, with out restrictions any client requests 100*c42dbd0eSchristos (including memory reads/writes, register fetch/stores and a 101*c42dbd0eSchristos resume). 102*c42dbd0eSchristos 103*c42dbd0eSchristos Process simulator: that process is not created until a call to 104*c42dbd0eSchristos sim_create_inferior. FIXME: What should the state of the simulator 105*c42dbd0eSchristos be? */ 106*c42dbd0eSchristos 107*c42dbd0eSchristos SIM_DESC sim_open (SIM_OPEN_KIND kind, struct host_callback_struct *callback, 108*c42dbd0eSchristos struct bfd *abfd, char * const *argv); 109*c42dbd0eSchristos 110*c42dbd0eSchristos 111*c42dbd0eSchristos /* Destory a simulator instance. 112*c42dbd0eSchristos 113*c42dbd0eSchristos QUITTING is non-zero if we cannot hang on errors. 114*c42dbd0eSchristos 115*c42dbd0eSchristos This may involve freeing target memory and closing any open files 116*c42dbd0eSchristos and mmap'd areas. You cannot assume sim_kill has already been 117*c42dbd0eSchristos called. */ 118*c42dbd0eSchristos 119*c42dbd0eSchristos void sim_close (SIM_DESC sd, int quitting); 120*c42dbd0eSchristos 121*c42dbd0eSchristos 122*c42dbd0eSchristos /* Load program PROG into the simulators memory. 123*c42dbd0eSchristos 124*c42dbd0eSchristos If ABFD is non-NULL, the bfd for the file has already been opened. 125*c42dbd0eSchristos The result is a return code indicating success. 126*c42dbd0eSchristos 127*c42dbd0eSchristos Hardware simulator: Normally, each program section is written into 128*c42dbd0eSchristos memory according to that sections LMA using physical (direct) 129*c42dbd0eSchristos addressing. The exception being systems, such as PPC/CHRP, which 130*c42dbd0eSchristos support more complicated program loaders. A call to this function 131*c42dbd0eSchristos should not effect the state of the processor registers. Multiple 132*c42dbd0eSchristos calls to this function are permitted and have an accumulative 133*c42dbd0eSchristos effect. 134*c42dbd0eSchristos 135*c42dbd0eSchristos Process simulator: Calls to this function may be ignored. 136*c42dbd0eSchristos 137*c42dbd0eSchristos FIXME: Most hardware simulators load the image at the VMA using 138*c42dbd0eSchristos virtual addressing. 139*c42dbd0eSchristos 140*c42dbd0eSchristos FIXME: For some hardware targets, before a loaded program can be 141*c42dbd0eSchristos executed, it requires the manipulation of VM registers and tables. 142*c42dbd0eSchristos Such manipulation should probably (?) occure in 143*c42dbd0eSchristos sim_create_inferior. */ 144*c42dbd0eSchristos 145*c42dbd0eSchristos SIM_RC sim_load (SIM_DESC sd, const char *prog, struct bfd *abfd, int from_tty); 146*c42dbd0eSchristos 147*c42dbd0eSchristos 148*c42dbd0eSchristos /* Prepare to run the simulated program. 149*c42dbd0eSchristos 150*c42dbd0eSchristos ABFD, if not NULL, provides initial processor state information. 151*c42dbd0eSchristos ARGV and ENV, if non NULL, are NULL terminated lists of pointers. 152*c42dbd0eSchristos 153*c42dbd0eSchristos Hardware simulator: This function shall initialize the processor 154*c42dbd0eSchristos registers to a known value. The program counter and possibly stack 155*c42dbd0eSchristos pointer shall be set using information obtained from ABFD (or 156*c42dbd0eSchristos hardware reset defaults). ARGV and ENV, dependant on the target 157*c42dbd0eSchristos ABI, may be written to memory. 158*c42dbd0eSchristos 159*c42dbd0eSchristos Process simulator: After a call to this function, a new process 160*c42dbd0eSchristos instance shall exist. The TEXT, DATA, BSS and stack regions shall 161*c42dbd0eSchristos all be initialized, ARGV and ENV shall be written to process 162*c42dbd0eSchristos address space (according to the applicable ABI) and the program 163*c42dbd0eSchristos counter and stack pointer set accordingly. */ 164*c42dbd0eSchristos 165*c42dbd0eSchristos SIM_RC sim_create_inferior (SIM_DESC sd, struct bfd *abfd, 166*c42dbd0eSchristos char * const *argv, char * const *env); 167*c42dbd0eSchristos 168*c42dbd0eSchristos 169*c42dbd0eSchristos /* Fetch LENGTH bytes of the simulated program's memory. Start fetch 170*c42dbd0eSchristos at virtual address MEM and store in BUF. Result is number of bytes 171*c42dbd0eSchristos read, or zero if error. */ 172*c42dbd0eSchristos 173*c42dbd0eSchristos int sim_read (SIM_DESC sd, SIM_ADDR mem, unsigned char *buf, int length); 174*c42dbd0eSchristos 175*c42dbd0eSchristos 176*c42dbd0eSchristos /* Store LENGTH bytes from BUF into the simulated program's 177*c42dbd0eSchristos memory. Store bytes starting at virtual address MEM. Result is 178*c42dbd0eSchristos number of bytes write, or zero if error. */ 179*c42dbd0eSchristos 180*c42dbd0eSchristos int sim_write (SIM_DESC sd, SIM_ADDR mem, const unsigned char *buf, int length); 181*c42dbd0eSchristos 182*c42dbd0eSchristos 183*c42dbd0eSchristos /* Fetch register REGNO storing its raw (target endian) value in the 184*c42dbd0eSchristos LENGTH byte buffer BUF. Return the actual size of the register or 185*c42dbd0eSchristos zero if REGNO is not applicable. 186*c42dbd0eSchristos 187*c42dbd0eSchristos Legacy implementations ignore LENGTH and always return -1. 188*c42dbd0eSchristos 189*c42dbd0eSchristos If LENGTH does not match the size of REGNO no data is transfered 190*c42dbd0eSchristos (the actual register size is still returned). */ 191*c42dbd0eSchristos 192*c42dbd0eSchristos int sim_fetch_register (SIM_DESC sd, int regno, unsigned char *buf, int length); 193*c42dbd0eSchristos 194*c42dbd0eSchristos 195*c42dbd0eSchristos /* Store register REGNO from the raw (target endian) value in BUF. 196*c42dbd0eSchristos 197*c42dbd0eSchristos Return the actual size of the register, any size not equal to 198*c42dbd0eSchristos LENGTH indicates the register was not updated correctly. 199*c42dbd0eSchristos 200*c42dbd0eSchristos Return a LENGTH of -1 to indicate the register was not updated 201*c42dbd0eSchristos and an error has occurred. 202*c42dbd0eSchristos 203*c42dbd0eSchristos Return a LENGTH of 0 to indicate the register was not updated 204*c42dbd0eSchristos but no error has occurred. */ 205*c42dbd0eSchristos 206*c42dbd0eSchristos int sim_store_register (SIM_DESC sd, int regno, unsigned char *buf, int length); 207*c42dbd0eSchristos 208*c42dbd0eSchristos 209*c42dbd0eSchristos /* Print whatever statistics the simulator has collected. 210*c42dbd0eSchristos 211*c42dbd0eSchristos VERBOSE is currently unused and must always be zero. */ 212*c42dbd0eSchristos 213*c42dbd0eSchristos void sim_info (SIM_DESC sd, int verbose); 214*c42dbd0eSchristos 215*c42dbd0eSchristos 216*c42dbd0eSchristos /* Return a memory map in XML format. 217*c42dbd0eSchristos 218*c42dbd0eSchristos The caller must free the returned string. 219*c42dbd0eSchristos 220*c42dbd0eSchristos For details on the format, see GDB's Memory Map Format documentation. */ 221*c42dbd0eSchristos 222*c42dbd0eSchristos char *sim_memory_map (SIM_DESC sd); 223*c42dbd0eSchristos 224*c42dbd0eSchristos 225*c42dbd0eSchristos /* Run (or resume) the simulated program. 226*c42dbd0eSchristos 227*c42dbd0eSchristos STEP, when non-zero indicates that only a single simulator cycle 228*c42dbd0eSchristos should be emulated. 229*c42dbd0eSchristos 230*c42dbd0eSchristos SIGGNAL, if non-zero is a (HOST) SIGRC value indicating the type of 231*c42dbd0eSchristos event (hardware interrupt, signal) to be delivered to the simulated 232*c42dbd0eSchristos program. 233*c42dbd0eSchristos 234*c42dbd0eSchristos Hardware simulator: If the SIGRC value returned by 235*c42dbd0eSchristos sim_stop_reason() is passed back to the simulator via SIGGNAL then 236*c42dbd0eSchristos the hardware simulator shall correctly deliver the hardware event 237*c42dbd0eSchristos indicated by that signal. If a value of zero is passed in then the 238*c42dbd0eSchristos simulation will continue as if there were no outstanding signal. 239*c42dbd0eSchristos The effect of any other SIGGNAL value is is implementation 240*c42dbd0eSchristos dependant. 241*c42dbd0eSchristos 242*c42dbd0eSchristos Process simulator: If SIGRC is non-zero then the corresponding 243*c42dbd0eSchristos signal is delivered to the simulated program and execution is then 244*c42dbd0eSchristos continued. A zero SIGRC value indicates that the program should 245*c42dbd0eSchristos continue as normal. */ 246*c42dbd0eSchristos 247*c42dbd0eSchristos void sim_resume (SIM_DESC sd, int step, int siggnal); 248*c42dbd0eSchristos 249*c42dbd0eSchristos 250*c42dbd0eSchristos /* Asynchronous request to stop the simulation. 251*c42dbd0eSchristos A nonzero return indicates that the simulator is able to handle 252*c42dbd0eSchristos the request */ 253*c42dbd0eSchristos 254*c42dbd0eSchristos int sim_stop (SIM_DESC sd); 255*c42dbd0eSchristos 256*c42dbd0eSchristos 257*c42dbd0eSchristos /* Fetch the REASON why the program stopped. 258*c42dbd0eSchristos 259*c42dbd0eSchristos SIM_EXITED: The program has terminated. SIGRC indicates the target 260*c42dbd0eSchristos dependant exit status. 261*c42dbd0eSchristos 262*c42dbd0eSchristos SIM_STOPPED: The program has stopped. SIGRC uses the host's signal 263*c42dbd0eSchristos numbering as a way of identifying the reaon: program interrupted by 264*c42dbd0eSchristos user via a sim_stop request (SIGINT); a breakpoint instruction 265*c42dbd0eSchristos (SIGTRAP); a completed single step (SIGTRAP); an internal error 266*c42dbd0eSchristos condition (SIGABRT); an illegal instruction (SIGILL); Access to an 267*c42dbd0eSchristos undefined memory region (SIGSEGV); Mis-aligned memory access 268*c42dbd0eSchristos (SIGBUS). For some signals information in addition to the signal 269*c42dbd0eSchristos number may be retained by the simulator (e.g. offending address), 270*c42dbd0eSchristos that information is not directly accessable via this interface. 271*c42dbd0eSchristos 272*c42dbd0eSchristos SIM_SIGNALLED: The program has been terminated by a signal. The 273*c42dbd0eSchristos simulator has encountered target code that causes the program 274*c42dbd0eSchristos to exit with signal SIGRC. 275*c42dbd0eSchristos 276*c42dbd0eSchristos SIM_RUNNING, SIM_POLLING: The return of one of these values 277*c42dbd0eSchristos indicates a problem internal to the simulator. */ 278*c42dbd0eSchristos 279*c42dbd0eSchristos enum sim_stop { sim_running, sim_polling, sim_exited, sim_stopped, sim_signalled }; 280*c42dbd0eSchristos 281*c42dbd0eSchristos void sim_stop_reason (SIM_DESC sd, enum sim_stop *reason, int *sigrc); 282*c42dbd0eSchristos 283*c42dbd0eSchristos 284*c42dbd0eSchristos /* Passthru for other commands that the simulator might support. 285*c42dbd0eSchristos Simulators should be prepared to deal with any combination of NULL 286*c42dbd0eSchristos or empty CMD. */ 287*c42dbd0eSchristos 288*c42dbd0eSchristos void sim_do_command (SIM_DESC sd, const char *cmd); 289*c42dbd0eSchristos 290*c42dbd0eSchristos /* Complete a command based on the available sim commands. Returns an 291*c42dbd0eSchristos array of possible matches. */ 292*c42dbd0eSchristos 293*c42dbd0eSchristos char **sim_complete_command (SIM_DESC sd, const char *text, const char *word); 294*c42dbd0eSchristos 295*c42dbd0eSchristos #ifdef __cplusplus 296*c42dbd0eSchristos } 297*c42dbd0eSchristos #endif 298*c42dbd0eSchristos 299*c42dbd0eSchristos #endif /* !defined (SIM_SIM_H) */ 300