1 /* This file defines the interface between the simulator and gdb.
2 Copyright (C) 1993, 1994, 1996, 1997 Free Software Foundation, Inc.
4 This file is part of GDB.
6 This program is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 2 of the License, or
9 (at your option) any later version.
11 This program is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 GNU General Public License for more details.
16 You should have received a copy of the GNU General Public License
17 along with this program; if not, write to the Free Software
18 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */
20 #if !defined (REMOTE_SIM_H)
21 #define REMOTE_SIM_H 1
23 /* This file is used when building stand-alone simulators, so isolate this
26 /* Pick up CORE_ADDR_TYPE if defined (from gdb), otherwise use same value as
27 gdb does (unsigned int - from defs.h). */
29 #ifndef CORE_ADDR_TYPE
30 typedef unsigned int SIM_ADDR
;
32 typedef CORE_ADDR_TYPE SIM_ADDR
;
36 /* Semi-opaque type used as result of sim_open and passed back to all
37 other routines. "desc" is short for "descriptor".
38 It is up to each simulator to define `sim_state'. */
40 typedef struct sim_state
*SIM_DESC
;
43 /* Values for `kind' arg to sim_open. */
46 SIM_OPEN_STANDALONE
, /* simulator used standalone (run.c) */
47 SIM_OPEN_DEBUG
/* simulator used by debugger (gdb) */
51 /* Return codes from various functions. */
59 /* The bfd struct, as an opaque type. */
64 /* Main simulator entry points. */
67 /* Create a fully initialized simulator instance.
69 (This function is called when the simulator is selected from the
72 KIND specifies how the simulator will be used. Currently there are only
73 two kinds: stand-alone and debug.
75 CALLBACK specifies a standard host callback (defined in callback.h).
77 ABFD, when non NULL, designates a target program. The program is
80 ARGV is a standard ARGV pointer such as that passed from the
81 command line. The syntax of the argument list is is assumed to be
82 ``SIM-PROG { SIM-OPTION } [ TARGET-PROGRAM { TARGET-OPTION } ]''.
84 On success, the result is a non NULL descriptor that shall be
85 passed to the other sim_foo functions. While the simulator
86 configuration can be parameterized by (in decreasing precedence)
87 ARGV's SIM-OPTION, ARGV's TARGET-PROGRAM and the ABFD argument, the
88 successful creation of the simulator shall not dependent on the
89 presence of any of these arguments/options.
91 For a simulator modeling real hardware, the created simulator shall
92 be sufficiently initialized to handle, with out restrictions any
93 client requests (including memory reads/writes, register
94 fetch/stores and a resume).
96 For a simulator modeling a process, that process is not created
97 until a call to sim_create_inferior. FIXME: What should the state
98 of the simulator be? */
100 SIM_DESC sim_open
PARAMS ((SIM_OPEN_KIND kind
, struct host_callback_struct
*callback
, struct _bfd
*abfd
, char **argv
));
103 /* Destory a simulator instance.
105 QUITTING is non-zero if we cannot hang on errors.
107 This may involve freeing target memory and closing any open files
108 and mmap'd areas. You cannot assume sim_kill has already been
111 void sim_close
PARAMS ((SIM_DESC sd
, int quitting
));
114 /* Load program PROG into the simulators memory.
116 If ABFD is non-NULL, the bfd for the file has already been opened.
117 The result is a return code indicating success.
119 For a simulator modeling real hardware, the client is permitted to
120 make multiple calls to this function. Such calls have an
123 For a simulator modeling a process, calls to this function may be
126 SIM_RC sim_load
PARAMS ((SIM_DESC sd
, char *prog
, struct _bfd
*abfd
, int from_tty
));
129 /* Prepare to run the simulated program.
131 ARGV and ENV are NULL terminated lists of pointers.
133 For a simulator modeling real hardware, this function shall
134 initialize the processor registers to a known value. The program
135 counter shall be set to the start address obtained from the last
136 program loaded (or the hardware reset default). The ARGV and ENV
137 arguments can be ignored.
139 For a simulator modeling a process, after a call to this function a
140 new process instance shall exist - the TEXT, DATA, BSS and stack
141 regions shall all be initialized, ARGV and ENV shall be written to
142 process address space (according to the applicable ABI), and the
143 program counter and stack pointer set accordingly. (NB: A simulator
144 may in fact initialize the TEXT, DATA and BSS sections during an
149 FIXME: Is the below a better definition - assuming that ABFD arg is
152 Prepare to run the simulated program.
154 ABFD, if not NULL, can be used to obtain initial processor state
155 information (eg PC value).
156 ARGV and ENV, if non NULL, are NULL terminated lists of pointers.
158 For a simulator modeling real hardware, this function shall
159 initialize the processor registers to a known value. The program
160 counter shall be set to the start address obtained from the ABFD
161 struct (or the hardware reset default). The ARGV and ENV arguments
164 For a simulator modeling a process, after a call to this function a
165 new process instance shall exist - the TEXT, DATA, BSS and stack
166 regions shall all be initialized, ARGV and ENV shall be written to
167 process address space (according to the applicable ABI), and the
168 program counter and stack pointer set accordingly. */
170 SIM_RC sim_create_inferior
PARAMS ((SIM_DESC sd
, char **argv
, char **env
));
173 /* Read LENGTH bytes of the simulated program's memory and store in
174 BUF. Result is number of bytes read, or zero if error. */
176 int sim_read
PARAMS ((SIM_DESC sd
, SIM_ADDR mem
, unsigned char *buf
, int length
));
179 /* Store LENGTH bytes from BUF in the simulated program's memory.
180 Result is number of bytes write, or zero if error. */
182 int sim_write
PARAMS ((SIM_DESC sd
, SIM_ADDR mem
, unsigned char *buf
, int length
));
185 /* Fetch register REGNO and store the raw (target endian) value in
188 void sim_fetch_register
PARAMS ((SIM_DESC sd
, int regno
, unsigned char *buf
));
191 /* Store register REGNO from the raw (target endian) value in BUF. */
193 void sim_store_register
PARAMS ((SIM_DESC sd
, int regno
, unsigned char *buf
));
196 /* Print whatever statistics the simulator has collected.
198 VERBOSE is currently unused and must always be zero. */
200 void sim_info
PARAMS ((SIM_DESC sd
, int verbose
));
203 /* Run (or resume) the simulated program. */
205 void sim_resume
PARAMS ((SIM_DESC sd
, int step
, int siggnal
));
208 /* Asynchronous request to stop the simulation.
209 A nonzero return indicates that the simulator is able to handle
212 int sim_stop
PARAMS ((SIM_DESC sd
));
215 /* Fetch the REASON why the program stopped.
217 SIM_EXITED: The program has terminated. SIGRC indicates the target
218 dependant exit status.
220 SIM_STOPPED: The program has stopped. SIGRC indicates the reason:
221 program interrupted by user via a sim_stop request (SIGINT); a
222 breakpoint instruction (SIGTRAP); a completed step (SIGTRAP); an
223 internal error condition (SIGABRT).
225 SIM_SIGNALLED: The simulator encountered target code that requires
226 the signal SIGRC to be delivered to the simulated program.
228 SIM_RUNNING, SIM_POLLING: The return of one of these values
229 indicates a problem internal to the simulator. */
231 enum sim_stop
{ sim_running
, sim_polling
, sim_exited
, sim_stopped
, sim_signalled
};
233 void sim_stop_reason
PARAMS ((SIM_DESC sd
, enum sim_stop
*reason
, int *sigrc
));
236 /* Passthru for other commands that the simulator might support.
237 Simulators should be prepared to deal with any combination of NULL
240 void sim_do_command
PARAMS ((SIM_DESC sd
, char *cmd
));
243 /* Provide simulator with a default (global) host_callback_struct.
244 THIS PROCEDURE IS DEPRECIATED.
245 GDB and NRUN do not use this interface.
246 This procedure does not take a SIM_DESC argument as it is
247 used before sim_open. */
249 void sim_set_callbacks
PARAMS ((struct host_callback_struct
*));
252 /* Set the size of the simulator memory array.
253 THIS PROCEDURE IS DEPRECIATED.
254 GDB and NRUN do not use this interface.
255 This procedure does not take a SIM_DESC argument as it is
256 used before sim_open. */
258 void sim_size
PARAMS ((int i
));
261 /* Run a simulation with tracing enabled.
262 THIS PROCEDURE IS DEPRECIATED.
263 GDB and NRUN do not use this interface.
264 This procedure does not take a SIM_DESC argument as it is
265 used before sim_open. */
267 int sim_trace
PARAMS ((SIM_DESC sd
));
270 /* Configure the size of the profile buffer.
271 THIS PROCEDURE IS DEPRECIATED.
272 GDB and NRUN do not use this interface.
273 This procedure does not take a SIM_DESC argument as it is
274 used before sim_open. */
276 void sim_set_profile_size
PARAMS ((int n
));
279 /* Kill the running program.
280 THIS PROCEDURE IS DEPRECIATED.
281 GDB and NRUN do not use this interface.
282 This procedure will be replaced as part of the introduction of
283 multi-cpu simulators. */
285 void sim_kill
PARAMS ((SIM_DESC sd
));
287 #endif /* !defined (REMOTE_SIM_H) */