OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [freertos-6.1.1/] [Demo/] [Common/] [ethernet/] [FreeRTOS-uIP/] [psock.h] - Blame information for rev 606

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 606 jeremybenn
/*
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 <adam@sics.se>
32
 *
33
 * $Id: psock.h 2 2011-07-17 20:13:17Z filepang@gmail.com $
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 <adam@sics.se>
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
/** @} */

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.