ChibiOS/RT Architecture - Reference Manual - Guides |
00001 /* 00002 ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. 00003 00004 This file is part of ChibiOS/RT. 00005 00006 ChibiOS/RT is free software; you can redistribute it and/or modify 00007 it under the terms of the GNU General Public License as published by 00008 the Free Software Foundation; either version 3 of the License, or 00009 (at your option) any later version. 00010 00011 ChibiOS/RT is distributed in the hope that it will be useful, 00012 but WITHOUT ANY WARRANTY; without even the implied warranty of 00013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00014 GNU General Public License for more details. 00015 00016 You should have received a copy of the GNU General Public License 00017 along with this program. If not, see <http://www.gnu.org/licenses/>. 00018 00019 --- 00020 00021 A special exception to the GPL can be applied should you wish to distribute 00022 a combined work that includes ChibiOS/RT, without being obliged to provide 00023 the source code for any proprietary components. See the file exception.txt 00024 for full details of how and when the exception can be applied. 00025 */ 00026 00027 /** 00028 * @file chioch.h 00029 * @brief I/O channels. 00030 * @details This header defines abstract interfaces useful to access generic 00031 * I/O resources in a standardized way. 00032 * 00033 * @addtogroup io_channels 00034 * @details This module defines an abstract interface for I/O channels by 00035 * extending the @p BaseSequentialStream interface. Note that no code 00036 * is present, I/O channels are just abstract interface like 00037 * structures, you should look at the systems as to a set of abstract 00038 * C++ classes (even if written in C). Specific device drivers can 00039 * use/extend the interface and implement them.<br> 00040 * This system has the advantage to make the access to channels 00041 * independent from the implementation logic. 00042 * @{ 00043 */ 00044 00045 #ifndef _CHIOCH_H_ 00046 #define _CHIOCH_H_ 00047 00048 /** 00049 * @brief @p BaseChannel specific methods. 00050 */ 00051 #define _base_channel_methods \ 00052 _base_sequental_stream_methods \ 00053 /* Channel output check.*/ \ 00054 bool_t (*putwouldblock)(void *instance); \ 00055 /* Channel input check.*/ \ 00056 bool_t (*getwouldblock)(void *instance); \ 00057 /* Channel put method with timeout specification.*/ \ 00058 msg_t (*put)(void *instance, uint8_t b, systime_t time); \ 00059 /* Channel get method with timeout specification.*/ \ 00060 msg_t (*get)(void *instance, systime_t time); \ 00061 /* Channel write method with timeout specification.*/ \ 00062 size_t (*writet)(void *instance, const uint8_t *bp, \ 00063 size_t n, systime_t time); \ 00064 /* Channel read method with timeout specification.*/ \ 00065 size_t (*readt)(void *instance, uint8_t *bp, size_t n, systime_t time); 00066 00067 /** 00068 * @brief @p BaseChannel specific data. 00069 * @note It is empty because @p BaseChannel is only an interface without 00070 * implementation. 00071 */ 00072 #define _base_channel_data \ 00073 _base_sequental_stream_data 00074 00075 /** 00076 * @brief @p BaseChannel virtual methods table. 00077 */ 00078 struct BaseChannelVMT { \ 00079 _base_channel_methods \ 00080 }; 00081 00082 /** 00083 * @extends BaseSequentialStream 00084 * 00085 * @brief Base channel class. 00086 * @details This class represents a generic, byte-wide, I/O channel. This class 00087 * introduces generic I/O primitives with timeout specification. 00088 */ 00089 typedef struct { 00090 /** @brief Virtual Methods Table.*/ 00091 const struct BaseChannelVMT *vmt; 00092 _base_channel_data 00093 } BaseChannel; 00094 00095 /** 00096 * @brief Channel output check. 00097 * @details This function verifies if a subsequent put/write operation would 00098 * block. 00099 * 00100 * @param[in] ip pointer to a @p BaseChannel or derived class 00101 * @return The output queue status: 00102 * @retval FALSE if the output queue has space and would not block a 00103 * write operation. 00104 * @retval TRUE if the output queue is full and would block a write 00105 * operation. 00106 */ 00107 #define chIOPutWouldBlock(ip) ((ip)->vmt->putwouldblock(ip)) 00108 00109 /** 00110 * @brief Channel input check. 00111 * @details This function verifies if a subsequent get/read operation would 00112 * block. 00113 * 00114 * @param[in] ip pointer to a @p BaseChannel or derived class 00115 * @return The input queue status: 00116 * @retval FALSE if the input queue contains data and would not block a 00117 * read operation. 00118 * @retval TRUE if the input queue is empty and would block a read 00119 * operation. 00120 */ 00121 #define chIOGetWouldBlock(ip) ((ip)->vmt->getwouldblock(ip)) 00122 00123 /** 00124 * @brief Channel blocking byte write. 00125 * @details This function writes a byte value to a channel. If the channel 00126 * is not ready to accept data then the calling thread is suspended. 00127 * 00128 * @param[in] ip pointer to a @p BaseChannel or derived class 00129 * @param[in] b the byte value to be written to the channel 00130 * @return The operation status: 00131 * @retval Q_OK if the operation succeeded. 00132 * @retval Q_RESET if the channel associated queue (if any) was reset. 00133 */ 00134 #define chIOPut(ip, b) ((ip)->vmt->put(ip, b, TIME_INFINITE)) 00135 00136 /** 00137 * @brief Channel blocking byte write with timeout. 00138 * @details This function writes a byte value to a channel. If the channel 00139 * is not ready to accept data then the calling thread is suspended. 00140 * 00141 * @param[in] ip pointer to a @p BaseChannel or derived class 00142 * @param[in] b the byte value to be written to the channel 00143 * @param[in] time the number of ticks before the operation timeouts, 00144 * the following special values are allowed: 00145 * - @a TIME_IMMEDIATE immediate timeout. 00146 * - @a TIME_INFINITE no timeout. 00147 * . 00148 * @return The operation status: 00149 * @retval Q_OK if the operation succeeded. 00150 * @retval Q_TIMEOUT if the specified time expired. 00151 * @retval Q_RESET if the channel associated queue (if any) was reset. 00152 */ 00153 #define chIOPutTimeout(ip, b, time) ((ip)->vmt->put(ip, b, time)) 00154 00155 /** 00156 * @brief Channel blocking byte read. 00157 * @details This function reads a byte value from a channel. If the data 00158 * is not available then the calling thread is suspended. 00159 * 00160 * @param[in] ip pointer to a @p BaseChannel or derived class 00161 * @return A byte value from the queue or: 00162 * @retval Q_RESET if the channel associated queue (if any) was reset. 00163 */ 00164 #define chIOGet(ip) ((ip)->vmt->get(ip, TIME_INFINITE)) 00165 00166 /** 00167 * @brief Channel blocking byte read with timeout. 00168 * @details This function reads a byte value from a channel. If the data 00169 * is not available then the calling thread is suspended. 00170 * 00171 * @param[in] ip pointer to a @p BaseChannel or derived class 00172 * @param[in] time the number of ticks before the operation timeouts, 00173 * the following special values are allowed: 00174 * - @a TIME_IMMEDIATE immediate timeout. 00175 * - @a TIME_INFINITE no timeout. 00176 * . 00177 * @return A byte value from the queue or: 00178 * @retval Q_TIMEOUT if the specified time expired. 00179 * @retval Q_RESET if the channel associated queue (if any) was reset. 00180 */ 00181 #define chIOGetTimeout(ip, time) ((ip)->vmt->get(ip, time)) 00182 00183 /** 00184 * @brief Channel blocking write with timeout. 00185 * @details The function writes data from a buffer to a channel. If the channel 00186 * is not ready to accept data then the calling thread is suspended. 00187 * 00188 * @param[in] ip pointer to a @p BaseChannel or derived class 00189 * @param[out] bp pointer to the data buffer 00190 * @param[in] n the maximum amount of data to be transferred 00191 * @param[in] time the number of ticks before the operation timeouts, 00192 * the following special values are allowed: 00193 * - @a TIME_IMMEDIATE immediate timeout. 00194 * - @a TIME_INFINITE no timeout. 00195 * . 00196 * @return The number of bytes transferred. 00197 */ 00198 #define chIOWriteTimeout(ip, bp, n, time) \ 00199 ((ip)->vmt->writet(ip, bp, n, time)) 00200 00201 /** 00202 * @brief Channel blocking read with timeout. 00203 * @details The function reads data from a channel into a buffer. If the data 00204 * is not available then the calling thread is suspended. 00205 * 00206 * @param[in] ip pointer to a @p BaseChannel or derived class 00207 * @param[in] bp pointer to the data buffer 00208 * @param[in] n the maximum amount of data to be transferred 00209 * @param[in] time the number of ticks before the operation timeouts, 00210 * the following special values are allowed: 00211 * - @a TIME_IMMEDIATE immediate timeout. 00212 * - @a TIME_INFINITE no timeout. 00213 * . 00214 * @return The number of bytes transferred. 00215 */ 00216 #define chIOReadTimeout(ip, bp, n, time) \ 00217 ((ip)->vmt->readt(ip, bp, n, time)) 00218 00219 #if CH_USE_EVENTS 00220 /** 00221 * @brief @p BaseAsynchronousChannel specific methods. 00222 */ 00223 #define _base_asynchronous_channel_methods \ 00224 _base_channel_methods 00225 00226 /** 00227 * @brief @p BaseAsynchronousChannel specific data. 00228 */ 00229 #define _base_asynchronous_channel_data \ 00230 _base_channel_data \ 00231 /* Data Available EventSource.*/ \ 00232 EventSource ievent; \ 00233 /* Data Transmitted EventSource.*/ \ 00234 EventSource oevent; 00235 00236 /** 00237 * @brief @p BaseAsynchronousChannel virtual methods table. 00238 */ 00239 struct BaseAsynchronousChannelVMT { 00240 _base_asynchronous_channel_methods 00241 }; 00242 00243 /** 00244 * @extends BaseChannel 00245 * 00246 * @brief Base asynchronous channel class. 00247 * @details This class extends @p BaseChannel by adding event sources fields 00248 * for asynchronous I/O for use in an event-driven environment. 00249 */ 00250 typedef struct { 00251 /** @brief Virtual Methods Table.*/ 00252 const struct BaseAsynchronousChannelVMT *vmt; 00253 _base_asynchronous_channel_data 00254 } BaseAsynchronousChannel; 00255 00256 /** 00257 * @brief Returns the write event source. 00258 * @details The write event source is broadcasted when the channel is ready 00259 * for write operations. This usually happens when the internal 00260 * output queue becomes empty. 00261 * 00262 * @param[in] ip pointer to a @p BaseAsynchronousChannel or derived 00263 * class 00264 * @return A pointer to an @p EventSource object. 00265 */ 00266 #define chIOGetWriteEventSource(ip) (&((ip)->vmt->oevent)) 00267 00268 /** 00269 * @brief Returns the read event source. 00270 * @details The read event source is broadcasted when the channel is ready 00271 * for read operations. This usually happens when the internal 00272 * input queue becomes non-empty. 00273 * 00274 * @param[in] ip pointer to a @p BaseAsynchronousChannel or derived 00275 * class 00276 * @return A pointer to an @p EventSource object. 00277 */ 00278 #define chIOGetReadEventSource(ip) (&((ip)->vmt->ievent)) 00279 00280 #endif /* CH_USE_EVENTS */ 00281 00282 #endif /* _CHIOCH_H_ */ 00283 00284 /** @} */