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