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