Fix naming conventions.
[bertos.git] / drv / ser.h
1 /*!
2  * \file
3  * <!--
4  * Copyright 2003,2004 Develer S.r.l. (http://www.develer.com/)
5  * Copyright 2000 Bernardo Innocenti <bernie@codewiz.org>
6  * This file is part of DevLib - See README.devlib for information.
7  * -->
8  *
9  * \brief High level serial I/O API
10  *
11  * \version $Id$
12  * \author Bernardo Innocenti <bernie@develer.com>
13  */
14
15 /*#*
16  *#* $Log$
17  *#* Revision 1.25  2006/02/17 22:28:00  bernie
18  *#* Rename ser_emul.c to ser_posix.c.
19  *#*
20  *#* Revision 1.24  2006/02/17 22:23:06  bernie
21  *#* Update POSIX serial emulator.
22  *#*
23  *#* Revision 1.23  2005/11/27 23:33:40  bernie
24  *#* Use appconfig.h instead of cfg/config.h.
25  *#*
26  *#* Revision 1.22  2005/11/04 16:20:02  bernie
27  *#* Fix reference to README.devlib in header.
28  *#*
29  *#* Revision 1.21  2005/04/11 19:10:27  bernie
30  *#* Include top-level headers from cfg/ subdir.
31  *#*
32  *#* Revision 1.20  2005/01/22 04:20:01  bernie
33  *#* Reformat.
34  *#*
35  *#* Revision 1.19  2005/01/11 18:08:16  aleph
36  *#* Add missing include
37  *#*
38  *#* Revision 1.18  2004/12/08 08:57:17  bernie
39  *#* Rename time_t to mtime_t.
40  *#*
41  *#* Revision 1.17  2004/11/16 21:54:56  bernie
42  *#* Changes for SC Monoboard support.
43  *#*
44  *#* Revision 1.16  2004/10/19 11:48:05  bernie
45  *#* Reformat.
46  *#*
47  *#* Revision 1.15  2004/10/19 08:11:53  bernie
48  *#* SERRF_TX, SERRF_RX: New macros; Enhance documentation.
49  *#*
50  *#* Revision 1.14  2004/10/03 18:43:18  bernie
51  *#* Fix a nasty bug caused by confusion between old-style and new-style configuration macros.
52  *#*
53  *#* Revision 1.13  2004/09/14 21:04:57  bernie
54  *#* Don't vanely call kdebug.h.
55  *#*
56  *#* Revision 1.12  2004/09/06 21:40:50  bernie
57  *#* Move buffer handling in chip-specific driver.
58  *#*
59  *#* Revision 1.11  2004/08/25 14:12:08  rasky
60  *#* Aggiornato il comment block dei log RCS
61  *#*
62  *#* Revision 1.10  2004/08/24 16:20:48  bernie
63  *#* ser_read(): Make buffer argument void *#* for consistency with ANSI C and ser_write()
64  *#*
65  *#* Revision 1.9  2004/08/15 05:32:22  bernie
66  *#* ser_resync(): New function.
67  *#*
68  *#* Revision 1.8  2004/08/02 20:20:29  aleph
69  *#* Merge from project_ks
70  *#*
71  *#* Revision 1.7  2004/07/30 14:15:53  rasky
72  *#* Nuovo supporto unificato per detect della CPU
73  *#*
74  *#* Revision 1.6  2004/07/29 22:57:09  bernie
75  *#* ser_drain(): New function; Make Serial::is_open a debug-only feature; Switch to new-style CONFIG_* macros.
76  *#*
77  *#* Revision 1.5  2004/07/18 21:54:23  bernie
78  *#* Add ATmega8 support.
79  *#*
80  *#* Revision 1.4  2004/06/03 11:27:09  bernie
81  *#* Add dual-license information.
82  *#*
83  *#* Revision 1.3  2004/06/02 21:35:24  aleph
84  *#* Serial enhancements: interruptible receive handler and 8 bit serial status for AVR; remove volatile attribute to FIFOBuffer, useless for new fifobuf routens
85  *#*
86  *#* Revision 1.2  2004/05/23 18:21:53  bernie
87  *#* Trim CVS logs and cleanup header info.
88  *#*
89  *#*/
90 #ifndef DRV_SER_H
91 #define DRV_SER_H
92
93 #include <mware/fifobuf.h>
94 #include <cfg/compiler.h>
95 #include <cfg/macros.h> /* BV() */
96 #include <cfg/os.h>
97 #include <appconfig.h>
98
99 /*! \name Serial Error/status flags. */
100 /*\{*/
101 #if CPU_AVR
102         typedef uint8_t serstatus_t;
103
104         /* Software errors */
105         #define SERRF_RXFIFOOVERRUN  BV(0)  /*!< Rx FIFO buffer overrun */
106         #define SERRF_RXTIMEOUT      BV(5)  /*!< Receive timeout */
107         #define SERRF_TXTIMEOUT      BV(6)  /*!< Transmit timeout */
108
109         /*
110          * Hardware errors.
111          * These flags map directly to the AVR UART Status Register (USR).
112          */
113         #define SERRF_RXSROVERRUN    BV(3)  /*!< Rx shift register overrun */
114         #define SERRF_FRAMEERROR     BV(4)  /*!< Stop bit missing */
115         #define SERRF_PARITYERROR    BV(7)  /*!< Parity error */
116         #define SERRF_NOISEERROR     0      /*!< Unsupported */
117 #elif CPU_DSP56K
118         typedef uint16_t serstatus_t;
119
120         /* Software errors */
121         #define SERRF_RXFIFOOVERRUN  BV(0)  /*!< Rx FIFO buffer overrun */
122         #define SERRF_RXTIMEOUT      BV(1)  /*!< Receive timeout */
123         #define SERRF_TXTIMEOUT      BV(2)  /*!< Transmit timeout */
124
125         /*
126          * Hardware errors.
127          * These flags map directly to the SCI Control Register.
128          */
129         #define SERRF_PARITYERROR    BV(8)  /*!< Parity error */
130         #define SERRF_FRAMEERROR     BV(9)  /*!< Stop bit missing */
131         #define SERRF_NOISEERROR     BV(10) /*!< Noise error */
132         #define SERRF_RXSROVERRUN    BV(11) /*!< Rx shift register overrun */
133 #elif OS_HOSTED
134         typedef uint16_t serstatus_t;
135
136         /* Software errors */
137         #define SERRF_RXFIFOOVERRUN  BV(0)  /*!< Rx FIFO buffer overrun */
138         #define SERRF_RXTIMEOUT      BV(1)  /*!< Receive timeout */
139         #define SERRF_TXTIMEOUT      BV(2)  /*!< Transmit timeout */
140
141         /* Hardware errors */
142         #define SERRF_RXSROVERRUN    0      /*!< Unsupported in emulated serial port. */
143         #define SERRF_FRAMEERROR     0      /*!< Unsupported in emulated serial port. */
144         #define SERRF_PARITYERROR    0      /*!< Unsupported in emulated serial port. */
145         #define SERRF_NOISEERROR     0      /*!< Unsupported in emulated serial port. */
146
147 #else
148         #error unknown architecture
149 #endif
150 /*\}*/
151
152 /** Mask to group all RX errors. */
153 #define SERRF_RX \
154         ( SERRF_RXFIFOOVERRUN \
155         | SERRF_RXTIMEOUT \
156         | SERRF_RXSROVERRUN \
157         | SERRF_PARITYERROR \
158         | SERRF_FRAMEERROR \
159         | SERRF_NOISEERROR)
160
161 /** Mask to group all TX errors. */
162 #define SERRF_TX  (SERRF_TXTIMEOUT)
163
164
165 /*!
166  * \name Parity settings for ser_setparity().
167  *
168  * \note Values are AVR-specific for performance reasons.
169  *       Other processors should either decode them or
170  *       redefine these macros.
171  */
172 /*\{*/
173 #define SER_PARITY_NONE  0
174 #define SER_PARITY_EVEN  2
175 #define SER_PARITY_ODD   3
176 /*\}*/
177
178 /*!
179  * \name Serial hw numbers
180  *
181  * \{
182  */
183 enum
184 {
185 #if CPU_AVR_ATMEGA64 || CPU_AVR_ATMEGA128
186         SER_UART0,
187         SER_UART1,
188         SER_SPI,
189 #elif CPU_AVR_ATMEGA103 || CPU_AVR_ATMEGA8
190         SER_UART0,
191         SER_SPI,
192 #elif CPU_DSP56K
193         // \todo since we now support "fake" multiplexed serials, this should be moved to hw.h
194         SER_UART0,
195         SER_PUNTALI,
196         SER_BARCODE,
197 #elif OS_HOSTED
198         SER_UART0,
199         SER_UART1,
200 #else
201         #error unknown architecture
202 #endif
203         SER_CNT  /*!< Number of serial ports */
204 };
205 /*\}*/
206
207
208 struct SerialHardware;
209
210 /*! Human-readable serial error descriptions */
211 extern const char * const serial_errors[8];
212
213 /*! Serial handle structure */
214 struct Serial
215 {
216         /*! Physical port number */
217         unsigned int unit;
218
219 #ifdef _DEBUG
220         bool is_open;
221 #endif
222
223         /*!
224          * \name Transmit and receive FIFOs.
225          *
226          * Declared volatile because handled asinchronously by interrupts.
227          *
228          * \{
229          */
230         FIFOBuffer txfifo;
231         FIFOBuffer rxfifo;
232         /* \} */
233
234 #if CONFIG_SER_RXTIMEOUT != -1
235         mtime_t rxtimeout;
236 #endif
237 #if CONFIG_SER_TXTIMEOUT != -1
238         mtime_t txtimeout;
239 #endif
240
241         /*! Holds the flags defined above.  Will be 0 when no errors have occurred. */
242         serstatus_t status;
243
244         /*! Low-level interface to hardware. */
245         struct SerialHardware* hw;
246 };
247
248
249 /* Function prototypes */
250 extern int ser_putchar(int c, struct Serial *port);
251 extern int ser_getchar(struct Serial *port);
252 extern int ser_getchar_nowait(struct Serial *port);
253
254 extern int ser_write(struct Serial *port, const void *buf, size_t len);
255 extern int ser_read(struct Serial *port, void *buf, size_t size);
256
257 extern int ser_print(struct Serial *port, const char *s);
258 extern int ser_printf(struct Serial *port, const char *format, ...) FORMAT(__printf__, 2, 3);
259
260 extern int ser_gets(struct Serial *port, char *buf, int size);
261 extern int ser_gets_echo(struct Serial *port, char *buf, int size, bool echo);
262
263 extern void ser_setbaudrate(struct Serial *port, unsigned long rate);
264 extern void ser_setparity(struct Serial *port, int parity);
265 extern void ser_settimeouts(struct Serial *port, mtime_t rxtimeout, mtime_t txtimeout);
266 extern void ser_resync(struct Serial *port, mtime_t delay);
267 extern void ser_purge(struct Serial *port);
268 extern void ser_drain(struct Serial *port);
269
270 extern struct Serial *ser_open(unsigned int unit);
271 extern void ser_close(struct Serial *port);
272
273 /*!
274  * \name Additional functions implemented as macros
275  *
276  * \{
277  */
278 #define ser_getstatus(h)    ((h)->status)
279 #define ser_setstatus(h, x) ((h)->status = (x))
280 /* \} */
281
282 #endif /* DRV_SER_H */