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