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