1e93f7393Sniklas /* Remote serial support interface definitions for GDB, the GNU Debugger. 2b725ae77Skettenis Copyright 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000 3b725ae77Skettenis Free Software Foundation, Inc. 4e93f7393Sniklas 5e93f7393Sniklas This file is part of GDB. 6e93f7393Sniklas 7e93f7393Sniklas This program is free software; you can redistribute it and/or modify 8e93f7393Sniklas it under the terms of the GNU General Public License as published by 9e93f7393Sniklas the Free Software Foundation; either version 2 of the License, or 10e93f7393Sniklas (at your option) any later version. 11e93f7393Sniklas 12e93f7393Sniklas This program is distributed in the hope that it will be useful, 13e93f7393Sniklas but WITHOUT ANY WARRANTY; without even the implied warranty of 14e93f7393Sniklas MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15e93f7393Sniklas GNU General Public License for more details. 16e93f7393Sniklas 17e93f7393Sniklas You should have received a copy of the GNU General Public License 18e93f7393Sniklas along with this program; if not, write to the Free Software 19b725ae77Skettenis Foundation, Inc., 59 Temple Place - Suite 330, 20b725ae77Skettenis Boston, MA 02111-1307, USA. */ 21e93f7393Sniklas 22e93f7393Sniklas #ifndef SERIAL_H 23e93f7393Sniklas #define SERIAL_H 24e93f7393Sniklas 25b725ae77Skettenis struct ui_file; 26e93f7393Sniklas 27e93f7393Sniklas /* For most routines, if a failure is indicated, then errno should be 28e93f7393Sniklas examined. */ 29e93f7393Sniklas 30b725ae77Skettenis /* Terminal state pointer. This is specific to each type of 31b725ae77Skettenis interface. */ 32e93f7393Sniklas 33b725ae77Skettenis typedef void *serial_ttystate; 34b725ae77Skettenis struct serial; 35b725ae77Skettenis 36b725ae77Skettenis /* Try to open NAME. Returns a new `struct serial *' on success, NULL 37b725ae77Skettenis on failure. Note that some open calls can block and, if possible, 38b725ae77Skettenis should be written to be non-blocking, with calls to ui_look_hook 39b725ae77Skettenis so they can be cancelled. An async interface for open could be 40b725ae77Skettenis added to GDB if necessary. */ 41b725ae77Skettenis 42b725ae77Skettenis extern struct serial *serial_open (const char *name); 43e93f7393Sniklas 44e93f7393Sniklas /* Open a new serial stream using a file handle. */ 45e93f7393Sniklas 46b725ae77Skettenis extern struct serial *serial_fdopen (const int fd); 47e93f7393Sniklas 48b725ae77Skettenis /* Push out all buffers, close the device and destroy SCB. */ 49e93f7393Sniklas 50b725ae77Skettenis extern void serial_close (struct serial *scb); 51e93f7393Sniklas 52b725ae77Skettenis /* Push out all buffers and destroy SCB without closing the device. */ 53e93f7393Sniklas 54b725ae77Skettenis extern void serial_un_fdopen (struct serial *scb); 55b725ae77Skettenis 56b725ae77Skettenis /* Read one char from the serial device with TIMEOUT seconds to wait 57b725ae77Skettenis or -1 to wait forever. Use timeout of 0 to effect a poll. 58b725ae77Skettenis Infinite waits are not permitted. Returns unsigned char if ok, else 59b725ae77Skettenis one of the following codes. Note that all error return-codes are 60b725ae77Skettenis guaranteed to be < 0. */ 61b725ae77Skettenis 62b725ae77Skettenis enum serial_rc { 63b725ae77Skettenis SERIAL_ERROR = -1, /* General error. */ 64b725ae77Skettenis SERIAL_TIMEOUT = -2, /* Timeout or data-not-ready during read. 65*63addd46Skettenis Unfortunately, through 66*63addd46Skettenis deprecated_ui_loop_hook(), this can also be 67*63addd46Skettenis a QUIT indication. */ 68b725ae77Skettenis SERIAL_EOF = -3 /* General end-of-file or remote target 69b725ae77Skettenis connection closed, indication. Includes 70b725ae77Skettenis things like the line dropping dead. */ 71b725ae77Skettenis }; 72b725ae77Skettenis 73b725ae77Skettenis extern int serial_readchar (struct serial *scb, int timeout); 74b725ae77Skettenis 75b725ae77Skettenis /* Write LEN chars from STRING to the port SCB. Returns 0 for 76b725ae77Skettenis success, non-zero for failure. */ 77b725ae77Skettenis 78b725ae77Skettenis extern int serial_write (struct serial *scb, const char *str, int len); 79b725ae77Skettenis 80b725ae77Skettenis /* Write a printf style string onto the serial port. */ 81b725ae77Skettenis 82b725ae77Skettenis extern void serial_printf (struct serial *desc, const char *,...) ATTR_FORMAT (printf, 2, 3); 83b725ae77Skettenis 84b725ae77Skettenis /* Allow pending output to drain. */ 85b725ae77Skettenis 86b725ae77Skettenis extern int serial_drain_output (struct serial *); 87b725ae77Skettenis 88b725ae77Skettenis /* Flush (discard) pending output. Might also flush input (if this 89b725ae77Skettenis system can't flush only output). */ 90b725ae77Skettenis 91b725ae77Skettenis extern int serial_flush_output (struct serial *); 92b725ae77Skettenis 93b725ae77Skettenis /* Flush pending input. Might also flush output (if this system can't 94b725ae77Skettenis flush only input). */ 95b725ae77Skettenis 96b725ae77Skettenis extern int serial_flush_input (struct serial *); 97e93f7393Sniklas 98e93f7393Sniklas /* Send a break between 0.25 and 0.5 seconds long. */ 99e93f7393Sniklas 100b725ae77Skettenis extern int serial_send_break (struct serial *scb); 101e93f7393Sniklas 102e93f7393Sniklas /* Turn the port into raw mode. */ 103e93f7393Sniklas 104b725ae77Skettenis extern void serial_raw (struct serial *scb); 105e93f7393Sniklas 106e93f7393Sniklas /* Return a pointer to a newly malloc'd ttystate containing the state 107e93f7393Sniklas of the tty. */ 108b725ae77Skettenis 109b725ae77Skettenis extern serial_ttystate serial_get_tty_state (struct serial *scb); 110e93f7393Sniklas 111e93f7393Sniklas /* Set the state of the tty to TTYSTATE. The change is immediate. 112e93f7393Sniklas When changing to or from raw mode, input might be discarded. 113b725ae77Skettenis Returns 0 for success, negative value for error (in which case 114b725ae77Skettenis errno contains the error). */ 115e93f7393Sniklas 116b725ae77Skettenis extern int serial_set_tty_state (struct serial *scb, serial_ttystate ttystate); 117b725ae77Skettenis 118b725ae77Skettenis /* printf_filtered a user-comprehensible description of ttystate on 119b725ae77Skettenis the specified STREAM. FIXME: At present this sends output to the 120b725ae77Skettenis default stream - GDB_STDOUT. */ 121b725ae77Skettenis 122b725ae77Skettenis extern void serial_print_tty_state (struct serial *scb, serial_ttystate ttystate, struct ui_file *); 123e93f7393Sniklas 124e93f7393Sniklas /* Set the tty state to NEW_TTYSTATE, where OLD_TTYSTATE is the 125e93f7393Sniklas current state (generally obtained from a recent call to 126b725ae77Skettenis serial_get_tty_state()), but be careful not to discard any input. 127b725ae77Skettenis This means that we never switch in or out of raw mode, even if 128b725ae77Skettenis NEW_TTYSTATE specifies a switch. */ 129e93f7393Sniklas 130b725ae77Skettenis extern int serial_noflush_set_tty_state (struct serial *scb, serial_ttystate new_ttystate, serial_ttystate old_ttystate); 131e93f7393Sniklas 132b725ae77Skettenis /* Set the baudrate to the decimal value supplied. Returns 0 for 133b725ae77Skettenis success, -1 for failure. */ 134e93f7393Sniklas 135b725ae77Skettenis extern int serial_setbaudrate (struct serial *scb, int rate); 136e93f7393Sniklas 137b725ae77Skettenis /* Set the number of stop bits to the value specified. Returns 0 for 138b725ae77Skettenis success, -1 for failure. */ 139e93f7393Sniklas 140e93f7393Sniklas #define SERIAL_1_STOPBITS 1 141e93f7393Sniklas #define SERIAL_1_AND_A_HALF_STOPBITS 2 /* 1.5 bits, snicker... */ 142e93f7393Sniklas #define SERIAL_2_STOPBITS 3 143e93f7393Sniklas 144b725ae77Skettenis extern int serial_setstopbits (struct serial *scb, int num); 145e93f7393Sniklas 146b725ae77Skettenis /* Asynchronous serial interface: */ 147e93f7393Sniklas 148b725ae77Skettenis /* Can the serial device support asynchronous mode? */ 149e93f7393Sniklas 150b725ae77Skettenis extern int serial_can_async_p (struct serial *scb); 151e93f7393Sniklas 152b725ae77Skettenis /* Has the serial device been put in asynchronous mode? */ 153e93f7393Sniklas 154b725ae77Skettenis extern int serial_is_async_p (struct serial *scb); 155e93f7393Sniklas 156b725ae77Skettenis /* For ASYNC enabled devices, register a callback and enable 157b725ae77Skettenis asynchronous mode. To disable asynchronous mode, register a NULL 158b725ae77Skettenis callback. */ 159e93f7393Sniklas 160b725ae77Skettenis typedef void (serial_event_ftype) (struct serial *scb, void *context); 161b725ae77Skettenis extern void serial_async (struct serial *scb, serial_event_ftype *handler, void *context); 162e93f7393Sniklas 163b725ae77Skettenis /* Provide direct access to the underlying FD (if any) used to 164b725ae77Skettenis implement the serial device. This interface is clearly 165b725ae77Skettenis deprecated. Will call internal_error() if the operation isn't 166b725ae77Skettenis applicable to the current serial device. */ 167e93f7393Sniklas 168b725ae77Skettenis extern int deprecated_serial_fd (struct serial *scb); 169b725ae77Skettenis 170b725ae77Skettenis /* Trace/debug mechanism. 171b725ae77Skettenis 172b725ae77Skettenis serial_debug() enables/disables internal debugging. 173b725ae77Skettenis serial_debug_p() indicates the current debug state. */ 174b725ae77Skettenis 175b725ae77Skettenis extern void serial_debug (struct serial *scb, int debug_p); 176b725ae77Skettenis 177b725ae77Skettenis extern int serial_debug_p (struct serial *scb); 178b725ae77Skettenis 179b725ae77Skettenis 180b725ae77Skettenis /* Details of an instance of a serial object */ 181b725ae77Skettenis 182b725ae77Skettenis struct serial 183b725ae77Skettenis { 184b725ae77Skettenis int fd; /* File descriptor */ 185b725ae77Skettenis struct serial_ops *ops; /* Function vector */ 186b725ae77Skettenis void *state; /* Local context info for open FD */ 187b725ae77Skettenis serial_ttystate ttystate; /* Not used (yet) */ 188b725ae77Skettenis int bufcnt; /* Amount of data remaining in receive 189b725ae77Skettenis buffer. -ve for sticky errors. */ 190b725ae77Skettenis unsigned char *bufp; /* Current byte */ 191b725ae77Skettenis unsigned char buf[BUFSIZ]; /* Da buffer itself */ 192b725ae77Skettenis int current_timeout; /* (ser-unix.c termio{,s} only), last 193b725ae77Skettenis value of VTIME */ 194b725ae77Skettenis int timeout_remaining; /* (ser-unix.c termio{,s} only), we 195b725ae77Skettenis still need to wait for this many 196b725ae77Skettenis more seconds. */ 197b725ae77Skettenis char *name; /* The name of the device or host */ 198b725ae77Skettenis struct serial *next; /* Pointer to the next `struct serial *' */ 199b725ae77Skettenis int refcnt; /* Number of pointers to this block */ 200b725ae77Skettenis int debug_p; /* Trace this serial devices operation. */ 201b725ae77Skettenis int async_state; /* Async internal state. */ 202b725ae77Skettenis void *async_context; /* Async event thread's context */ 203b725ae77Skettenis serial_event_ftype *async_handler;/* Async event handler */ 204b725ae77Skettenis }; 205b725ae77Skettenis 206b725ae77Skettenis struct serial_ops 207b725ae77Skettenis { 208b725ae77Skettenis char *name; 209b725ae77Skettenis struct serial_ops *next; 210b725ae77Skettenis int (*open) (struct serial *, const char *name); 211b725ae77Skettenis void (*close) (struct serial *); 212b725ae77Skettenis int (*readchar) (struct serial *, int timeout); 213b725ae77Skettenis int (*write) (struct serial *, const char *str, int len); 214b725ae77Skettenis /* Discard pending output */ 215b725ae77Skettenis int (*flush_output) (struct serial *); 216b725ae77Skettenis /* Discard pending input */ 217b725ae77Skettenis int (*flush_input) (struct serial *); 218b725ae77Skettenis int (*send_break) (struct serial *); 219b725ae77Skettenis void (*go_raw) (struct serial *); 220b725ae77Skettenis serial_ttystate (*get_tty_state) (struct serial *); 221b725ae77Skettenis int (*set_tty_state) (struct serial *, serial_ttystate); 222b725ae77Skettenis void (*print_tty_state) (struct serial *, serial_ttystate, 223b725ae77Skettenis struct ui_file *); 224b725ae77Skettenis int (*noflush_set_tty_state) (struct serial *, serial_ttystate, 225b725ae77Skettenis serial_ttystate); 226b725ae77Skettenis int (*setbaudrate) (struct serial *, int rate); 227b725ae77Skettenis int (*setstopbits) (struct serial *, int num); 228b725ae77Skettenis /* Wait for output to drain */ 229b725ae77Skettenis int (*drain_output) (struct serial *); 230b725ae77Skettenis /* Change the serial device into/out of asynchronous mode, call 231b725ae77Skettenis the specified function when ever there is something 232b725ae77Skettenis interesting. */ 233b725ae77Skettenis void (*async) (struct serial *scb, int async_p); 234b725ae77Skettenis }; 235b725ae77Skettenis 236b725ae77Skettenis /* Add a new serial interface to the interface list */ 237b725ae77Skettenis 238b725ae77Skettenis extern void serial_add_interface (struct serial_ops * optable); 239e93f7393Sniklas 240e93f7393Sniklas /* File in which to record the remote debugging session */ 241e93f7393Sniklas 242b725ae77Skettenis extern void serial_log_command (const char *); 243e93f7393Sniklas 244e93f7393Sniklas #endif /* SERIAL_H */ 245