Back to index

cell-binutils  2.17cvs20070401
remote-sim.h
Go to the documentation of this file.
00001 /* This file defines the interface between the simulator and gdb.
00002 
00003    Copyright 1993, 1994, 1996, 1997, 1998, 2000, 2002, 2007
00004    Free Software Foundation, Inc.
00005 
00006 This file is part of GDB.
00007 
00008 This program is free software; you can redistribute it and/or modify
00009 it under the terms of the GNU General Public License as published by
00010 the Free Software Foundation; either version 2 of the License, or
00011 (at your option) any later version.
00012 
00013 This program is distributed in the hope that it will be useful,
00014 but WITHOUT ANY WARRANTY; without even the implied warranty of
00015 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00016 GNU General Public License for more details.
00017 
00018 You should have received a copy of the GNU General Public License
00019 along with this program; if not, write to the Free Software
00020 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.  */
00021 
00022 #if !defined (REMOTE_SIM_H)
00023 #define REMOTE_SIM_H 1
00024 
00025 #ifdef __cplusplus
00026 extern "C" {
00027 #endif
00028 
00029 /* This file is used when building stand-alone simulators, so isolate this
00030    file from gdb.  */
00031 
00032 /* Pick up CORE_ADDR_TYPE if defined (from gdb), otherwise use same value as
00033    gdb does (unsigned int - from defs.h).  */
00034 
00035 #ifndef CORE_ADDR_TYPE
00036 typedef unsigned int SIM_ADDR;
00037 #else
00038 typedef CORE_ADDR_TYPE SIM_ADDR;
00039 #endif
00040 
00041 
00042 /* Semi-opaque type used as result of sim_open and passed back to all
00043    other routines.  "desc" is short for "descriptor".
00044    It is up to each simulator to define `sim_state'.  */
00045 
00046 typedef struct sim_state *SIM_DESC;
00047 
00048 
00049 /* Values for `kind' arg to sim_open.  */
00050 
00051 typedef enum {
00052   SIM_OPEN_STANDALONE, /* simulator used standalone (run.c) */
00053   SIM_OPEN_DEBUG       /* simulator used by debugger (gdb) */
00054 } SIM_OPEN_KIND;
00055 
00056 
00057 /* Return codes from various functions.  */
00058 
00059 typedef enum {
00060   SIM_RC_FAIL = 0,
00061   SIM_RC_OK = 1
00062 } SIM_RC;
00063 
00064 
00065 /* The bfd struct, as an opaque type.  */
00066 
00067 struct bfd;
00068 
00069 
00070 /* Main simulator entry points.  */
00071 
00072 
00073 /* Create a fully initialized simulator instance.
00074 
00075    (This function is called when the simulator is selected from the
00076    gdb command line.)
00077 
00078    KIND specifies how the simulator shall be used.  Currently there
00079    are only two kinds: stand-alone and debug.
00080 
00081    CALLBACK specifies a standard host callback (defined in callback.h).
00082 
00083    ABFD, when non NULL, designates a target program.  The program is
00084    not loaded.
00085 
00086    ARGV is a standard ARGV pointer such as that passed from the
00087    command line.  The syntax of the argument list is is assumed to be
00088    ``SIM-PROG { SIM-OPTION } [ TARGET-PROGRAM { TARGET-OPTION } ]''.
00089    The trailing TARGET-PROGRAM and args are only valid for a
00090    stand-alone simulator.
00091 
00092    On success, the result is a non NULL descriptor that shall be
00093    passed to the other sim_foo functions.  While the simulator
00094    configuration can be parameterized by (in decreasing precedence)
00095    ARGV's SIM-OPTION, ARGV's TARGET-PROGRAM and the ABFD argument, the
00096    successful creation of the simulator shall not dependent on the
00097    presence of any of these arguments/options.
00098 
00099    Hardware simulator: The created simulator shall be sufficiently
00100    initialized to handle, with out restrictions any client requests
00101    (including memory reads/writes, register fetch/stores and a
00102    resume).
00103 
00104    Process simulator: that process is not created until a call to
00105    sim_create_inferior.  FIXME: What should the state of the simulator
00106    be? */
00107 
00108 SIM_DESC sim_open PARAMS ((SIM_OPEN_KIND kind, struct host_callback_struct *callback, struct bfd *abfd, char **argv));
00109 
00110 
00111 /* Destory a simulator instance.
00112 
00113    QUITTING is non-zero if we cannot hang on errors.
00114 
00115    This may involve freeing target memory and closing any open files
00116    and mmap'd areas.  You cannot assume sim_kill has already been
00117    called. */
00118 
00119 void sim_close PARAMS ((SIM_DESC sd, int quitting));
00120 
00121 
00122 /* Load program PROG into the simulators memory.
00123 
00124    If ABFD is non-NULL, the bfd for the file has already been opened.
00125    The result is a return code indicating success.
00126 
00127    Hardware simulator: Normally, each program section is written into
00128    memory according to that sections LMA using physical (direct)
00129    addressing.  The exception being systems, such as PPC/CHRP, which
00130    support more complicated program loaders.  A call to this function
00131    should not effect the state of the processor registers.  Multiple
00132    calls to this function are permitted and have an accumulative
00133    effect.
00134 
00135    Process simulator: Calls to this function may be ignored.
00136 
00137    FIXME: Most hardware simulators load the image at the VMA using
00138    virtual addressing.
00139 
00140    FIXME: For some hardware targets, before a loaded program can be
00141    executed, it requires the manipulation of VM registers and tables.
00142    Such manipulation should probably (?) occure in
00143    sim_create_inferior. */
00144 
00145 SIM_RC sim_load PARAMS ((SIM_DESC sd, char *prog, struct bfd *abfd, int from_tty));
00146 
00147 
00148 /* Prepare to run the simulated program.
00149 
00150    ABFD, if not NULL, provides initial processor state information.
00151    ARGV and ENV, if non NULL, are NULL terminated lists of pointers.
00152 
00153    Hardware simulator: This function shall initialize the processor
00154    registers to a known value.  The program counter and possibly stack
00155    pointer shall be set using information obtained from ABFD (or
00156    hardware reset defaults).  ARGV and ENV, dependant on the target
00157    ABI, may be written to memory.
00158 
00159    Process simulator: After a call to this function, a new process
00160    instance shall exist. The TEXT, DATA, BSS and stack regions shall
00161    all be initialized, ARGV and ENV shall be written to process
00162    address space (according to the applicable ABI) and the program
00163    counter and stack pointer set accordingly. */
00164 
00165 SIM_RC sim_create_inferior PARAMS ((SIM_DESC sd, struct bfd *abfd, char **argv, char **env));
00166 
00167 
00168 /* Fetch LENGTH bytes of the simulated program's memory.  Start fetch
00169    at virtual address MEM and store in BUF.  Result is number of bytes
00170    read, or zero if error.  */
00171 
00172 int sim_read PARAMS ((SIM_DESC sd, SIM_ADDR mem, unsigned char *buf, int length));
00173 
00174 
00175 /* Store LENGTH bytes from BUF into the simulated program's
00176    memory. Store bytes starting at virtual address MEM. Result is
00177    number of bytes write, or zero if error.  */
00178 
00179 int sim_write PARAMS ((SIM_DESC sd, SIM_ADDR mem, unsigned char *buf, int length));
00180 
00181 
00182 /* Fetch register REGNO storing its raw (target endian) value in the
00183    LENGTH byte buffer BUF.  Return the actual size of the register or
00184    zero if REGNO is not applicable.
00185 
00186    Legacy implementations ignore LENGTH and always return -1.
00187 
00188    If LENGTH does not match the size of REGNO no data is transfered
00189    (the actual register size is still returned). */
00190 
00191 int sim_fetch_register PARAMS ((SIM_DESC sd, int regno, unsigned char *buf, int length));
00192 
00193 
00194 /* Store register REGNO from the raw (target endian) value in BUF.
00195    Return the actual size of the register or zero if REGNO is not
00196    applicable.
00197 
00198    Legacy implementations ignore LENGTH and always return -1.
00199 
00200    If LENGTH does not match the size of REGNO no data is transfered
00201    (the actual register size is still returned). */
00202 
00203 int sim_store_register PARAMS ((SIM_DESC sd, int regno, unsigned char *buf, int length));
00204 
00205 
00206 /* Print whatever statistics the simulator has collected.
00207 
00208    VERBOSE is currently unused and must always be zero.  */
00209 
00210 void sim_info PARAMS ((SIM_DESC sd, int verbose));
00211 
00212 
00213 /* Run (or resume) the simulated program.
00214 
00215    STEP, when non-zero indicates that only a single simulator cycle
00216    should be emulated.
00217 
00218    SIGGNAL, if non-zero is a (HOST) SIGRC value indicating the type of
00219    event (hardware interrupt, signal) to be delivered to the simulated
00220    program.
00221 
00222    Hardware simulator: If the SIGRC value returned by
00223    sim_stop_reason() is passed back to the simulator via SIGGNAL then
00224    the hardware simulator shall correctly deliver the hardware event
00225    indicated by that signal.  If a value of zero is passed in then the
00226    simulation will continue as if there were no outstanding signal.
00227    The effect of any other SIGGNAL value is is implementation
00228    dependant.
00229 
00230    Process simulator: If SIGRC is non-zero then the corresponding
00231    signal is delivered to the simulated program and execution is then
00232    continued.  A zero SIGRC value indicates that the program should
00233    continue as normal. */
00234 
00235 void sim_resume PARAMS ((SIM_DESC sd, int step, int siggnal));
00236 
00237 
00238 /* Asynchronous request to stop the simulation.
00239    A nonzero return indicates that the simulator is able to handle
00240    the request */
00241 
00242 int sim_stop PARAMS ((SIM_DESC sd));
00243 
00244 
00245 /* Fetch the REASON why the program stopped.
00246 
00247    SIM_EXITED: The program has terminated. SIGRC indicates the target
00248    dependant exit status.
00249 
00250    SIM_STOPPED: The program has stopped.  SIGRC uses the host's signal
00251    numbering as a way of identifying the reaon: program interrupted by
00252    user via a sim_stop request (SIGINT); a breakpoint instruction
00253    (SIGTRAP); a completed single step (SIGTRAP); an internal error
00254    condition (SIGABRT); an illegal instruction (SIGILL); Access to an
00255    undefined memory region (SIGSEGV); Mis-aligned memory access
00256    (SIGBUS).  For some signals information in addition to the signal
00257    number may be retained by the simulator (e.g. offending address),
00258    that information is not directly accessable via this interface.
00259 
00260    SIM_SIGNALLED: The program has been terminated by a signal. The
00261    simulator has encountered target code that causes the the program
00262    to exit with signal SIGRC.
00263 
00264    SIM_RUNNING, SIM_POLLING: The return of one of these values
00265    indicates a problem internal to the simulator. */
00266 
00267 enum sim_stop { sim_running, sim_polling, sim_exited, sim_stopped, sim_signalled };
00268 
00269 void sim_stop_reason PARAMS ((SIM_DESC sd, enum sim_stop *reason, int *sigrc));
00270 
00271 
00272 /* Passthru for other commands that the simulator might support.
00273    Simulators should be prepared to deal with any combination of NULL
00274    or empty CMD. */
00275 
00276 void sim_do_command PARAMS ((SIM_DESC sd, char *cmd));
00277 
00278 #ifdef __cplusplus
00279 }
00280 #endif
00281 
00282 #endif /* !defined (REMOTE_SIM_H) */