1 /* 2 * Copyright (c) 2004, Swedish Institute of Computer Science. 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 1. Redistributions of source code must retain the above copyright 9 * notice, this list of conditions and the following disclaimer. 10 * 2. Redistributions in binary form must reproduce the above copyright 11 * notice, this list of conditions and the following disclaimer in the 12 * documentation and/or other materials provided with the distribution. 13 * 3. Neither the name of the Institute nor the names of its contributors 14 * may be used to endorse or promote products derived from this software 15 * without specific prior written permission. 16 * 17 * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND 18 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20 * ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE 21 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27 * SUCH DAMAGE. 28 * 29 * This file is part of the uIP TCP/IP stack 30 * 31 * Author: Adam Dunkels <[email protected]> 32 * 33 * $Id: psock.h,v 1.3 2006/06/12 08:00:30 adam Exp $ 34 */ 35 36 /** 37 * \defgroup psock Protosockets library 38 * @{ 39 * 40 * The protosocket library provides an interface to the uIP stack that is 41 * similar to the traditional BSD socket interface. Unlike programs 42 * written for the ordinary uIP event-driven interface, programs 43 * written with the protosocket library are executed in a sequential 44 * fashion and does not have to be implemented as explicit state 45 * machines. 46 * 47 * Protosockets only work with TCP connections. 48 * 49 * The protosocket library uses \ref pt protothreads to provide 50 * sequential control flow. This makes the protosockets lightweight in 51 * terms of memory, but also means that protosockets inherits the 52 * functional limitations of protothreads. Each protosocket lives only 53 * within a single function. Automatic variables (stack variables) are 54 * not retained across a protosocket library function call. 55 * 56 * \note Because the protosocket library uses protothreads, local 57 * variables will not always be saved across a call to a protosocket 58 * library function. It is therefore advised that local variables are 59 * used with extreme care. 60 * 61 * The protosocket library provides functions for sending data without 62 * having to deal with retransmissions and acknowledgements, as well 63 * as functions for reading data without having to deal with data 64 * being split across more than one TCP segment. 65 * 66 * Because each protosocket runs as a protothread, the protosocket has to be 67 * started with a call to PSOCK_BEGIN() at the start of the function 68 * in which the protosocket is used. Similarly, the protosocket protothread can 69 * be terminated by a call to PSOCK_EXIT(). 70 * 71 */ 72 73 /** 74 * \file 75 * Protosocket library header file 76 * \author 77 * Adam Dunkels <[email protected]> 78 * 79 */ 80 81 #ifndef __PSOCK_H__ 82 #define __PSOCK_H__ 83 84 #include "uipopt.h" 85 #include "pt.h" 86 87 /* 88 * The structure that holds the state of a buffer. 89 * 90 * This structure holds the state of a uIP buffer. The structure has 91 * no user-visible elements, but is used through the functions 92 * provided by the library. 93 * 94 */ 95 struct psock_buf { 96 u8_t *ptr; 97 unsigned short left; 98 }; 99 100 /** 101 * The representation of a protosocket. 102 * 103 * The protosocket structrure is an opaque structure with no user-visible 104 * elements. 105 */ 106 struct psock { 107 struct pt pt, psockpt; /* Protothreads - one that's using the psock 108 functions, and one that runs inside the 109 psock functions. */ 110 const u8_t *sendptr; /* Pointer to the next data to be sent. */ 111 u8_t *readptr; /* Pointer to the next data to be read. */ 112 113 char *bufptr; /* Pointer to the buffer used for buffering 114 incoming data. */ 115 116 u16_t sendlen; /* The number of bytes left to be sent. */ 117 u16_t readlen; /* The number of bytes left to be read. */ 118 119 struct psock_buf buf; /* The structure holding the state of the 120 input buffer. */ 121 unsigned int bufsize; /* The size of the input buffer. */ 122 123 unsigned char state; /* The state of the protosocket. */ 124 }; 125 126 void psock_init(struct psock *psock, char *buffer, unsigned int buffersize); 127 /** 128 * Initialize a protosocket. 129 * 130 * This macro initializes a protosocket and must be called before the 131 * protosocket is used. The initialization also specifies the input buffer 132 * for the protosocket. 133 * 134 * \param psock (struct psock *) A pointer to the protosocket to be 135 * initialized 136 * 137 * \param buffer (char *) A pointer to the input buffer for the 138 * protosocket. 139 * 140 * \param buffersize (unsigned int) The size of the input buffer. 141 * 142 * \hideinitializer 143 */ 144 #define PSOCK_INIT(psock, buffer, buffersize) \ 145 psock_init(psock, buffer, buffersize) 146 147 /** 148 * Start the protosocket protothread in a function. 149 * 150 * This macro starts the protothread associated with the protosocket and 151 * must come before other protosocket calls in the function it is used. 152 * 153 * \param psock (struct psock *) A pointer to the protosocket to be 154 * started. 155 * 156 * \hideinitializer 157 */ 158 #define PSOCK_BEGIN(psock) PT_BEGIN(&((psock)->pt)) 159 160 PT_THREAD(psock_send(struct psock *psock, const char *buf, unsigned int len)); 161 /** 162 * Send data. 163 * 164 * This macro sends data over a protosocket. The protosocket protothread blocks 165 * until all data has been sent and is known to have been received by 166 * the remote end of the TCP connection. 167 * 168 * \param psock (struct psock *) A pointer to the protosocket over which 169 * data is to be sent. 170 * 171 * \param data (char *) A pointer to the data that is to be sent. 172 * 173 * \param datalen (unsigned int) The length of the data that is to be 174 * sent. 175 * 176 * \hideinitializer 177 */ 178 #define PSOCK_SEND(psock, data, datalen) \ 179 PT_WAIT_THREAD(&((psock)->pt), psock_send(psock, data, datalen)) 180 181 /** 182 * \brief Send a null-terminated string. 183 * \param psock Pointer to the protosocket. 184 * \param str The string to be sent. 185 * 186 * This function sends a null-terminated string over the 187 * protosocket. 188 * 189 * \hideinitializer 190 */ 191 #define PSOCK_SEND_STR(psock, str) \ 192 PT_WAIT_THREAD(&((psock)->pt), psock_send(psock, str, strlen(str))) 193 194 PT_THREAD(psock_generator_send(struct psock *psock, 195 unsigned short (*f)(void *), void *arg)); 196 197 /** 198 * \brief Generate data with a function and send it 199 * \param psock Pointer to the protosocket. 200 * \param generator Pointer to the generator function 201 * \param arg Argument to the generator function 202 * 203 * This function generates data and sends it over the 204 * protosocket. This can be used to dynamically generate 205 * data for a transmission, instead of generating the data 206 * in a buffer beforehand. This function reduces the need for 207 * buffer memory. The generator function is implemented by 208 * the application, and a pointer to the function is given 209 * as an argument with the call to PSOCK_GENERATOR_SEND(). 210 * 211 * The generator function should place the generated data 212 * directly in the uip_appdata buffer, and return the 213 * length of the generated data. The generator function is 214 * called by the protosocket layer when the data first is 215 * sent, and once for every retransmission that is needed. 216 * 217 * \hideinitializer 218 */ 219 #define PSOCK_GENERATOR_SEND(psock, generator, arg) \ 220 PT_WAIT_THREAD(&((psock)->pt), \ 221 psock_generator_send(psock, generator, arg)) 222 223 224 /** 225 * Close a protosocket. 226 * 227 * This macro closes a protosocket and can only be called from within the 228 * protothread in which the protosocket lives. 229 * 230 * \param psock (struct psock *) A pointer to the protosocket that is to 231 * be closed. 232 * 233 * \hideinitializer 234 */ 235 #define PSOCK_CLOSE(psock) uip_close() 236 237 PT_THREAD(psock_readbuf(struct psock *psock)); 238 /** 239 * Read data until the buffer is full. 240 * 241 * This macro will block waiting for data and read the data into the 242 * input buffer specified with the call to PSOCK_INIT(). Data is read 243 * until the buffer is full.. 244 * 245 * \param psock (struct psock *) A pointer to the protosocket from which 246 * data should be read. 247 * 248 * \hideinitializer 249 */ 250 #define PSOCK_READBUF(psock) \ 251 PT_WAIT_THREAD(&((psock)->pt), psock_readbuf(psock)) 252 253 PT_THREAD(psock_readto(struct psock *psock, unsigned char c)); 254 /** 255 * Read data up to a specified character. 256 * 257 * This macro will block waiting for data and read the data into the 258 * input buffer specified with the call to PSOCK_INIT(). Data is only 259 * read until the specifieed character appears in the data stream. 260 * 261 * \param psock (struct psock *) A pointer to the protosocket from which 262 * data should be read. 263 * 264 * \param c (char) The character at which to stop reading. 265 * 266 * \hideinitializer 267 */ 268 #define PSOCK_READTO(psock, c) \ 269 PT_WAIT_THREAD(&((psock)->pt), psock_readto(psock, c)) 270 271 /** 272 * The length of the data that was previously read. 273 * 274 * This macro returns the length of the data that was previously read 275 * using PSOCK_READTO() or PSOCK_READ(). 276 * 277 * \param psock (struct psock *) A pointer to the protosocket holding the data. 278 * 279 * \hideinitializer 280 */ 281 #define PSOCK_DATALEN(psock) psock_datalen(psock) 282 283 u16_t psock_datalen(struct psock *psock); 284 285 /** 286 * Exit the protosocket's protothread. 287 * 288 * This macro terminates the protothread of the protosocket and should 289 * almost always be used in conjunction with PSOCK_CLOSE(). 290 * 291 * \sa PSOCK_CLOSE_EXIT() 292 * 293 * \param psock (struct psock *) A pointer to the protosocket. 294 * 295 * \hideinitializer 296 */ 297 #define PSOCK_EXIT(psock) PT_EXIT(&((psock)->pt)) 298 299 /** 300 * Close a protosocket and exit the protosocket's protothread. 301 * 302 * This macro closes a protosocket and exits the protosocket's protothread. 303 * 304 * \param psock (struct psock *) A pointer to the protosocket. 305 * 306 * \hideinitializer 307 */ 308 #define PSOCK_CLOSE_EXIT(psock) \ 309 do { \ 310 PSOCK_CLOSE(psock); \ 311 PSOCK_EXIT(psock); \ 312 } while(0) 313 314 /** 315 * Declare the end of a protosocket's protothread. 316 * 317 * This macro is used for declaring that the protosocket's protothread 318 * ends. It must always be used together with a matching PSOCK_BEGIN() 319 * macro. 320 * 321 * \param psock (struct psock *) A pointer to the protosocket. 322 * 323 * \hideinitializer 324 */ 325 #define PSOCK_END(psock) PT_END(&((psock)->pt)) 326 327 char psock_newdata(struct psock *s); 328 329 /** 330 * Check if new data has arrived on a protosocket. 331 * 332 * This macro is used in conjunction with the PSOCK_WAIT_UNTIL() 333 * macro to check if data has arrived on a protosocket. 334 * 335 * \param psock (struct psock *) A pointer to the protosocket. 336 * 337 * \hideinitializer 338 */ 339 #define PSOCK_NEWDATA(psock) psock_newdata(psock) 340 341 /** 342 * Wait until a condition is true. 343 * 344 * This macro blocks the protothread until the specified condition is 345 * true. The macro PSOCK_NEWDATA() can be used to check if new data 346 * arrives when the protosocket is waiting. 347 * 348 * Typically, this macro is used as follows: 349 * 350 \code 351 PT_THREAD(thread(struct psock *s, struct timer *t)) 352 { 353 PSOCK_BEGIN(s); 354 355 PSOCK_WAIT_UNTIL(s, PSOCK_NEWADATA(s) || timer_expired(t)); 356 357 if(PSOCK_NEWDATA(s)) { 358 PSOCK_READTO(s, '\n'); 359 } else { 360 handle_timed_out(s); 361 } 362 363 PSOCK_END(s); 364 } 365 \endcode 366 * 367 * \param psock (struct psock *) A pointer to the protosocket. 368 * \param condition The condition to wait for. 369 * 370 * \hideinitializer 371 */ 372 #define PSOCK_WAIT_UNTIL(psock, condition) \ 373 PT_WAIT_UNTIL(&((psock)->pt), (condition)); 374 375 #define PSOCK_WAIT_THREAD(psock, condition) \ 376 PT_WAIT_THREAD(&((psock)->pt), (condition)) 377 378 #endif /* __PSOCK_H__ */ 379 380 /** @} */ 381