gdb/event-loop.h

   1 /* Definitions used by the GDB event loop.
   2    Copyright 1999 Free Software Foundation, Inc.
   3    Written by Elena Zannoni <ezannoni@cygnus.com> of Cygnus Solutions.
   4
   5    This file is part of GDB.
   6
   7    This program is free software; you can redistribute it and/or modify
   8    it under the terms of the GNU General Public License as published by
   9    the Free Software Foundation; either version 2 of the License, or
  10    (at your option) any later version.
  11
  12    This program is distributed in the hope that it will be useful,
  13    but WITHOUT ANY WARRANTY; without even the implied warranty of
  14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15    GNU General Public License for more details.
  16
  17    You should have received a copy of the GNU General Public License
  18    along with this program; if not, write to the Free Software
  19    Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.  */
  20
  21 #include <stdlib.h>
  22 #include <sys/types.h>
  23 #include <sys/time.h>
  24 #include <signal.h>
  25 #include <unistd.h>
  26 #include <fcntl.h>
  27 #ifdef HAVE_SYS_WAIT_H
  28 #include <sys/wait.h>
  29 #endif
  30 #include "defs.h"
  31
  32 /* An event loop listens for events from multiple event sources. When
  33    an event arrives, it is queued and processed by calling the
  34    appropriate event handler. The event loop then continues to listen
  35    for more events. An event loop completes when there are no event
  36    sources to listen on.  External event sources can be plugged into
  37    the loop.
  38
  39    There are 3 main components:
  40    - a list of file descriptors to be monitored, GDB_NOTIFIER.
  41    - a list of events that have occurred, EVENT_QUEUE.
  42    - a list of signal handling functions, SIGHANDLER_LIST.
  43
  44    GDB_NOTIFIER keeps track of the event sources. Event sources for
  45    gdb are currently the UI and the target.  Gdb communicates with the
  46    command line user interface via the readline library and usually
  47    communicates with remote targets via a serial port. Serial ports
  48    are represented in GDB as file descriptors and select/poll calls.
  49    For native targets instead, the communication consists of calls to
  50    ptrace and waits (via signals) or calls to poll/select (via file
  51    descriptors). In the current gdb, the code handling events related
  52    to the target resides in the wait_for_inferior function and in
  53    various target specific files (*-tdep.c).
  54
  55    EVENT_QUEUE keeps track of the events that have happened during the
  56    last iteration of the event loop, and need to be processed.  An
  57    event is represented by a procedure to be invoked in order to
  58    process the event.  The queue is scanned head to tail.  If the
  59    event of interest is a change of state in a file descriptor, then a
  60    call to poll or select will be made to detect it.
  61
  62    If the events generate signals, they are also queued by special
  63    functions that are invoked through traditional signal handlers.
  64    The actions to be taken is response to such events will be executed
  65    when the SIGHANDLER_LIST is scanned, the next time through the
  66    infinite loop.
  67
  68    Corollary tasks are the creation and deletion of event sources. */
  69
  70 typedef PTR gdb_client_data;
  71 typedef struct gdb_event gdb_event;
  72
  73 typedef void (file_handler_func) PARAMS ((gdb_client_data, int mask));
  74 typedef void (async_handler_func) PARAMS ((gdb_client_data));
  75 typedef void (event_handler_func) PARAMS ((int));
  76
  77 /* Event for the GDB event system.  Events are queued by calling
  78    async_queue_event and serviced later on by gdb_do_one_event. An
  79    event can be, for instance, a file descriptor becoming ready to be
  80    read. Servicing an event simply means that the procedure PROC will
  81    be called.  We have 2 queues, one for file handlers that we listen
  82    to in the event loop, and one for the file handlers+events that are
  83    ready. The procedure PROC associated with each event is always the
  84    same (handle_file_event).  Its duty is to invoke the handler
  85    associated with the file descriptor whose state change generated
  86    the event, plus doing other cleanups adn such. */
  87
  88 struct gdb_event
  89   {
  90     event_handler_func *proc;   /* Procedure to call to service this event. */
  91     int fd;                     /* File descriptor that is ready. */
  92     struct gdb_event *next_event;       /* Next in list of events or NULL. */
  93   };
  94
  95 /* Information about each file descriptor we register with the event
  96    loop. */
  97
  98 typedef struct file_handler
  99   {
 100     int fd;                     /* File descriptor. */
 101     int mask;                   /* Events we want to monitor: POLLIN, etc. */
 102     int ready_mask;             /* Events that have been seen since
 103                                    the last time. */
 104     file_handler_func *proc;    /* Procedure to call when fd is ready. */
 105     gdb_client_data client_data;        /* Argument to pass to proc. */
 106     struct file_handler *next_file;     /* Next registered file descriptor. */
 107   }
 108 file_handler;
 109
 110 /* PROC is a function to be invoked when the READY flag is set. This
 111    happens when there has been a signal and the corresponding signal
 112    handler has 'triggered' this async_signal_handler for
 113    execution. The actual work to be done in response to a signal will
 114    be carried out by PROC at a later time, within process_event. This
 115    provides a deferred execution of signal handlers.
 116    Async_init_signals takes care of setting up such an
 117    asyn_signal_handler for each interesting signal. */
 118
 119 typedef struct async_signal_handler
 120   {
 121     int ready;  /* If ready, call this handler from the main event loop,
 122                                    using invoke_async_handler. */
 123     struct async_signal_handler *next_handler;  /* Ptr to next handler */
 124     async_handler_func *proc;   /* Function to call to do the work */
 125     gdb_client_data client_data;        /* Argument to async_handler_func */
 126   }
 127 async_signal_handler;
 128
 129 /* Where to add an event onto the event queue, by queue_event. */
 130 typedef enum
 131   {
 132     /* Add at tail of queue. It will be processed in first in first
 133        out order. */
 134     TAIL,
 135     /* Add at head of queue. It will be processed in last in first out
 136        order. */
 137     HEAD
 138   }
 139 queue_position;
 140
 141 /* Tell create_file_handler what events we are interested in.
 142    This is used by the select version of the event loop. */
 143
 144 #define GDB_READABLE    (1<<1)
 145 #define GDB_WRITABLE    (1<<2)
 146 #define GDB_EXCEPTION   (1<<3)
 147
 148 /* Type of the mask arguments to select. */
 149
 150 #ifndef NO_FD_SET
 151 #define SELECT_MASK fd_set
 152 #else
 153 #ifndef _AIX
 154 typedef long fd_mask;
 155 #endif
 156 #if defined(_IBMR2)
 157 #define SELECT_MASK void
 158 #else
 159 #define SELECT_MASK int
 160 #endif
 161 #endif
 162
 163 /* Define "NBBY" (number of bits per byte) if it's not already defined. */
 164
 165 #ifndef NBBY
 166 #define NBBY 8
 167 #endif
 168
 169
 170 /* Define the number of fd_masks in an fd_set */
 171
 172 #ifndef FD_SETSIZE
 173 #ifdef OPEN_MAX
 174 #define FD_SETSIZE OPEN_MAX
 175 #else
 176 #define FD_SETSIZE 256
 177 #endif
 178 #endif
 179 #if !defined(howmany)
 180 #define howmany(x, y) (((x)+((y)-1))/(y))
 181 #endif
 182 #ifndef NFDBITS
 183 #define NFDBITS NBBY*sizeof(fd_mask)
 184 #endif
 185 #define MASK_SIZE howmany(FD_SETSIZE, NFDBITS)
 186
 187
 188 /* Stack for prompts. Each prompt is composed as a prefix, a prompt
 189    and a suffix. The prompt to be displayed at any given time is the
 190    one on top of the stack.  A stack is necessary because of cases in
 191    which the execution of a gdb command requires further input from
 192    the user, like for instance 'commands' for breakpoints and
 193    'actions' for tracepoints. In these cases, the prompt is '>' and
 194    gdb should process input using the asynchronous readline interface
 195    and the event loop.  In order to achieve this, we need to save
 196    somewhere the state of GDB, i.e. that it is processing user input
 197    as part of a command and not as part of the top level command loop.
 198    The prompt stack represents part of the saved state. Another part
 199    would be the function that readline would invoke after a whole line
 200    of input has ben entered. This second piece would be something
 201    like, for instance, where to return within the code for the actions
 202    commands after a line has been read.  This latter portion has not
 203    beeen implemented yet.  The need for a 3-part prompt arises from
 204    the annotation level. When this is set to 2, the prompt is actually
 205    composed of a prefix, the prompt itself and a suffix. */
 206
 207 /* At any particular time there will be always at least one prompt on
 208    the stack, the one being currently displayed by gdb. If gdb is
 209    using annotation level equal 2, there will be 2 prompts on the
 210    stack: the usual one, w/o prefix and suffix (at top - 1), and the
 211    'composite' one with prefix and suffix added (at top). At this
 212    time, this is the only use of the prompt stack. Resetting annotate
 213    to 0 or 1, pops the top of the stack, resetting its size to one
 214    element. The MAXPROMPTS limit is safe, for now. Once other cases
 215    are dealt with (like the different prompts used for 'commands' or
 216    'actions') this array implementation of the prompt stack may have
 217    to change. */
 218
 219 #define MAXPROMPTS 10
 220 struct prompts
 221   {
 222     struct
 223       {
 224         char *prefix;
 225         char *prompt;
 226         char *suffix;
 227       }
 228     prompt_stack[MAXPROMPTS];
 229     int top;
 230   };
 231
 232 #define PROMPT(X) the_prompts.prompt_stack[the_prompts.top + X].prompt
 233 #define PREFIX(X) the_prompts.prompt_stack[the_prompts.top + X].prefix
 234 #define SUFFIX(X) the_prompts.prompt_stack[the_prompts.top + X].suffix
 235
 236 extern void delete_file_handler PARAMS ((int));
 237 extern void
 238   create_file_handler PARAMS ((int, int, file_handler_func, gdb_client_data));
 239 extern int gdb_do_one_event PARAMS ((void));
 240 extern void mark_async_signal_handler PARAMS ((async_signal_handler *));
 241 extern async_signal_handler *
 242   create_async_signal_handler PARAMS ((async_handler_func *, gdb_client_data));
 243