Contiki 2.5
packetbuf.h
Go to the documentation of this file.
1 /**
2  * \addtogroup rime
3  * @{
4  */
5 
6 /**
7  * \defgroup packetbuf Rime buffer management
8  * @{
9  *
10  * The packetbuf module does Rime's buffer management.
11  */
12 
13 /*
14  * Copyright (c) 2006, Swedish Institute of Computer Science.
15  * All rights reserved.
16  *
17  * Redistribution and use in source and binary forms, with or without
18  * modification, are permitted provided that the following conditions
19  * are met:
20  * 1. Redistributions of source code must retain the above copyright
21  * notice, this list of conditions and the following disclaimer.
22  * 2. Redistributions in binary form must reproduce the above copyright
23  * notice, this list of conditions and the following disclaimer in the
24  * documentation and/or other materials provided with the distribution.
25  * 3. Neither the name of the Institute nor the names of its contributors
26  * may be used to endorse or promote products derived from this software
27  * without specific prior written permission.
28  *
29  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
30  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
31  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
32  * ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
33  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
34  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
35  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
36  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
37  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
38  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
39  * SUCH DAMAGE.
40  *
41  * This file is part of the Contiki operating system.
42  *
43  * $Id: packetbuf.h,v 1.2 2010/12/16 22:41:43 adamdunkels Exp $
44  */
45 
46 /**
47  * \file
48  * Header file for the Rime buffer (packetbuf) management
49  * \author
50  * Adam Dunkels <adam@sics.se>
51  */
52 
53 #ifndef __PACKETBUF_H__
54 #define __PACKETBUF_H__
55 
56 #include "contiki-conf.h"
57 #include "net/rime/rimeaddr.h"
58 
59 /**
60  * \brief The size of the packetbuf, in bytes
61  */
62 #ifdef PACKETBUF_CONF_SIZE
63 #define PACKETBUF_SIZE PACKETBUF_CONF_SIZE
64 #else
65 #define PACKETBUF_SIZE 128
66 #endif
67 
68 /**
69  * \brief The size of the packetbuf header, in bytes
70  */
71 #ifdef PACKETBUF_CONF_HDR_SIZE
72 #define PACKETBUF_HDR_SIZE PACKETBUF_CONF_HDR_SIZE
73 #else
74 #define PACKETBUF_HDR_SIZE 48
75 #endif
76 
77 /**
78  * \brief Clear and reset the packetbuf
79  *
80  * This function clears the packetbuf and resets all
81  * internal state pointers (header size, header pointer,
82  * external data pointer). It is used before preparing a
83  * packet in the packetbuf.
84  *
85  */
86 void packetbuf_clear(void);
87 
88 /**
89  * \brief Clear and reset the header of the packetbuf
90  *
91  * This function clears the header of the packetbuf and
92  * resets all the internal state pointers pertaining to
93  * the header (header size, header pointer, but not
94  * external data pointer). It is used before after sending
95  * a packet in the packetbuf, to be able to reuse the
96  * packet buffer for a later retransmission.
97  *
98  */
99 void packetbuf_clear_hdr(void);
100 
101 void packetbuf_hdr_remove(int bytes);
102 
103 /**
104  * \brief Get a pointer to the data in the packetbuf
105  * \return Pointer to the packetbuf data
106  *
107  * This function is used to get a pointer to the data in
108  * the packetbuf. The data is either stored in the packetbuf,
109  * or referenced to an external location.
110  *
111  * For outbound packets, the packetbuf consists of two
112  * parts: header and data. The header is accessed with the
113  * packetbuf_hdrptr() function.
114  *
115  * For incoming packets, both the packet header and the
116  * packet data is stored in the data portion of the
117  * packetbuf. Thus this function is used to get a pointer to
118  * the header for incoming packets.
119  *
120  */
121 void *packetbuf_dataptr(void);
122 
123 /**
124  * \brief Get a pointer to the header in the packetbuf, for outbound packets
125  * \return Pointer to the packetbuf header
126  *
127  * For outbound packets, the packetbuf consists of two
128  * parts: header and data. This function is used to get a
129  * pointer to the header in the packetbuf. The header is
130  * stored in the packetbuf.
131  *
132  */
133 void *packetbuf_hdrptr(void);
134 
135 /**
136  * \brief Get the length of the header in the packetbuf, for outbound packets
137  * \return Length of the header in the packetbuf
138  *
139  * For outbound packets, the packetbuf consists of two
140  * parts: header and data. This function is used to get
141  * the length of the header in the packetbuf. The header is
142  * stored in the packetbuf and accessed via the
143  * packetbuf_hdrptr() function.
144  *
145  */
146 uint8_t packetbuf_hdrlen(void);
147 
148 
149 /**
150  * \brief Get the length of the data in the packetbuf
151  * \return Length of the data in the packetbuf
152  *
153  * For outbound packets, the packetbuf consists of two
154  * parts: header and data. This function is used to get
155  * the length of the data in the packetbuf. The data is
156  * stored in the packetbuf and accessed via the
157  * packetbuf_dataptr() function.
158  *
159  * For incoming packets, both the packet header and the
160  * packet data is stored in the data portion of the
161  * packetbuf. This function is then used to get the total
162  * length of the packet - both header and data.
163  *
164  */
165 uint16_t packetbuf_datalen(void);
166 
167 /**
168  * \brief Get the total length of the header and data in the packetbuf
169  * \return Length of data and header in the packetbuf
170  *
171  */
172 uint16_t packetbuf_totlen(void);
173 
174 /**
175  * \brief Set the length of the data in the packetbuf
176  * \param len The length of the data
177  *
178  * For outbound packets, the packetbuf consists of two
179  * parts: header and data. This function is used to set
180  * the length of the data in the packetbuf.
181  */
182 void packetbuf_set_datalen(uint16_t len);
183 
184 /**
185  * \brief Point the packetbuf to external data
186  * \param ptr A pointer to the external data
187  * \param len The length of the external data
188  *
189  * For outbound packets, the packetbuf consists of two
190  * parts: header and data. This function is used to make
191  * the packetbuf point to external data. The function also
192  * specifies the length of the external data that the
193  * packetbuf references.
194  */
195 void packetbuf_reference(void *ptr, uint16_t len);
196 
197 /**
198  * \brief Check if the packetbuf references external data
199  * \retval Non-zero if the packetbuf references external data, zero otherwise.
200  *
201  * For outbound packets, the packetbuf consists of two
202  * parts: header and data. This function is used to check
203  * if the packetbuf points to external data that has
204  * previously been referenced with packetbuf_reference().
205  *
206  */
207 int packetbuf_is_reference(void);
208 
209 /**
210  * \brief Get a pointer to external data referenced by the packetbuf
211  * \retval A pointer to the external data
212  *
213  * For outbound packets, the packetbuf consists of two
214  * parts: header and data. The data may point to external
215  * data that has previously been referenced with
216  * packetbuf_reference(). This function is used to get a
217  * pointer to the external data.
218  *
219  */
220 void *packetbuf_reference_ptr(void);
221 
222 /**
223  * \brief Compact the packetbuf
224  *
225  * This function compacts the packetbuf by copying the data
226  * portion of the packetbuf so that becomes consecutive to
227  * the header. It also copies external data that has
228  * previously been referenced with packetbuf_reference()
229  * into the packetbuf.
230  *
231  * This function is called by the Rime code before a
232  * packet is to be sent by a device driver. This assures
233  * that the entire packet is consecutive in memory.
234  *
235  */
236 void packetbuf_compact(void);
237 
238 /**
239  * \brief Copy from external data into the packetbuf
240  * \param from A pointer to the data from which to copy
241  * \param len The size of the data to copy
242  * \retval The number of bytes that was copied into the packetbuf
243  *
244  * This function copies data from a pointer into the
245  * packetbuf. If the data that is to be copied is larger
246  * than the packetbuf, only the data that fits in the
247  * packetbuf is copied. The number of bytes that could be
248  * copied into the rimbuf is returned.
249  *
250  */
251 int packetbuf_copyfrom(const void *from, uint16_t len);
252 
253 /**
254  * \brief Copy the entire packetbuf to an external buffer
255  * \param to A pointer to the buffer to which the data is to be copied
256  * \retval The number of bytes that was copied to the external buffer
257  *
258  * This function copies the packetbuf to an external
259  * buffer. Both the data portion and the header portion of
260  * the packetbuf is copied. If the packetbuf referenced
261  * external data (referenced with packetbuf_reference()) the
262  * external data is copied.
263  *
264  * The external buffer to which the packetbuf is to be
265  * copied must be able to accomodate at least
266  * (PACKETBUF_SIZE + PACKETBUF_HDR_SIZE) bytes. The number of
267  * bytes that was copied to the external buffer is
268  * returned.
269  *
270  */
271 int packetbuf_copyto(void *to);
272 
273 /**
274  * \brief Copy the header portion of the packetbuf to an external buffer
275  * \param to A pointer to the buffer to which the data is to be copied
276  * \retval The number of bytes that was copied to the external buffer
277  *
278  * This function copies the header portion of the packetbuf
279  * to an external buffer.
280  *
281  * The external buffer to which the packetbuf is to be
282  * copied must be able to accomodate at least
283  * PACKETBUF_HDR_SIZE bytes. The number of bytes that was
284  * copied to the external buffer is returned.
285  *
286  */
287 int packetbuf_copyto_hdr(uint8_t *to);
288 
289 /**
290  * \brief Extend the header of the packetbuf, for outbound packets
291  * \param size The number of bytes the header should be extended
292  * \retval Non-zero if the header could be extended, zero otherwise
293  *
294  * This function is used to allocate extra space in the
295  * header portion in the packetbuf, when preparing outbound
296  * packets for transmission. If the function is unable to
297  * allocate sufficient header space, the function returns
298  * zero and does not allocate anything.
299  *
300  */
301 int packetbuf_hdralloc(int size);
302 
303 /**
304  * \brief Reduce the header in the packetbuf, for incoming packets
305  * \param size The number of bytes the header should be reduced
306  * \retval Non-zero if the header could be reduced, zero otherwise
307  *
308  * This function is used to remove the first part of the
309  * header in the packetbuf, when processing incoming
310  * packets. If the function is unable to remove the
311  * requested amount of header space, the function returns
312  * zero and does not allocate anything.
313  *
314  */
315 int packetbuf_hdrreduce(int size);
316 
317 /* Packet attributes stuff below: */
318 
319 typedef uint16_t packetbuf_attr_t;
320 
321 struct packetbuf_attr {
322 /* uint8_t type; */
323  packetbuf_attr_t val;
324 };
325 struct packetbuf_addr {
326 /* uint8_t type; */
327  rimeaddr_t addr;
328 };
329 
330 #define PACKETBUF_ATTR_PACKET_TYPE_DATA 0
331 #define PACKETBUF_ATTR_PACKET_TYPE_ACK 1
332 #define PACKETBUF_ATTR_PACKET_TYPE_STREAM 2
333 #define PACKETBUF_ATTR_PACKET_TYPE_STREAM_END 3
334 #define PACKETBUF_ATTR_PACKET_TYPE_TIMESTAMP 4
335 
336 enum {
337  PACKETBUF_ATTR_NONE,
338 
339  /* Scope 0 attributes: used only on the local node. */
340  PACKETBUF_ATTR_CHANNEL,
341  PACKETBUF_ATTR_NETWORK_ID,
342  PACKETBUF_ATTR_LINK_QUALITY,
343  PACKETBUF_ATTR_RSSI,
344  PACKETBUF_ATTR_TIMESTAMP,
345  PACKETBUF_ATTR_RADIO_TXPOWER,
346  PACKETBUF_ATTR_LISTEN_TIME,
347  PACKETBUF_ATTR_TRANSMIT_TIME,
348  PACKETBUF_ATTR_MAX_MAC_TRANSMISSIONS,
349  PACKETBUF_ATTR_MAC_SEQNO,
350  PACKETBUF_ATTR_MAC_ACK,
351 
352  /* Scope 1 attributes: used between two neighbors only. */
353  PACKETBUF_ATTR_RELIABLE,
354  PACKETBUF_ATTR_PACKET_ID,
355  PACKETBUF_ATTR_PACKET_TYPE,
356  PACKETBUF_ATTR_REXMIT,
357  PACKETBUF_ATTR_MAX_REXMIT,
358  PACKETBUF_ATTR_NUM_REXMIT,
359  PACKETBUF_ATTR_PENDING,
360 
361  /* Scope 2 attributes: used between end-to-end nodes. */
362  PACKETBUF_ATTR_HOPS,
363  PACKETBUF_ATTR_TTL,
364  PACKETBUF_ATTR_EPACKET_ID,
365  PACKETBUF_ATTR_EPACKET_TYPE,
366  PACKETBUF_ATTR_ERELIABLE,
367 
368  /* These must be last */
369  PACKETBUF_ADDR_SENDER,
370  PACKETBUF_ADDR_RECEIVER,
371  PACKETBUF_ADDR_ESENDER,
372  PACKETBUF_ADDR_ERECEIVER,
373 
374  PACKETBUF_ATTR_MAX
375 };
376 
377 #define PACKETBUF_NUM_ADDRS 4
378 #define PACKETBUF_NUM_ATTRS (PACKETBUF_ATTR_MAX - PACKETBUF_NUM_ADDRS)
379 #define PACKETBUF_ADDR_FIRST PACKETBUF_ADDR_SENDER
380 
381 #define PACKETBUF_IS_ADDR(type) ((type) >= PACKETBUF_ADDR_FIRST)
382 
383 #if PACKETBUF_CONF_ATTRS_INLINE
384 
385 extern struct packetbuf_attr packetbuf_attrs[];
386 extern struct packetbuf_addr packetbuf_addrs[];
387 
388 static int packetbuf_set_attr(uint8_t type, const packetbuf_attr_t val);
389 static packetbuf_attr_t packetbuf_attr(uint8_t type);
390 static int packetbuf_set_addr(uint8_t type, const rimeaddr_t *addr);
391 static const rimeaddr_t *packetbuf_addr(uint8_t type);
392 
393 static inline int
394 packetbuf_set_attr(uint8_t type, const packetbuf_attr_t val)
395 {
396 /* packetbuf_attrs[type].type = type; */
397  packetbuf_attrs[type].val = val;
398  return 1;
399 }
400 static inline packetbuf_attr_t
401 packetbuf_attr(uint8_t type)
402 {
403  return packetbuf_attrs[type].val;
404 }
405 
406 static inline int
407 packetbuf_set_addr(uint8_t type, const rimeaddr_t *addr)
408 {
409 /* packetbuf_addrs[type - PACKETBUF_ADDR_FIRST].type = type; */
410  rimeaddr_copy(&packetbuf_addrs[type - PACKETBUF_ADDR_FIRST].addr, addr);
411  return 1;
412 }
413 
414 static inline const rimeaddr_t *
415 packetbuf_addr(uint8_t type)
416 {
417  return &packetbuf_addrs[type - PACKETBUF_ADDR_FIRST].addr;
418 }
419 #else /* PACKETBUF_CONF_ATTRS_INLINE */
420 int packetbuf_set_attr(uint8_t type, const packetbuf_attr_t val);
421 packetbuf_attr_t packetbuf_attr(uint8_t type);
422 int packetbuf_set_addr(uint8_t type, const rimeaddr_t *addr);
423 const rimeaddr_t *packetbuf_addr(uint8_t type);
424 #endif /* PACKETBUF_CONF_ATTRS_INLINE */
425 
426 void packetbuf_attr_clear(void);
427 
428 void packetbuf_attr_copyto(struct packetbuf_attr *attrs,
429  struct packetbuf_addr *addrs);
430 void packetbuf_attr_copyfrom(struct packetbuf_attr *attrs,
431  struct packetbuf_addr *addrs);
432 
433 #define PACKETBUF_ATTRIBUTES(...) { __VA_ARGS__ PACKETBUF_ATTR_LAST }
434 #define PACKETBUF_ATTR_LAST { PACKETBUF_ATTR_NONE, 0 }
435 
436 #define PACKETBUF_ATTR_BIT 1
437 #define PACKETBUF_ATTR_BYTE 8
438 #define PACKETBUF_ADDRSIZE (sizeof(rimeaddr_t) * PACKETBUF_ATTR_BYTE)
439 
440 struct packetbuf_attrlist {
441  uint8_t type;
442  uint8_t len;
443 };
444 
445 #endif /* __PACKETBUF_H__ */
446 /** @} */
447 /** @} */
Generated on Fri Aug 30 2013 12:34:05 for Contiki 2.5 by   doxygen 1.8.3.1