20000-05-19 H.J. Lu (hjl@gnu.org)

[binutils-gdb.git] / include / remote-sim.h

diff --git a/include/remote-sim.h b/include/remote-sim.h
index c4fecc0ec3934a2dfe74852e0f0a442ecf50d8cd..b32f93fddcad88d4ddcbb2e6077a525183bd11ed 100644 (file)
--- a/include/remote-sim.h
+++ b/include/remote-sim.h
@@ -180,15 +180,28 @@ int sim_read PARAMS ((SIM_DESC sd, SIM_ADDR mem, unsigned char *buf, int length)
 int sim_write PARAMS ((SIM_DESC sd, SIM_ADDR mem, unsigned char *buf, int length));
 
 
-/* Fetch register REGNO and store the raw (target endian) value in
-   BUF.  */
+/* Fetch register REGNO storing its raw (target endian) value in the
+   LENGTH byte buffer BUF.  Return the actual size of the register or
+   zero if REGNO is not applicable.
 
-void sim_fetch_register PARAMS ((SIM_DESC sd, int regno, unsigned char *buf));
+   Legacy implementations ignore LENGTH and always return -1.
 
+   If LENGTH does not match the size of REGNO no data is transfered
+   (the actual register size is still returned). */
 
-/* Store register REGNO from the raw (target endian) value in BUF.  */
+int sim_fetch_register PARAMS ((SIM_DESC sd, int regno, unsigned char *buf, int length));
 
-void sim_store_register PARAMS ((SIM_DESC sd, int regno, unsigned char *buf));
+
+/* Store register REGNO from the raw (target endian) value in BUF.
+   Return the actual size of the register or zero if REGNO is not
+   applicable.
+
+   Legacy implementations ignore LENGTH and always return -1.
+
+   If LENGTH does not match the size of REGNO no data is transfered
+   (the actual register size is still returned). */
+
+int sim_store_register PARAMS ((SIM_DESC sd, int regno, unsigned char *buf, int length));
 
 
 /* Print whatever statistics the simulator has collected.
@@ -198,7 +211,27 @@ void sim_store_register PARAMS ((SIM_DESC sd, int regno, unsigned char *buf));
 void sim_info PARAMS ((SIM_DESC sd, int verbose));
 
 
-/* Run (or resume) the simulated program.  */
+/* Run (or resume) the simulated program.
+
+   STEP, when non-zero indicates that only a single simulator cycle
+   should be emulated.
+
+   SIGGNAL, if non-zero is a (HOST) SIGRC value indicating the type of
+   event (hardware interrupt, signal) to be delivered to the simulated
+   program.
+
+   Hardware simulator: If the SIGRC value returned by
+   sim_stop_reason() is passed back to the simulator via SIGGNAL then
+   the hardware simulator shall correctly deliver the hardware event
+   indicated by that signal.  If a value of zero is passed in then the
+   simulation will continue as if there were no outstanding signal.
+   The effect of any other SIGGNAL value is is implementation
+   dependant.
+
+   Process simulator: If SIGRC is non-zero then the corresponding
+   signal is delivered to the simulated program and execution is then
+   continued.  A zero SIGRC value indicates that the program should
+   continue as normal. */
 
 void sim_resume PARAMS ((SIM_DESC sd, int step, int siggnal));
 
@@ -221,10 +254,13 @@ int sim_stop PARAMS ((SIM_DESC sd));
    (SIGTRAP); a completed single step (SIGTRAP); an internal error
    condition (SIGABRT); an illegal instruction (SIGILL); Access to an
    undefined memory region (SIGSEGV); Mis-aligned memory access
-   (SIGBUS).
+   (SIGBUS).  For some signals information in addition to the signal
+   number may be retained by the simulator (e.g. offending address),
+   that information is not directly accessable via this interface.
 
-   SIM_SIGNALLED: The simulator encountered target code that requires
-   the signal SIGRC to be delivered to the simulated program.
+   SIM_SIGNALLED: The program has been terminated by a signal. The
+   simulator has encountered target code that causes the the program
+   to exit with signal SIGRC.
 
    SIM_RUNNING, SIM_POLLING: The return of one of these values
    indicates a problem internal to the simulator. */
@@ -272,15 +308,27 @@ void sim_set_callbacks PARAMS ((struct host_callback_struct *));
 void sim_size PARAMS ((int i));
 
 
-/* Run a simulation with tracing enabled.
+/* Single-step simulator with tracing enabled.
    THIS PROCEDURE IS DEPRECIATED.
+   THIS PROCEDURE IS EVEN MORE DEPRECATED THAN SIM_SET_TRACE
    GDB and NRUN do not use this interface.
-   This procedure does not take a SIM_DESC argument as it is
-   used before sim_open. */
+   This procedure returns: ``0'' indicating that the simulator should
+   be continued using sim_trace() calls; ``1'' indicating that the
+   simulation has finished. */
 
 int sim_trace PARAMS ((SIM_DESC sd));
 
 
+/* Enable tracing.
+   THIS PROCEDURE IS DEPRECIATED.
+   GDB and NRUN do not use this interface.
+   This procedure returns: ``0'' indicating that the simulator should
+   be continued using sim_trace() calls; ``1'' indicating that the
+   simulation has finished. */
+
+void sim_set_trace PARAMS ((void));
+
+
 /* Configure the size of the profile buffer.
    THIS PROCEDURE IS DEPRECIATED.
    GDB and NRUN do not use this interface.