GDB (xrefs)
/tmp/gdb-7.10/gdb/serial.h
Go to the documentation of this file.
1 /* Remote serial support interface definitions for GDB, the GNU Debugger.
2  Copyright (C) 1992-2015 Free Software Foundation, Inc.
3 
4  This file is part of GDB.
5 
6  This program is free software; you can redistribute it and/or modify
7  it under the terms of the GNU General Public License as published by
8  the Free Software Foundation; either version 3 of the License, or
9  (at your option) any later version.
10 
11  This program is distributed in the hope that it will be useful,
12  but WITHOUT ANY WARRANTY; without even the implied warranty of
13  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14  GNU General Public License for more details.
15 
16  You should have received a copy of the GNU General Public License
17  along with this program. If not, see <http://www.gnu.org/licenses/>. */
18 
19 #ifndef SERIAL_H
20 #define SERIAL_H
21 
22 #ifdef USE_WIN32API
23 #include <winsock2.h>
24 #include <windows.h>
25 #endif
26 
27 struct ui_file;
28 
29 /* For most routines, if a failure is indicated, then errno should be
30  examined. */
31 
32 /* Terminal state pointer. This is specific to each type of
33  interface. */
34 
35 typedef void *serial_ttystate;
36 struct serial;
37 
38 /* Try to open NAME. Returns a new `struct serial *' on success, NULL
39  on failure. The new serial object has a reference count of 1.
40  Note that some open calls can block and, if possible, should be
41  written to be non-blocking, with calls to ui_look_hook so they can
42  be cancelled. An async interface for open could be added to GDB if
43  necessary. */
44 
45 extern struct serial *serial_open (const char *name);
46 
47 /* Returns true if SCB is open. */
48 
49 extern int serial_is_open (struct serial *scb);
50 
51 /* Find an already opened serial stream using a file handle. */
52 
53 extern struct serial *serial_for_fd (int fd);
54 
55 /* Open a new serial stream using a file handle. */
56 
57 extern struct serial *serial_fdopen (const int fd);
58 
59 /* Push out all buffers, close the device and unref SCB. */
60 
61 extern void serial_close (struct serial *scb);
62 
63 /* Increment reference count of SCB. */
64 
65 extern void serial_ref (struct serial *scb);
66 
67 /* Decrement reference count of SCB. */
68 
69 extern void serial_unref (struct serial *scb);
70 
71 /* Create a pipe, and put the read end in files[0], and the write end
72  in filde[1]. Returns 0 for success, negative value for error (in
73  which case errno contains the error). */
74 
75 extern int gdb_pipe (int fildes[2]);
76 
77 /* Create a pipe with each end wrapped in a `struct serial' interface.
78  Put the read end in scbs[0], and the write end in scbs[1]. Returns
79  0 for success, negative value for error (in which case errno
80  contains the error). */
81 
82 extern int serial_pipe (struct serial *scbs[2]);
83 
84 /* Push out all buffers and destroy SCB without closing the device. */
85 
86 extern void serial_un_fdopen (struct serial *scb);
87 
88 /* Read one char from the serial device with TIMEOUT seconds to wait
89  or -1 to wait forever. Use timeout of 0 to effect a poll.
90  Infinite waits are not permitted. Returns unsigned char if ok, else
91  one of the following codes. Note that all error return-codes are
92  guaranteed to be < 0. */
93 
94 enum serial_rc {
95  SERIAL_ERROR = -1, /* General error. */
96  SERIAL_TIMEOUT = -2, /* Timeout or data-not-ready during read.
97  Unfortunately, through
98  deprecated_ui_loop_hook (), this can also
99  be a QUIT indication. */
100  SERIAL_EOF = -3 /* General end-of-file or remote target
101  connection closed, indication. Includes
102  things like the line dropping dead. */
103 };
104 
105 extern int serial_readchar (struct serial *scb, int timeout);
106 
107 /* Write COUNT bytes from BUF to the port SCB. Returns 0 for
108  success, non-zero for failure. */
109 
110 extern int serial_write (struct serial *scb, const void *buf, size_t count);
111 
112 /* Write a printf style string onto the serial port. */
113 
114 extern void serial_printf (struct serial *desc,
115  const char *,...) ATTRIBUTE_PRINTF (2, 3);
116 
117 /* Allow pending output to drain. */
118 
119 extern int serial_drain_output (struct serial *);
120 
121 /* Flush (discard) pending output. Might also flush input (if this
122  system can't flush only output). */
123 
124 extern int serial_flush_output (struct serial *);
125 
126 /* Flush pending input. Might also flush output (if this system can't
127  flush only input). */
128 
129 extern int serial_flush_input (struct serial *);
130 
131 /* Send a break between 0.25 and 0.5 seconds long. */
132 
133 extern int serial_send_break (struct serial *scb);
134 
135 /* Turn the port into raw mode. */
136 
137 extern void serial_raw (struct serial *scb);
138 
139 /* Return a pointer to a newly malloc'd ttystate containing the state
140  of the tty. */
141 
142 extern serial_ttystate serial_get_tty_state (struct serial *scb);
143 
144 /* Return a pointer to a newly malloc'd ttystate containing a copy
145  of the state in TTYSTATE. */
146 
147 extern serial_ttystate serial_copy_tty_state (struct serial *scb,
148  serial_ttystate ttystate);
149 
150 /* Set the state of the tty to TTYSTATE. The change is immediate.
151  When changing to or from raw mode, input might be discarded.
152  Returns 0 for success, negative value for error (in which case
153  errno contains the error). */
154 
155 extern int serial_set_tty_state (struct serial *scb, serial_ttystate ttystate);
156 
157 /* printf_filtered a user-comprehensible description of ttystate on
158  the specified STREAM. FIXME: At present this sends output to the
159  default stream - GDB_STDOUT. */
160 
161 extern void serial_print_tty_state (struct serial *scb,
162  serial_ttystate ttystate,
163  struct ui_file *);
164 
165 /* Set the tty state to NEW_TTYSTATE, where OLD_TTYSTATE is the
166  current state (generally obtained from a recent call to
167  serial_get_tty_state()), but be careful not to discard any input.
168  This means that we never switch in or out of raw mode, even if
169  NEW_TTYSTATE specifies a switch. */
170 
171 extern int serial_noflush_set_tty_state (struct serial *scb,
172  serial_ttystate new_ttystate,
173  serial_ttystate old_ttystate);
174 
175 /* Set the baudrate to the decimal value supplied. Returns 0 for
176  success, -1 for failure. */
177 
178 extern int serial_setbaudrate (struct serial *scb, int rate);
179 
180 /* Set the number of stop bits to the value specified. Returns 0 for
181  success, -1 for failure. */
182 
183 #define SERIAL_1_STOPBITS 1
184 #define SERIAL_1_AND_A_HALF_STOPBITS 2 /* 1.5 bits, snicker... */
185 #define SERIAL_2_STOPBITS 3
186 
187 extern int serial_setstopbits (struct serial *scb, int num);
188 
189 #define GDBPARITY_NONE 0
190 #define GDBPARITY_ODD 1
191 #define GDBPARITY_EVEN 2
192 
193 /* Set parity for serial port. Returns 0 for success, -1 for failure. */
194 
195 extern int serial_setparity (struct serial *scb, int parity);
196 
197 /* Asynchronous serial interface: */
198 
199 /* Can the serial device support asynchronous mode? */
200 
201 extern int serial_can_async_p (struct serial *scb);
202 
203 /* Has the serial device been put in asynchronous mode? */
204 
205 extern int serial_is_async_p (struct serial *scb);
206 
207 /* For ASYNC enabled devices, register a callback and enable
208  asynchronous mode. To disable asynchronous mode, register a NULL
209  callback. */
210 
211 typedef void (serial_event_ftype) (struct serial *scb, void *context);
212 extern void serial_async (struct serial *scb,
213  serial_event_ftype *handler, void *context);
214 
215 /* Trace/debug mechanism.
216 
217  serial_debug() enables/disables internal debugging.
218  serial_debug_p() indicates the current debug state. */
219 
220 extern void serial_debug (struct serial *scb, int debug_p);
221 
222 extern int serial_debug_p (struct serial *scb);
223 
224 
225 /* Details of an instance of a serial object. */
226 
227 struct serial
228  {
229  /* serial objects are ref counted (but not the underlying
230  connection, just the object's lifetime in memory). */
231  int refcnt;
232 
233  int fd; /* File descriptor */
234  /* File descriptor for a separate error stream that should be
235  immediately forwarded to gdb_stderr. This may be -1.
236  If != -1, this descriptor should be non-blocking or
237  ops->avail should be non-NULL. */
238  int error_fd;
239  const struct serial_ops *ops; /* Function vector */
240  void *state; /* Local context info for open FD */
241  serial_ttystate ttystate; /* Not used (yet) */
242  int bufcnt; /* Amount of data remaining in receive
243  buffer. -ve for sticky errors. */
244  unsigned char *bufp; /* Current byte */
245  unsigned char buf[BUFSIZ]; /* Da buffer itself */
246  int current_timeout; /* (ser-unix.c termio{,s} only), last
247  value of VTIME */
248  int timeout_remaining; /* (ser-unix.c termio{,s} only), we
249  still need to wait for this many
250  more seconds. */
251  char *name; /* The name of the device or host */
252  struct serial *next; /* Pointer to the next `struct serial *' */
253  int debug_p; /* Trace this serial devices operation. */
254  int async_state; /* Async internal state. */
255  void *async_context; /* Async event thread's context */
256  serial_event_ftype *async_handler;/* Async event handler */
257  };
258 
260  {
261  char *name;
262  int (*open) (struct serial *, const char *name);
263  void (*close) (struct serial *);
264  int (*fdopen) (struct serial *, int fd);
265  int (*readchar) (struct serial *, int timeout);
266  int (*write) (struct serial *, const void *buf, size_t count);
267  /* Discard pending output */
268  int (*flush_output) (struct serial *);
269  /* Discard pending input */
270  int (*flush_input) (struct serial *);
271  int (*send_break) (struct serial *);
272  void (*go_raw) (struct serial *);
273  serial_ttystate (*get_tty_state) (struct serial *);
275  int (*set_tty_state) (struct serial *, serial_ttystate);
276  void (*print_tty_state) (struct serial *, serial_ttystate,
277  struct ui_file *);
280  int (*setbaudrate) (struct serial *, int rate);
281  int (*setstopbits) (struct serial *, int num);
282  /* Set the value PARITY as parity setting for serial object.
283  Return 0 in the case of success. */
284  int (*setparity) (struct serial *, int parity);
285  /* Wait for output to drain. */
286  int (*drain_output) (struct serial *);
287  /* Change the serial device into/out of asynchronous mode, call
288  the specified function when ever there is something
289  interesting. */
290  void (*async) (struct serial *scb, int async_p);
291  /* Perform a low-level read operation, reading (at most) COUNT
292  bytes into SCB->BUF. Return zero at end of file. */
293  int (*read_prim)(struct serial *scb, size_t count);
294  /* Perform a low-level write operation, writing (at most) COUNT
295  bytes from BUF. */
296  int (*write_prim)(struct serial *scb, const void *buf, size_t count);
297  /* Return that number of bytes that can be read from FD
298  without blocking. Return value of -1 means that the
299  read will not block even if less that requested bytes
300  are available. */
301  int (*avail)(struct serial *scb, int fd);
302 
303 #ifdef USE_WIN32API
304  /* Return a handle to wait on, indicating available data from SCB
305  when signaled, in *READ. Return a handle indicating errors
306  in *EXCEPT. */
307  void (*wait_handle) (struct serial *scb, HANDLE *read, HANDLE *except);
308  void (*done_wait_handle) (struct serial *scb);
309 #endif /* USE_WIN32API */
310  };
311 
312 /* Add a new serial interface to the interface list. */
313 
314 extern void serial_add_interface (const struct serial_ops * optable);
315 
316 /* File in which to record the remote debugging session. */
317 
318 extern void serial_log_command (struct target_ops *self, const char *);
319 
320 #ifdef USE_WIN32API
321 
322 /* Windows-only: find or create handles that we can wait on for this
323  serial device. */
324 extern void serial_wait_handle (struct serial *, HANDLE *, HANDLE *);
325 
326 /* Windows-only: signal that we are done with the wait handles. */
327 extern void serial_done_wait_handle (struct serial *);
328 
329 #endif /* USE_WIN32API */
330 
331 #endif /* SERIAL_H */
ssize_t read(int fd, void *buf, size_t count)
Definition: expect-read1.c:26
void serial_un_fdopen(struct serial *scb)
Definition: serial.c:346
int timeout_remaining
Definition: serial.h:248
serial_event_ftype * async_handler
Definition: serial.h:256
int current_timeout
Definition: serial.h:246
int(* flush_output)(struct serial *)
Definition: serial.h:268
void serial_add_interface(const struct serial_ops *optable)
Definition: serial.c:162
void serial_print_tty_state(struct serial *scb, serial_ttystate ttystate, struct ui_file *)
Definition: serial.c:500
void serial_raw(struct serial *scb)
Definition: serial.c:476
void(* print_tty_state)(struct serial *, serial_ttystate, struct ui_file *)
Definition: serial.h:276
serial_ttystate(* copy_tty_state)(struct serial *, serial_ttystate)
Definition: serial.h:274
void serial_async(struct serial *scb, serial_event_ftype *handler, void *context)
Definition: serial.c:548
int async_state
Definition: serial.h:254
int(* flush_input)(struct serial *)
Definition: serial.h:270
serial_ttystate serial_get_tty_state(struct serial *scb)
Definition: serial.c:482
int error_fd
Definition: serial.h:238
int(* send_break)(struct serial *)
Definition: serial.h:271
int serial_setparity(struct serial *scb, int parity)
Definition: serial.c:530
struct serial * next
Definition: serial.h:252
int serial_pipe(struct serial *scbs[2])
Definition: serial.c:595
serial_ttystate serial_copy_tty_state(struct serial *scb, serial_ttystate ttystate)
Definition: serial.c:488
void serial_printf(struct serial *desc, const char *,...) ATTRIBUTE_PRINTF(2
int(* read_prim)(struct serial *scb, size_t count)
Definition: serial.h:293
void * async_context
Definition: serial.h:255
int(* fdopen)(struct serial *, int fd)
Definition: serial.h:264
int serial_setstopbits(struct serial *scb, int num)
Definition: serial.c:522
unsigned char * bufp
Definition: serial.h:244
static int timeout
Definition: monitor.c:75
struct serial * serial_for_fd(int fd)
Definition: serial.c:171
const char *const name
Definition: aarch64-tdep.c:68
int(* readchar)(struct serial *, int timeout)
Definition: serial.h:265
int refcnt
Definition: serial.h:231
void serial_ref(struct serial *scb)
Definition: serial.c:358
int serial_debug_p(struct serial *scb)
Definition: serial.c:568
void serial_unref(struct serial *scb)
Definition: serial.c:364
int serial_flush_input(struct serial *)
Definition: serial.c:461
int serial_can_async_p(struct serial *scb)
Definition: serial.c:536
int(* write_prim)(struct serial *scb, const void *buf, size_t count)
Definition: serial.h:296
int(* write)(struct serial *, const void *buf, size_t count)
Definition: serial.h:266
static const char * parity
Definition: serial.c:658
int(* setstopbits)(struct serial *, int num)
Definition: serial.h:281
unsigned char buf[BUFSIZ]
Definition: serial.h:245
int(* open)(struct serial *, const char *name)
Definition: serial.h:262
struct serial * serial_fdopen(const int fd)
Definition: serial.c:291
void(* close)(struct serial *)
Definition: serial.h:263
char * name
Definition: serial.h:261
serial_rc
Definition: serial.h:94
int(* set_tty_state)(struct serial *, serial_ttystate)
Definition: serial.h:275
int(* setparity)(struct serial *, int parity)
Definition: serial.h:284
serial_ttystate ttystate
Definition: serial.h:241
serial_ttystate(* get_tty_state)(struct serial *)
Definition: serial.h:273
const char const char int
Definition: command.h:229
int serial_readchar(struct serial *scb, int timeout)
Definition: serial.c:372
struct serial * serial_open(const char *name)
Definition: serial.c:185
int serial_setbaudrate(struct serial *scb, int rate)
Definition: serial.c:516
int(* avail)(struct serial *scb, int fd)
Definition: serial.h:301
int serial_send_break(struct serial *scb)
Definition: serial.c:467
void( serial_event_ftype)(struct serial *scb, void *context)
Definition: serial.h:211
void serial_close(struct serial *scb)
Definition: serial.c:340
int fd
Definition: serial.h:233
void(* async)(struct serial *scb, int async_p)
Definition: serial.h:290
int bufcnt
Definition: serial.h:242
int serial_noflush_set_tty_state(struct serial *scb, serial_ttystate new_ttystate, serial_ttystate old_ttystate)
Definition: serial.c:508
int serial_is_async_p(struct serial *scb)
Definition: serial.c:542
void serial_log_command(struct target_ops *self, const char *)
Definition: serial.c:132
static void ATTRIBUTE_PRINTF(6, 0)
Definition: cli-out.c:229
void serial_debug(struct serial *scb, int debug_p)
Definition: serial.c:562
int(* noflush_set_tty_state)(struct serial *, serial_ttystate, serial_ttystate)
Definition: serial.h:278
void * serial_ttystate
Definition: serial.h:27
int serial_flush_output(struct serial *)
Definition: serial.c:455
int debug_p
Definition: serial.h:253
void(* go_raw)(struct serial *)
Definition: serial.h:272
int serial_set_tty_state(struct serial *scb, serial_ttystate ttystate)
Definition: serial.c:494
int(* setbaudrate)(struct serial *, int rate)
Definition: serial.h:280
int(* drain_output)(struct serial *)
Definition: serial.h:286
void * state
Definition: serial.h:240
const struct serial_ops * ops
Definition: serial.h:239
int serial_is_open(struct serial *scb)
Definition: serial.c:352
int gdb_pipe(int fildes[2])
Definition: ser-go32.c:873
int serial_write(struct serial *scb, const void *buf, size_t count)
Definition: serial.c:403
char * name
Definition: serial.h:251
void int serial_drain_output(struct serial *)
Definition: serial.c:449
int rate
Definition: ser-unix.c:683