sio.h

00001 /*
00002  * Copyright (c) 2001-2004 Swedish Institute of Computer Science.
00003  * All rights reserved. 
00004  * 
00005  * Redistribution and use in source and binary forms, with or without modification, 
00006  * are permitted provided that the following conditions are met:
00007  *
00008  * 1. Redistributions of source code must retain the above copyright notice,
00009  *    this list of conditions and the following disclaimer.
00010  * 2. Redistributions in binary form must reproduce the above copyright notice,
00011  *    this list of conditions and the following disclaimer in the documentation
00012  *    and/or other materials provided with the distribution.
00013  * 3. The name of the author may not be used to endorse or promote products
00014  *    derived from this software without specific prior written permission. 
00015  *
00016  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED 
00017  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 
00018  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT 
00019  * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
00020  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT 
00021  * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 
00022  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 
00023  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 
00024  * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 
00025  * OF SUCH DAMAGE.
00026  *
00027  * This file is part of the lwIP TCP/IP stack.
00028  */
00029 
00030 /*
00031  * This is the interface to the platform specific serial IO module
00032  * It needs to be implemented by those platforms which need SLIP or PPP
00033  */
00034 
00035 #ifndef __SIO_H__
00036 #define __SIO_H__
00037 
00038 #include "lwip/arch.h"
00039 
00040 #ifdef __cplusplus
00041 extern "C" {
00042 #endif
00043 
00044 /* If you want to define sio_fd_t elsewhere or differently,
00045    define this in your cc.h file. */
00046 #ifndef __sio_fd_t_defined
00047 typedef void * sio_fd_t;
00048 #endif
00049 
00050 /* The following functions can be defined to something else in your cc.h file
00051    or be implemented in your custom sio.c file. */
00052 
00053 #ifndef sio_open
00054 /**
00055  * Opens a serial device for communication.
00056  * 
00057  * @param devnum device number
00058  * @return handle to serial device if successful, NULL otherwise
00059  */
00060 sio_fd_t sio_open(u8_t devnum);
00061 #endif
00062 
00063 #ifndef sio_send
00064 /**
00065  * Sends a single character to the serial device.
00066  * 
00067  * @param c character to send
00068  * @param fd serial device handle
00069  * 
00070  * @note This function will block until the character can be sent.
00071  */
00072 void sio_send(u8_t c, sio_fd_t fd);
00073 #endif
00074 
00075 #ifndef sio_recv
00076 /**
00077  * Receives a single character from the serial device.
00078  * 
00079  * @param fd serial device handle
00080  * 
00081  * @note This function will block until a character is received.
00082  */
00083 u8_t sio_recv(sio_fd_t fd);
00084 #endif
00085 
00086 #ifndef sio_read
00087 /**
00088  * Reads from the serial device.
00089  * 
00090  * @param fd serial device handle
00091  * @param data pointer to data buffer for receiving
00092  * @param len maximum length (in bytes) of data to receive
00093  * @return number of bytes actually received - may be 0 if aborted by sio_read_abort
00094  * 
00095  * @note This function will block until data can be received. The blocking
00096  * can be cancelled by calling sio_read_abort().
00097  */
00098 u32_t sio_read(sio_fd_t fd, u8_t *data, u32_t len);
00099 #endif
00100 
00101 #ifndef sio_tryread
00102 /**
00103  * Tries to read from the serial device. Same as sio_read but returns
00104  * immediately if no data is available and never blocks.
00105  * 
00106  * @param fd serial device handle
00107  * @param data pointer to data buffer for receiving
00108  * @param len maximum length (in bytes) of data to receive
00109  * @return number of bytes actually received
00110  */
00111 u32_t sio_tryread(sio_fd_t fd, u8_t *data, u32_t len);
00112 #endif
00113 
00114 #ifndef sio_write
00115 /**
00116  * Writes to the serial device.
00117  * 
00118  * @param fd serial device handle
00119  * @param data pointer to data to send
00120  * @param len length (in bytes) of data to send
00121  * @return number of bytes actually sent
00122  * 
00123  * @note This function will block until all data can be sent.
00124  */
00125 u32_t sio_write(sio_fd_t fd, u8_t *data, u32_t len);
00126 #endif
00127 
00128 #ifndef sio_read_abort
00129 /**
00130  * Aborts a blocking sio_read() call.
00131  * 
00132  * @param fd serial device handle
00133  */
00134 void sio_read_abort(sio_fd_t fd);
00135 #endif
00136 
00137 #ifdef __cplusplus
00138 }
00139 #endif
00140 
00141 #endif /* __SIO_H__ */