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.
5 This file is part of GDB.
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.
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.
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. */
22 #include <sys/types.h>
27 #ifdef HAVE_SYS_WAIT_H
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
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.
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).
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.
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
68 Corollary tasks are the creation and deletion of event sources. */
70 typedef PTR gdb_client_data;
71 typedef struct gdb_event gdb_event;
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));
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. */
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. */
95 /* Information about each file descriptor we register with the event
98 typedef struct file_handler
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
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. */
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. */
119 typedef struct async_signal_handler
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 */
127 async_signal_handler;
129 /* Where to add an event onto the event queue, by queue_event. */
132 /* Add at tail of queue. It will be processed in first in first
135 /* Add at head of queue. It will be processed in last in first out
141 /* Tell create_file_handler what events we are interested in.
142 This is used by the select version of the event loop. */
144 #define GDB_READABLE (1<<1)
145 #define GDB_WRITABLE (1<<2)
146 #define GDB_EXCEPTION (1<<3)
148 /* Type of the mask arguments to select. */
151 #define SELECT_MASK fd_set
154 typedef long fd_mask;
157 #define SELECT_MASK void
159 #define SELECT_MASK int
163 /* Define "NBBY" (number of bits per byte) if it's not already defined. */
170 /* Define the number of fd_masks in an fd_set */
174 #define FD_SETSIZE OPEN_MAX
176 #define FD_SETSIZE 256
179 #if !defined(howmany)
180 #define howmany(x, y) (((x)+((y)-1))/(y))
183 #define NFDBITS NBBY*sizeof(fd_mask)
185 #define MASK_SIZE howmany(FD_SETSIZE, NFDBITS)
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. */
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
219 #define MAXPROMPTS 10
228 prompt_stack[MAXPROMPTS];
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
236 extern void delete_file_handler PARAMS ((int));
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));