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