Back to index

cell-binutils  2.17cvs20070401
callback.h
Go to the documentation of this file.
00001 /* Remote target system call callback support.
00002    Copyright 1997, 2007 Free Software Foundation, Inc.
00003    Contributed by Cygnus Solutions.
00004 
00005 This file is part of GDB.
00006 
00007 This program is free software; you can redistribute it and/or modify
00008 it under the terms of the GNU General Public License as published by
00009 the Free Software Foundation; either version 2 of the License, or
00010 (at your option) any later version.
00011 
00012 This program is distributed in the hope that it will be useful,
00013 but WITHOUT ANY WARRANTY; without even the implied warranty of
00014 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00015 GNU General Public License for more details.
00016 
00017 You should have received a copy of the GNU General Public License
00018 along with this program; if not, write to the Free Software
00019 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.  */
00020 
00021 /* This interface isn't intended to be specific to any particular kind
00022    of remote (hardware, simulator, whatever).  As such, support for it
00023    (e.g. sim/common/callback.c) should *not* live in the simulator source
00024    tree, nor should it live in the gdb source tree.  */
00025 
00026 /* There are various ways to handle system calls:
00027 
00028    1) Have a simulator intercept the appropriate trap instruction and
00029    directly perform the system call on behalf of the target program.
00030    This is the typical way of handling system calls for embedded targets.
00031    [Handling system calls for embedded targets isn't that much of an
00032    oxymoron as running compiler testsuites make use of the capability.]
00033 
00034    This method of system call handling is done when STATE_ENVIRONMENT
00035    is ENVIRONMENT_USER.
00036 
00037    2) Have a simulator emulate the hardware as much as possible.
00038    If the program running on the real hardware communicates with some sort
00039    of target manager, one would want to be able to run this program on the
00040    simulator as well.
00041 
00042    This method of system call handling is done when STATE_ENVIRONMENT
00043    is ENVIRONMENT_OPERATING.
00044 */
00045 
00046 #ifndef CALLBACK_H
00047 #define CALLBACK_H
00048 
00049 /* ??? The reason why we check for va_start here should be documented.  */
00050 
00051 #ifndef va_start
00052 #include <ansidecl.h>
00053 #include <stdarg.h>
00054 #endif
00055 /* Needed for enum bfd_endian.  */
00056 #include "bfd.h"
00057 
00058 /* Mapping of host/target values.  */
00059 /* ??? For debugging purposes, one might want to add a string of the
00060    name of the symbol.  */
00061 
00062 typedef struct {
00063   int host_val;
00064   int target_val;
00065 } CB_TARGET_DEFS_MAP;
00066 
00067 #define MAX_CALLBACK_FDS 10
00068 
00069 /* Forward decl for stat/fstat.  */
00070 struct stat;
00071 
00072 typedef struct host_callback_struct host_callback;
00073 
00074 struct host_callback_struct 
00075 {
00076   int (*close) PARAMS ((host_callback *,int));
00077   int (*get_errno) PARAMS ((host_callback *));
00078   int (*isatty) PARAMS ((host_callback *, int));
00079   int (*lseek) PARAMS ((host_callback *, int, long , int));
00080   int (*open) PARAMS ((host_callback *, const char*, int mode));
00081   int (*read) PARAMS ((host_callback *,int,  char *, int));
00082   int (*read_stdin) PARAMS (( host_callback *, char *, int));
00083   int (*rename) PARAMS ((host_callback *, const char *, const char *));
00084   int (*system) PARAMS ((host_callback *, const char *));
00085   long (*time) PARAMS ((host_callback *, long *));
00086   int (*unlink) PARAMS ((host_callback *, const char *));
00087   int (*write) PARAMS ((host_callback *,int, const char *, int));
00088   int (*write_stdout) PARAMS ((host_callback *, const char *, int));
00089   void (*flush_stdout) PARAMS ((host_callback *));
00090   int (*write_stderr) PARAMS ((host_callback *, const char *, int));
00091   void (*flush_stderr) PARAMS ((host_callback *));
00092   int (*stat) PARAMS ((host_callback *, const char *, struct stat *));
00093   int (*fstat) PARAMS ((host_callback *, int, struct stat *));
00094   int (*lstat) PARAMS ((host_callback *, const char *, struct stat *));
00095   int (*ftruncate) PARAMS ((host_callback *, int, long));
00096   int (*truncate) PARAMS ((host_callback *, const char *, long));
00097   int (*pipe) PARAMS ((host_callback *, int *));
00098 
00099   /* Called by the framework when a read call has emptied a pipe buffer.  */
00100   void (*pipe_empty) PARAMS ((host_callback *, int read_fd, int write_fd));
00101 
00102   /* Called by the framework when a write call makes a pipe buffer
00103      non-empty.  */
00104   void (*pipe_nonempty) PARAMS ((host_callback *, int read_fd, int write_fd));
00105 
00106   /* When present, call to the client to give it the oportunity to
00107      poll any io devices for a request to quit (indicated by a nonzero
00108      return value). */
00109   int (*poll_quit) PARAMS ((host_callback *));
00110 
00111   /* Used when the target has gone away, so we can close open
00112      handles and free memory etc etc.  */
00113   int (*shutdown) PARAMS ((host_callback *));
00114   int (*init)     PARAMS ((host_callback *));
00115 
00116   /* depreciated, use vprintf_filtered - Talk to the user on a console.  */
00117   void (*printf_filtered) PARAMS ((host_callback *, const char *, ...));
00118 
00119   /* Talk to the user on a console.  */
00120   void (*vprintf_filtered) PARAMS ((host_callback *, const char *, va_list));
00121 
00122   /* Same as vprintf_filtered but to stderr.  */
00123   void (*evprintf_filtered) PARAMS ((host_callback *, const char *, va_list));
00124 
00125   /* Print an error message and "exit".
00126      In the case of gdb "exiting" means doing a longjmp back to the main
00127      command loop.  */
00128   void (*error) PARAMS ((host_callback *, const char *, ...));
00129 
00130   int last_errno;           /* host format */
00131 
00132   int fdmap[MAX_CALLBACK_FDS];
00133   /* fd_buddy is used to contruct circular lists of target fds that point to
00134      the same host fd.  A uniquely mapped fd points to itself; for a closed
00135      one, fd_buddy has the value -1.  The host file descriptors for stdin /
00136      stdout / stderr are never closed by the simulators, so they are put
00137      in a special fd_buddy circular list which also has MAX_CALLBACK_FDS
00138      as a member.  */
00139   /* ??? We don't have a callback entry for dup, although it is trival to
00140      implement now.  */
00141   short fd_buddy[MAX_CALLBACK_FDS+1];
00142 
00143   /* 0 = none, >0 = reader (index of writer),
00144      <0 = writer (negative index of reader).
00145      If abs (ispipe[N]) == N, then N is an end of a pipe whose other
00146      end is closed.  */
00147   short ispipe[MAX_CALLBACK_FDS];
00148 
00149   /* A writer stores the buffer at its index.  Consecutive writes
00150      realloc the buffer and add to the size.  The reader indicates the
00151      read part in its .size, until it has consumed it all, at which
00152      point it deallocates the buffer and zeroes out both sizes.  */
00153   struct pipe_write_buffer
00154   {
00155     int size;
00156     char *buffer;
00157   } pipe_buffer[MAX_CALLBACK_FDS];
00158 
00159   /* System call numbers.  */
00160   CB_TARGET_DEFS_MAP *syscall_map;
00161   /* Errno values.  */
00162   CB_TARGET_DEFS_MAP *errno_map;
00163   /* Flags to the open system call.  */
00164   CB_TARGET_DEFS_MAP *open_map;
00165   /* Signal numbers.  */
00166   CB_TARGET_DEFS_MAP *signal_map;
00167   /* Layout of `stat' struct.
00168      The format is a series of "name,length" pairs separated by colons.
00169      Empty space is indicated with a `name' of "space".
00170      All padding must be explicitly mentioned.
00171      Lengths are in bytes.  If this needs to be extended to bits,
00172      use "name.bits".
00173      Example: "st_dev,4:st_ino,4:st_mode,4:..."  */
00174   const char *stat_map;
00175 
00176   enum bfd_endian target_endian;
00177 
00178   /* Size of an "int" on the target (for syscalls whose ABI uses "int").
00179      This must include padding, and only padding-at-higher-address is
00180      supported.  For example, a 64-bit target with 32-bit int:s which
00181      are padded to 64 bits when in an array, should supposedly set this
00182      to 8.  The default is 4 which matches ILP32 targets and 64-bit
00183      targets with 32-bit ints and no padding.  */
00184   int target_sizeof_int;
00185 
00186   /* Marker for those wanting to do sanity checks.
00187      This should remain the last member of this struct to help catch
00188      miscompilation errors. */
00189 #define HOST_CALLBACK_MAGIC 4705 /* teds constant */
00190   int magic;
00191 };
00192 
00193 extern host_callback default_callback;
00194 
00195 /* Canonical versions of system call numbers.
00196    It's not intended to willy-nilly throw every system call ever heard
00197    of in here.  Only include those that have an important use.
00198    ??? One can certainly start a discussion over the ones that are currently
00199    here, but that will always be true.  */
00200 
00201 /* These are used by the ANSI C support of libc.  */
00202 #define       CB_SYS_exit   1
00203 #define       CB_SYS_open   2
00204 #define       CB_SYS_close  3
00205 #define       CB_SYS_read   4
00206 #define       CB_SYS_write  5
00207 #define       CB_SYS_lseek  6
00208 #define       CB_SYS_unlink 7
00209 #define       CB_SYS_getpid 8
00210 #define       CB_SYS_kill   9
00211 #define CB_SYS_fstat    10
00212 /*#define CB_SYS_sbrk       11 - not currently a system call, but reserved.  */
00213 
00214 /* ARGV support.  */
00215 #define CB_SYS_argvlen      12
00216 #define CB_SYS_argv  13
00217 
00218 /* These are extras added for one reason or another.  */
00219 #define CB_SYS_chdir 14
00220 #define CB_SYS_stat  15
00221 #define CB_SYS_chmod        16
00222 #define CB_SYS_utime        17
00223 #define CB_SYS_time  18
00224 
00225 /* More standard syscalls.  */
00226 #define CB_SYS_lstat    19
00227 #define CB_SYS_rename       20
00228 #define CB_SYS_truncate     21
00229 #define CB_SYS_ftruncate 22
00230 #define CB_SYS_pipe  23
00231 
00232 /* Struct use to pass and return information necessary to perform a
00233    system call.  */
00234 /* FIXME: Need to consider target word size.  */
00235 
00236 typedef struct cb_syscall {
00237   /* The target's value of what system call to perform.  */
00238   int func;
00239   /* The arguments to the syscall.  */
00240   long arg1, arg2, arg3, arg4;
00241 
00242   /* The result.  */
00243   long result;
00244   /* Some system calls have two results.  */
00245   long result2;
00246   /* The target's errno value, or 0 if success.
00247      This is converted to the target's value with host_to_target_errno.  */
00248   int errcode;
00249 
00250   /* Working space to be used by memory read/write callbacks.  */
00251   PTR p1;
00252   PTR p2;
00253   long x1,x2;
00254 
00255   /* Callbacks for reading/writing memory (e.g. for read/write syscalls).
00256      ??? long or unsigned long might be better to use for the `count'
00257      argument here.  We mimic sim_{read,write} for now.  Be careful to
00258      test any changes with -Wall -Werror, mixed signed comparisons
00259      will get you.  */
00260   int (*read_mem) PARAMS ((host_callback * /*cb*/, struct cb_syscall * /*sc*/,
00261                         unsigned long /*taddr*/, char * /*buf*/,
00262                         int /*bytes*/));
00263   int (*write_mem) PARAMS ((host_callback * /*cb*/, struct cb_syscall * /*sc*/,
00264                          unsigned long /*taddr*/, const char * /*buf*/,
00265                          int /*bytes*/));
00266 
00267   /* For sanity checking, should be last entry.  */
00268   int magic;
00269 } CB_SYSCALL;
00270 
00271 /* Magic number sanity checker.  */
00272 #define CB_SYSCALL_MAGIC 0x12344321
00273 
00274 /* Macro to initialize CB_SYSCALL.  Called first, before filling in
00275    any fields.  */
00276 #define CB_SYSCALL_INIT(sc) \
00277 do { \
00278   memset ((sc), 0, sizeof (*(sc))); \
00279   (sc)->magic = CB_SYSCALL_MAGIC; \
00280 } while (0)
00281 
00282 /* Return codes for various interface routines.  */
00283 
00284 typedef enum {
00285   CB_RC_OK = 0,
00286   /* generic error */
00287   CB_RC_ERR,
00288   /* either file not found or no read access */
00289   CB_RC_ACCESS,
00290   CB_RC_NO_MEM
00291 } CB_RC;
00292 
00293 /* Read in target values for system call numbers, errno values, signals.  */
00294 CB_RC cb_read_target_syscall_maps PARAMS ((host_callback *, const char *));
00295 
00296 /* Translate target to host syscall function numbers.  */
00297 int cb_target_to_host_syscall PARAMS ((host_callback *, int));
00298 
00299 /* Translate host to target errno value.  */
00300 int cb_host_to_target_errno PARAMS ((host_callback *, int));
00301 
00302 /* Translate target to host open flags.  */
00303 int cb_target_to_host_open PARAMS ((host_callback *, int));
00304 
00305 /* Translate target signal number to host.  */
00306 int cb_target_to_host_signal PARAMS ((host_callback *, int));
00307 
00308 /* Translate host signal number to target.  */
00309 int cb_host_to_target_signal PARAMS ((host_callback *, int));
00310 
00311 /* Translate host stat struct to target.
00312    If stat struct ptr is NULL, just compute target stat struct size.
00313    Result is size of target stat struct or 0 if error.  */
00314 int cb_host_to_target_stat PARAMS ((host_callback *, const struct stat *, PTR));
00315 
00316 /* Translate a value to target endian.  */
00317 void cb_store_target_endian PARAMS ((host_callback *, char *, int, long));
00318 
00319 /* Perform a system call.  */
00320 CB_RC cb_syscall PARAMS ((host_callback *, CB_SYSCALL *));
00321 
00322 #endif