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