]> git.ipfire.org Git - thirdparty/binutils-gdb.git/blame - gdb/serial.h
Copyright updates for 2007.
[thirdparty/binutils-gdb.git] / gdb / serial.h
CommitLineData
c906108c 1/* Remote serial support interface definitions for GDB, the GNU Debugger.
6aba47ca
DJ
2 Copyright (C) 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, 2004,
3 2005, 2006, 2007 Free Software Foundation, Inc.
c906108c 4
c5aa993b 5 This file is part of GDB.
c906108c 6
c5aa993b
JM
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.
c906108c 11
c5aa993b
JM
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.
c906108c 16
c5aa993b
JM
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
197e01b6
EZ
19 Foundation, Inc., 51 Franklin Street, Fifth Floor,
20 Boston, MA 02110-1301, USA. */
c906108c
SS
21
22#ifndef SERIAL_H
23#define SERIAL_H
24
0ea3f30e
DJ
25#ifdef USE_WIN32API
26#include <windows.h>
27#endif
28
da3331ec
AC
29struct ui_file;
30
c2c6d25f
JM
31/* For most routines, if a failure is indicated, then errno should be
32 examined. */
c906108c 33
c2c6d25f 34/* Terminal state pointer. This is specific to each type of
2c1ab592 35 interface. */
c906108c 36
c2c6d25f 37typedef void *serial_ttystate;
65e2f740 38struct serial;
c906108c 39
819cc324 40/* Try to open NAME. Returns a new `struct serial *' on success, NULL
63b5bc2f
MH
41 on failure. Note that some open calls can block and, if possible,
42 should be written to be non-blocking, with calls to ui_look_hook
43 so they can be cancelled. An async interface for open could be
2c1ab592 44 added to GDB if necessary. */
c906108c 45
819cc324 46extern struct serial *serial_open (const char *name);
c906108c 47
0ea3f30e
DJ
48/* Find an already opened serial stream using a file handle. */
49
50extern struct serial *serial_for_fd (int fd);
51
c2c6d25f 52/* Open a new serial stream using a file handle. */
c906108c 53
819cc324 54extern struct serial *serial_fdopen (const int fd);
c906108c 55
2c1ab592 56/* Push out all buffers, close the device and destroy SCB. */
c906108c 57
819cc324 58extern void serial_close (struct serial *scb);
c906108c 59
819cc324 60/* Push out all buffers and destroy SCB without closing the device. */
c906108c 61
819cc324 62extern void serial_un_fdopen (struct serial *scb);
c906108c 63
c2c6d25f 64/* Read one char from the serial device with TIMEOUT seconds to wait
2df3850c
JM
65 or -1 to wait forever. Use timeout of 0 to effect a poll.
66 Infinite waits are not permitted. Returns unsigned char if ok, else
67 one of the following codes. Note that all error return-codes are
2c1ab592 68 guaranteed to be < 0. */
2acceee2
JM
69
70enum serial_rc {
2c1ab592 71 SERIAL_ERROR = -1, /* General error. */
2df3850c 72 SERIAL_TIMEOUT = -2, /* Timeout or data-not-ready during read.
98bbd631 73 Unfortunately, through
2c1ab592
MS
74 deprecated_ui_loop_hook (), this can also
75 be a QUIT indication. */
2acceee2
JM
76 SERIAL_EOF = -3 /* General end-of-file or remote target
77 connection closed, indication. Includes
2c1ab592 78 things like the line dropping dead. */
2acceee2 79};
c2c6d25f 80
819cc324 81extern int serial_readchar (struct serial *scb, int timeout);
c2c6d25f 82
819cc324 83/* Write LEN chars from STRING to the port SCB. Returns 0 for
c2c6d25f
JM
84 success, non-zero for failure. */
85
819cc324 86extern int serial_write (struct serial *scb, const char *str, int len);
c2c6d25f 87
2c1ab592 88/* Write a printf style string onto the serial port. */
c2c6d25f 89
2c1ab592
MS
90extern void serial_printf (struct serial *desc,
91 const char *,...) ATTR_FORMAT (printf, 2, 3);
c906108c 92
2c1ab592 93/* Allow pending output to drain. */
c906108c 94
819cc324 95extern int serial_drain_output (struct serial *);
c5aa993b 96
c2c6d25f
JM
97/* Flush (discard) pending output. Might also flush input (if this
98 system can't flush only output). */
c906108c 99
819cc324 100extern int serial_flush_output (struct serial *);
c906108c 101
c2c6d25f
JM
102/* Flush pending input. Might also flush output (if this system can't
103 flush only input). */
c906108c 104
819cc324 105extern int serial_flush_input (struct serial *);
c906108c
SS
106
107/* Send a break between 0.25 and 0.5 seconds long. */
108
819cc324 109extern int serial_send_break (struct serial *scb);
c906108c 110
2c1ab592 111/* Turn the port into raw mode. */
c906108c 112
819cc324 113extern void serial_raw (struct serial *scb);
c906108c
SS
114
115/* Return a pointer to a newly malloc'd ttystate containing the state
116 of the tty. */
c2c6d25f 117
819cc324 118extern serial_ttystate serial_get_tty_state (struct serial *scb);
c906108c
SS
119
120/* Set the state of the tty to TTYSTATE. The change is immediate.
121 When changing to or from raw mode, input might be discarded.
c2c6d25f
JM
122 Returns 0 for success, negative value for error (in which case
123 errno contains the error). */
124
819cc324 125extern int serial_set_tty_state (struct serial *scb, serial_ttystate ttystate);
c906108c 126
c2c6d25f
JM
127/* printf_filtered a user-comprehensible description of ttystate on
128 the specified STREAM. FIXME: At present this sends output to the
2c1ab592 129 default stream - GDB_STDOUT. */
c2c6d25f 130
819cc324 131extern void serial_print_tty_state (struct serial *scb, serial_ttystate ttystate, struct ui_file *);
c906108c
SS
132
133/* Set the tty state to NEW_TTYSTATE, where OLD_TTYSTATE is the
134 current state (generally obtained from a recent call to
2cd58942 135 serial_get_tty_state()), but be careful not to discard any input.
c2c6d25f
JM
136 This means that we never switch in or out of raw mode, even if
137 NEW_TTYSTATE specifies a switch. */
138
819cc324 139extern int serial_noflush_set_tty_state (struct serial *scb, serial_ttystate new_ttystate, serial_ttystate old_ttystate);
c906108c 140
c2c6d25f
JM
141/* Set the baudrate to the decimal value supplied. Returns 0 for
142 success, -1 for failure. */
c906108c 143
819cc324 144extern int serial_setbaudrate (struct serial *scb, int rate);
c906108c 145
c2c6d25f
JM
146/* Set the number of stop bits to the value specified. Returns 0 for
147 success, -1 for failure. */
c906108c 148
c2c6d25f 149#define SERIAL_1_STOPBITS 1
2c1ab592 150#define SERIAL_1_AND_A_HALF_STOPBITS 2 /* 1.5 bits, snicker... */
c2c6d25f 151#define SERIAL_2_STOPBITS 3
c906108c 152
819cc324 153extern int serial_setstopbits (struct serial *scb, int num);
c906108c 154
c2c6d25f 155/* Asynchronous serial interface: */
c906108c 156
c2c6d25f 157/* Can the serial device support asynchronous mode? */
c906108c 158
819cc324 159extern int serial_can_async_p (struct serial *scb);
c906108c 160
c2c6d25f 161/* Has the serial device been put in asynchronous mode? */
c906108c 162
819cc324 163extern int serial_is_async_p (struct serial *scb);
c906108c 164
c2c6d25f
JM
165/* For ASYNC enabled devices, register a callback and enable
166 asynchronous mode. To disable asynchronous mode, register a NULL
2c1ab592 167 callback. */
c906108c 168
819cc324
AC
169typedef void (serial_event_ftype) (struct serial *scb, void *context);
170extern void serial_async (struct serial *scb, serial_event_ftype *handler, void *context);
c906108c 171
c2c6d25f
JM
172/* Provide direct access to the underlying FD (if any) used to
173 implement the serial device. This interface is clearly
174 deprecated. Will call internal_error() if the operation isn't
2c1ab592 175 applicable to the current serial device. */
c906108c 176
819cc324 177extern int deprecated_serial_fd (struct serial *scb);
c906108c 178
2acceee2
JM
179/* Trace/debug mechanism.
180
2cd58942 181 serial_debug() enables/disables internal debugging.
2c1ab592 182 serial_debug_p() indicates the current debug state. */
2acceee2 183
819cc324 184extern void serial_debug (struct serial *scb, int debug_p);
2acceee2 185
819cc324 186extern int serial_debug_p (struct serial *scb);
2acceee2 187
c906108c 188
c2c6d25f 189/* Details of an instance of a serial object */
c906108c 190
65e2f740 191struct serial
c2c6d25f
JM
192 {
193 int fd; /* File descriptor */
194 struct serial_ops *ops; /* Function vector */
195 void *state; /* Local context info for open FD */
196 serial_ttystate ttystate; /* Not used (yet) */
2acceee2 197 int bufcnt; /* Amount of data remaining in receive
2c1ab592 198 buffer. -ve for sticky errors. */
c2c6d25f
JM
199 unsigned char *bufp; /* Current byte */
200 unsigned char buf[BUFSIZ]; /* Da buffer itself */
2acceee2
JM
201 int current_timeout; /* (ser-unix.c termio{,s} only), last
202 value of VTIME */
203 int timeout_remaining; /* (ser-unix.c termio{,s} only), we
204 still need to wait for this many
205 more seconds. */
c2c6d25f 206 char *name; /* The name of the device or host */
819cc324 207 struct serial *next; /* Pointer to the next `struct serial *' */
c2c6d25f 208 int refcnt; /* Number of pointers to this block */
2c1ab592
MS
209 int debug_p; /* Trace this serial devices operation. */
210 int async_state; /* Async internal state. */
c2c6d25f
JM
211 void *async_context; /* Async event thread's context */
212 serial_event_ftype *async_handler;/* Async event handler */
213 };
214
215struct serial_ops
216 {
217 char *name;
218 struct serial_ops *next;
819cc324
AC
219 int (*open) (struct serial *, const char *name);
220 void (*close) (struct serial *);
221 int (*readchar) (struct serial *, int timeout);
222 int (*write) (struct serial *, const char *str, int len);
c2c6d25f 223 /* Discard pending output */
819cc324 224 int (*flush_output) (struct serial *);
c2c6d25f 225 /* Discard pending input */
819cc324
AC
226 int (*flush_input) (struct serial *);
227 int (*send_break) (struct serial *);
228 void (*go_raw) (struct serial *);
229 serial_ttystate (*get_tty_state) (struct serial *);
230 int (*set_tty_state) (struct serial *, serial_ttystate);
231 void (*print_tty_state) (struct serial *, serial_ttystate,
232 struct ui_file *);
233 int (*noflush_set_tty_state) (struct serial *, serial_ttystate,
234 serial_ttystate);
235 int (*setbaudrate) (struct serial *, int rate);
236 int (*setstopbits) (struct serial *, int num);
c2c6d25f 237 /* Wait for output to drain */
819cc324 238 int (*drain_output) (struct serial *);
c2c6d25f
JM
239 /* Change the serial device into/out of asynchronous mode, call
240 the specified function when ever there is something
2c1ab592 241 interesting. */
819cc324 242 void (*async) (struct serial *scb, int async_p);
b4505029
MM
243 /* Perform a low-level read operation, reading (at most) COUNT
244 bytes into SCB->BUF. */
245 int (*read_prim)(struct serial *scb, size_t count);
246 /* Perform a low-level write operation, writing (at most) COUNT
247 bytes from BUF. */
248 int (*write_prim)(struct serial *scb, const void *buf, size_t count);
0ea3f30e
DJ
249
250#ifdef USE_WIN32API
251 /* Return a handle to wait on, indicating available data from SCB
252 when signaled, in *READ. Return a handle indicating errors
253 in *EXCEPT. */
254 void (*wait_handle) (struct serial *scb, HANDLE *read, HANDLE *except);
c3e2b812 255 void (*done_wait_handle) (struct serial *scb);
0ea3f30e 256#endif /* USE_WIN32API */
c2c6d25f
JM
257 };
258
259/* Add a new serial interface to the interface list */
c906108c 260
c2c6d25f 261extern void serial_add_interface (struct serial_ops * optable);
c906108c
SS
262
263/* File in which to record the remote debugging session */
264
c2c6d25f 265extern void serial_log_command (const char *);
c906108c 266
0ea3f30e
DJ
267#ifdef USE_WIN32API
268
269/* Windows-only: find or create handles that we can wait on for this
270 serial device. */
271extern void serial_wait_handle (struct serial *, HANDLE *, HANDLE *);
272
c3e2b812
DJ
273/* Windows-only: signal that we are done with the wait handles. */
274extern void serial_done_wait_handle (struct serial *);
275
0ea3f30e
DJ
276#endif /* USE_WIN32API */
277
c906108c 278#endif /* SERIAL_H */