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