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 ui_loop_hook(), this
66			   can also be a QUIT indication.  */
67  SERIAL_EOF = -3	/* General end-of-file or remote target
68			   connection closed, indication.  Includes
69			   things like the line dropping dead. */
70};
71
72extern int serial_readchar (struct serial *scb, int timeout);
73
74/* Write LEN chars from STRING to the port SCB.  Returns 0 for
75   success, non-zero for failure.  */
76
77extern int serial_write (struct serial *scb, const char *str, int len);
78
79/* Write a printf style string onto the serial port. */
80
81extern void serial_printf (struct serial *desc, const char *,...) ATTR_FORMAT (printf, 2, 3);
82
83/* Allow pending output to drain. */
84
85extern int serial_drain_output (struct serial *);
86
87/* Flush (discard) pending output.  Might also flush input (if this
88   system can't flush only output).  */
89
90extern int serial_flush_output (struct serial *);
91
92/* Flush pending input.  Might also flush output (if this system can't
93   flush only input).  */
94
95extern int serial_flush_input (struct serial *);
96
97/* Send a break between 0.25 and 0.5 seconds long.  */
98
99extern int serial_send_break (struct serial *scb);
100
101/* Turn the port into raw mode. */
102
103extern void serial_raw (struct serial *scb);
104
105/* Return a pointer to a newly malloc'd ttystate containing the state
106   of the tty.  */
107
108extern serial_ttystate serial_get_tty_state (struct serial *scb);
109
110/* Set the state of the tty to TTYSTATE.  The change is immediate.
111   When changing to or from raw mode, input might be discarded.
112   Returns 0 for success, negative value for error (in which case
113   errno contains the error).  */
114
115extern int serial_set_tty_state (struct serial *scb, serial_ttystate ttystate);
116
117/* printf_filtered a user-comprehensible description of ttystate on
118   the specified STREAM. FIXME: At present this sends output to the
119   default stream - GDB_STDOUT. */
120
121extern void serial_print_tty_state (struct serial *scb, serial_ttystate ttystate, struct ui_file *);
122
123/* Set the tty state to NEW_TTYSTATE, where OLD_TTYSTATE is the
124   current state (generally obtained from a recent call to
125   serial_get_tty_state()), but be careful not to discard any input.
126   This means that we never switch in or out of raw mode, even if
127   NEW_TTYSTATE specifies a switch.  */
128
129extern int serial_noflush_set_tty_state (struct serial *scb, serial_ttystate new_ttystate, serial_ttystate old_ttystate);
130
131/* Set the baudrate to the decimal value supplied.  Returns 0 for
132   success, -1 for failure.  */
133
134extern int serial_setbaudrate (struct serial *scb, int rate);
135
136/* Set the number of stop bits to the value specified.  Returns 0 for
137   success, -1 for failure.  */
138
139#define SERIAL_1_STOPBITS 1
140#define SERIAL_1_AND_A_HALF_STOPBITS 2	/* 1.5 bits, snicker... */
141#define SERIAL_2_STOPBITS 3
142
143extern int serial_setstopbits (struct serial *scb, int num);
144
145/* Asynchronous serial interface: */
146
147/* Can the serial device support asynchronous mode? */
148
149extern int serial_can_async_p (struct serial *scb);
150
151/* Has the serial device been put in asynchronous mode? */
152
153extern int serial_is_async_p (struct serial *scb);
154
155/* For ASYNC enabled devices, register a callback and enable
156   asynchronous mode.  To disable asynchronous mode, register a NULL
157   callback. */
158
159typedef void (serial_event_ftype) (struct serial *scb, void *context);
160extern void serial_async (struct serial *scb, serial_event_ftype *handler, void *context);
161
162/* Provide direct access to the underlying FD (if any) used to
163   implement the serial device.  This interface is clearly
164   deprecated. Will call internal_error() if the operation isn't
165   applicable to the current serial device. */
166
167extern int deprecated_serial_fd (struct serial *scb);
168
169/* Trace/debug mechanism.
170
171   serial_debug() enables/disables internal debugging.
172   serial_debug_p() indicates the current debug state. */
173
174extern void serial_debug (struct serial *scb, int debug_p);
175
176extern int serial_debug_p (struct serial *scb);
177
178
179/* Details of an instance of a serial object */
180
181struct serial
182  {
183    int fd;			/* File descriptor */
184    struct serial_ops *ops;	/* Function vector */
185    void *state;       		/* Local context info for open FD */
186    serial_ttystate ttystate;	/* Not used (yet) */
187    int bufcnt;			/* Amount of data remaining in receive
188				   buffer.  -ve for sticky errors. */
189    unsigned char *bufp;	/* Current byte */
190    unsigned char buf[BUFSIZ];	/* Da buffer itself */
191    int current_timeout;	/* (ser-unix.c termio{,s} only), last
192				   value of VTIME */
193    int timeout_remaining;	/* (ser-unix.c termio{,s} only), we
194				   still need to wait for this many
195				   more seconds.  */
196    char *name;			/* The name of the device or host */
197    struct serial *next;	/* Pointer to the next `struct serial *' */
198    int refcnt;			/* Number of pointers to this block */
199    int debug_p;		/* Trace this serial devices operation. */
200    int async_state;		/* Async internal state. */
201    void *async_context;	/* Async event thread's context */
202    serial_event_ftype *async_handler;/* Async event handler */
203  };
204
205struct serial_ops
206  {
207    char *name;
208    struct serial_ops *next;
209    int (*open) (struct serial *, const char *name);
210    void (*close) (struct serial *);
211    int (*readchar) (struct serial *, int timeout);
212    int (*write) (struct serial *, const char *str, int len);
213    /* Discard pending output */
214    int (*flush_output) (struct serial *);
215    /* Discard pending input */
216    int (*flush_input) (struct serial *);
217    int (*send_break) (struct serial *);
218    void (*go_raw) (struct serial *);
219    serial_ttystate (*get_tty_state) (struct serial *);
220    int (*set_tty_state) (struct serial *, serial_ttystate);
221    void (*print_tty_state) (struct serial *, serial_ttystate,
222			     struct ui_file *);
223    int (*noflush_set_tty_state) (struct serial *, serial_ttystate,
224				  serial_ttystate);
225    int (*setbaudrate) (struct serial *, int rate);
226    int (*setstopbits) (struct serial *, int num);
227    /* Wait for output to drain */
228    int (*drain_output) (struct serial *);
229    /* Change the serial device into/out of asynchronous mode, call
230       the specified function when ever there is something
231       interesting. */
232    void (*async) (struct serial *scb, int async_p);
233  };
234
235/* Add a new serial interface to the interface list */
236
237extern void serial_add_interface (struct serial_ops * optable);
238
239/* File in which to record the remote debugging session */
240
241extern void serial_log_command (const char *);
242
243#endif /* SERIAL_H */
244