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