From 3115087d268dbcca2e2886a73fe34ebb75822226 Mon Sep 17 00:00:00 2001
From: goldsimon <goldsimon>
Date: Tue, 25 Aug 2009 17:54:28 +0000
Subject: [PATCH] Commented the functions, added sio_tryread() for non-blocking
 read (to be used in slipif-polling mode)

---
 src/include/lwip/sio.h | 72 ++++++++++++++++++++++++++++++++++++++----
 1 file changed, 66 insertions(+), 6 deletions(-)

diff --git a/src/include/lwip/sio.h b/src/include/lwip/sio.h
index 7d9162e4..28ae2f22 100644
--- a/src/include/lwip/sio.h
+++ b/src/include/lwip/sio.h
@@ -51,27 +51,87 @@ typedef void * sio_fd_t;
    or be implemented in your custom sio.c file. */
 
 #ifndef sio_open
-sio_fd_t sio_open(u8_t);
+/**
+ * Opens a serial device for communication.
+ * 
+ * @param devnum device number
+ * @return handle to serial device if successful, NULL otherwise
+ */
+sio_fd_t sio_open(u8_t devnum);
 #endif
 
 #ifndef sio_send
-void sio_send(u8_t, sio_fd_t);
+/**
+ * Sends a single character to the serial device.
+ * 
+ * @param c character to send
+ * @param fd serial device handle
+ * 
+ * @note This function will block until the character can be sent.
+ */
+void sio_send(u8_t c, sio_fd_t fd);
 #endif
 
 #ifndef sio_recv
-u8_t sio_recv(sio_fd_t);
+/**
+ * Receives a single character from the serial device.
+ * 
+ * @param fd serial device handle
+ * 
+ * @note This function will block until a character is received.
+ */
+u8_t sio_recv(sio_fd_t fd);
 #endif
 
 #ifndef sio_read
-u32_t sio_read(sio_fd_t, u8_t *, u32_t);
+/**
+ * Reads from the serial device.
+ * 
+ * @param fd serial device handle
+ * @param data pointer to data buffer for receiving
+ * @param len maximum length (in bytes) of data to receive
+ * @return number of bytes actually received - may be 0 if aborted by sio_read_abort
+ * 
+ * @note This function will block until data can be received. The blocking
+ * can be cancelled by calling sio_read_abort().
+ */
+u32_t sio_read(sio_fd_t fd, u8_t *data, u32_t len);
+#endif
+
+#ifndef sio_tryread
+/**
+ * Tries to read from the serial device. Same as sio_read but returns
+ * immediately if no data is available and never blocks.
+ * 
+ * @param fd serial device handle
+ * @param data pointer to data buffer for receiving
+ * @param len maximum length (in bytes) of data to receive
+ * @return number of bytes actually received
+ */
+u32_t sio_tryread(sio_fd_t fd, u8_t *data, u32_t len);
 #endif
 
 #ifndef sio_write
-u32_t sio_write(sio_fd_t, u8_t *, u32_t);
+/**
+ * Writes to the serial device.
+ * 
+ * @param fd serial device handle
+ * @param data pointer to data to send
+ * @param len length (in bytes) of data to send
+ * @return number of bytes actually sent
+ * 
+ * @note This function will block until all data can be sent.
+ */
+u32_t sio_write(sio_fd_t fd, u8_t *data, u32_t len);
 #endif
 
 #ifndef sio_read_abort
-void sio_read_abort(sio_fd_t);
+/**
+ * Aborts a blocking sio_read() call.
+ * 
+ * @param fd serial device handle
+ */
+void sio_read_abort(sio_fd_t fd);
 #endif
 
 #ifdef __cplusplus