drv/ser.h

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