Misc documentation and style fixes.
[bertos.git] / drv / ser.c
index ac91d87fcd96de706907f25f342a25d52fd74a32..9e7e96d6d9592b6268fe2760e7456ab94b95f8b5 100755 (executable)
--- a/drv/ser.c
+++ b/drv/ser.c
  * \author Bernardo Innocenti <bernie@develer.com>
  */
 
-/*
- * $Log$
- * Revision 1.9  2004/08/08 06:06:20  bernie
- * Use new-style CONFIG_ idiom; Fix module-wide documentation.
- *
- * Revision 1.8  2004/07/29 22:57:09  bernie
- * ser_drain(): New function; Make Serial::is_open a debug-only feature; Switch to new-style CONFIG_* macros.
- *
- * Revision 1.7  2004/07/18 21:49:03  bernie
- * Make CONFIG_SER_DEFBAUDRATE optional.
- *
- * Revision 1.6  2004/06/07 15:56:28  aleph
- * Remove cast-as-lvalue extension abuse
- *
- * Revision 1.5  2004/06/06 16:41:44  bernie
- * ser_putchar(): Use fifo_push_locked() to fix potential race on 8bit processors.
- *
- * Revision 1.4  2004/06/03 11:27:09  bernie
- * Add dual-license information.
- *
- * Revision 1.3  2004/06/02 21:35:24  aleph
- * Serial enhancements: interruptible receive handler and 8 bit serial status for AVR; remove volatile attribute to FIFOBuffer, useless for new fifobuf routens
- *
- * Revision 1.2  2004/05/23 18:21:53  bernie
- * Trim CVS logs and cleanup header info.
- *
- */
+/*#*
+ *#* $Log$
+ *#* Revision 1.15  2004/08/25 14:12:08  rasky
+ *#* Aggiornato il comment block dei log RCS
+ *#*
+ *#* Revision 1.14  2004/08/24 16:22:57  bernie
+ *#* Thinkos; Doxygen fixes
+ *#*
+ *#* Revision 1.13  2004/08/24 16:20:48  bernie
+ *#* ser_read(): Make buffer argument void *#* for consistency with ANSI C and ser_write()
+ *#*
+ *#* Revision 1.12  2004/08/24 13:49:39  bernie
+ *#* Fix thinko.
+ *#*
+ *#* Revision 1.11  2004/08/15 05:32:22  bernie
+ *#* ser_resync(): New function.
+ *#*
+ *#* Revision 1.10  2004/08/10 06:29:50  bernie
+ *#* Rename timer_gettick() to timer_ticks().
+ *#*
+ *#* Revision 1.9  2004/08/08 06:06:20  bernie
+ *#* Use new-style CONFIG_ idiom; Fix module-wide documentation.
+ *#*
+ *#* Revision 1.8  2004/07/29 22:57:09  bernie
+ *#* ser_drain(): New function; Make Serial::is_open a debug-only feature; Switch to new-style CONFIG_* macros.
+ *#*
+ *#* Revision 1.7  2004/07/18 21:49:03  bernie
+ *#* Make CONFIG_SER_DEFBAUDRATE optional.
+ *#*
+ *#* Revision 1.6  2004/06/07 15:56:28  aleph
+ *#* Remove cast-as-lvalue extension abuse
+ *#*
+ *#* Revision 1.5  2004/06/06 16:41:44  bernie
+ *#* ser_putchar(): Use fifo_push_locked() to fix potential race on 8bit processors.
+ *#*
+ *#* Revision 1.4  2004/06/03 11:27:09  bernie
+ *#* Add dual-license information.
+ *#*
+ *#* Revision 1.3  2004/06/02 21:35:24  aleph
+ *#* Serial enhancements: interruptible receive handler and 8 bit serial status for AVR; remove volatile attribute to FIFOBuffer, useless for new fifobuf routens
+ *#*
+ *#* Revision 1.2  2004/05/23 18:21:53  bernie
+ *#* Trim CVS logs and cleanup header info.
+ *#*
+ *#*/
 
 #include <mware/formatwr.h>
 #include <drv/kdebug.h>
@@ -90,7 +108,7 @@ int ser_putchar(int c, struct Serial *port)
        if (fifo_isfull_locked(&port->txfifo))
        {
 #if CONFIG_SER_TXTIMEOUT != -1
-               time_t start_time = timer_gettick();
+               time_t start_time = timer_ticks();
 #endif
 
                /* Attende finche' il buffer e' pieno... */
@@ -101,7 +119,7 @@ int ser_putchar(int c, struct Serial *port)
                        proc_switch();
 #endif
 #if CONFIG_SER_TXTIMEOUT != -1
-                       if (timer_gettick() - start_time >= port->txtimeout)
+                       if (timer_ticks() - start_time >= port->txtimeout)
                        {
                                port->status |= SERRF_TXTIMEOUT;
                                return EOF;
@@ -137,7 +155,7 @@ int ser_getchar(struct Serial *port)
        if (fifo_isempty_locked(&port->rxfifo))
        {
 #if CONFIG_SER_RXTIMEOUT != -1
-               time_t start_time = timer_gettick();
+               time_t start_time = timer_ticks();
 #endif
                /* Wait while buffer is empty */
                do
@@ -147,7 +165,7 @@ int ser_getchar(struct Serial *port)
                        proc_switch();
 #endif
 #if CONFIG_SER_RXTIMEOUT != -1
-                       if (timer_gettick() - start_time >= port->rxtimeout)
+                       if (timer_ticks() - start_time >= port->rxtimeout)
                        {
                                port->status |= SERRF_RXTIMEOUT;
                                return EOF;
@@ -233,21 +251,22 @@ int ser_gets_echo(struct Serial *port, char *buf, int size, bool echo)
 
 
 /*!
- * Read at most size bytes and puts them
- * in buf.
- * \return number of bytes read or EOF in case
- *         of error.
+ * Read at most \a size bytes from \a port and put them in \a buf
+ *
+ * \return number of bytes actually read, or EOF in
+ *         case of error.
  */
-int ser_read(struct Serial *port, char *buf, size_t size)
+int ser_read(struct Serial *port, void *buf, size_t size)
 {
        size_t i = 0;
+       char *_buf = (char *)buf;
        int c;
 
        while (i < size)
        {
                if ((c = ser_getchar(port)) == EOF)
                        return EOF;
-               buf[i++] = c;
+               _buf[i++] = c;
        }
 
        return i;
@@ -316,6 +335,33 @@ void ser_settimeouts(struct Serial *port, time_t rxtimeout, time_t txtimeout)
 }
 #endif /* CONFIG_SER_RXTIMEOUT || CONFIG_SER_TXTIMEOUT */
 
+#if CONFIG_SER_RXTIMEOUT != -1
+/*!
+ * Discard input to resynchronize with remote end
+ *
+ * Discard incoming data until the port stops receiving
+ * characters for at least \a delay milliseconds.
+ *
+ * \note Serial errors are reset before and after executing the purge.
+ */
+void ser_resync(struct Serial *port, time_t delay)
+{
+       time_t old_rxtimeout = port->rxtimeout;
+
+       ser_settimeouts(port, delay, port->txtimeout);
+       do
+       {
+               ser_setstatus(port, 0);
+               ser_getchar(port);
+       }
+       while (!(ser_getstatus(port) & SERRF_RXTIMEOUT));
+
+       /* Restore port to an usable status */
+       ser_setstatus(port, 0);
+       ser_settimeouts(port, old_rxtimeout, port->txtimeout);
+}
+#endif /* CONFIG_SER_RXTIMEOUT */
+
 
 void ser_setbaudrate(struct Serial *port, unsigned long rate)
 {
@@ -332,12 +378,13 @@ void ser_setparity(struct Serial *port, int parity)
 /*!
  * Flush both the RX and TX buffers.
  */
-void ser_purge(struct Serial *ser)
+void ser_purge(struct Serial *port)
 {
-       fifo_flush_locked(&ser->rxfifo);
-       fifo_flush_locked(&ser->txfifo);
+       fifo_flush_locked(&port->rxfifo);
+       fifo_flush_locked(&port->txfifo);
 }
 
+
 /*!
  * Wait until all pending output is completely
  * transmitted to the other end.
@@ -348,7 +395,7 @@ void ser_purge(struct Serial *ser)
  */
 void ser_drain(struct Serial *ser)
 {
-       while(!fifo_isempty(&ser->txfifo))
+       while (!fifo_isempty(&ser->txfifo))
        {
 #if defined(CONFIG_KERN_SCHED) && CONFIG_KERN_SCHED
                        /* Give up timeslice to other processes. */