xref: /netbsd-src/external/gpl3/binutils.old/dist/include/sim/sim.h (revision c42dbd0ed2e61fe6eda8590caa852ccf34719964)
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