Contiki-Inga 3.x
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  */
44 
45 /**
46  * \file
47  * Header file for the Rime buffer (packetbuf) management
48  * \author
49  * Adam Dunkels <adam@sics.se>
50  */
51 
52 #ifndef PACKETBUF_H_
53 #define PACKETBUF_H_
54 
55 #include "contiki-conf.h"
56 #include "net/linkaddr.h"
57 
58 /**
59  * \brief The size of the packetbuf, in bytes
60  */
61 #ifdef PACKETBUF_CONF_SIZE
62 #define PACKETBUF_SIZE PACKETBUF_CONF_SIZE
63 #else
64 #define PACKETBUF_SIZE 128
65 #endif
66 
67 /**
68  * \brief The size of the packetbuf header, in bytes
69  */
70 #ifdef PACKETBUF_CONF_HDR_SIZE
71 #define PACKETBUF_HDR_SIZE PACKETBUF_CONF_HDR_SIZE
72 #else
73 #define PACKETBUF_HDR_SIZE 48
74 #endif
75 
76 /**
77  * \brief Clear and reset the packetbuf
78  *
79  * This function clears the packetbuf and resets all
80  * internal state pointers (header size, header pointer,
81  * external data pointer). It is used before preparing a
82  * packet in the packetbuf.
83  *
84  */
85 void packetbuf_clear(void);
86 
87 /**
88  * \brief Clear and reset the header of the packetbuf
89  *
90  * This function clears the header of the packetbuf and
91  * resets all the internal state pointers pertaining to
92  * the header (header size, header pointer, but not
93  * external data pointer). It is used before after sending
94  * a packet in the packetbuf, to be able to reuse the
95  * packet buffer for a later retransmission.
96  *
97  */
98 void packetbuf_clear_hdr(void);
99 
100 void packetbuf_hdr_remove(int bytes);
101 
102 /**
103  * \brief Get a pointer to the data in the packetbuf
104  * \return Pointer to the packetbuf data
105  *
106  * This function is used to get a pointer to the data in
107  * the packetbuf. The data is either stored in the packetbuf,
108  * or referenced to an external location.
109  *
110  * For outbound packets, the packetbuf consists of two
111  * parts: header and data. The header is accessed with the
112  * packetbuf_hdrptr() function.
113  *
114  * For incoming packets, both the packet header and the
115  * packet data is stored in the data portion of the
116  * packetbuf. Thus this function is used to get a pointer to
117  * the header for incoming packets.
118  *
119  */
120 void *packetbuf_dataptr(void);
121 
122 /**
123  * \brief Get a pointer to the header in the packetbuf, for outbound packets
124  * \return Pointer to the packetbuf header
125  *
126  * For outbound packets, the packetbuf consists of two
127  * parts: header and data. This function is used to get a
128  * pointer to the header in the packetbuf. The header is
129  * stored in the packetbuf.
130  *
131  */
132 void *packetbuf_hdrptr(void);
133 
134 /**
135  * \brief Get the length of the header in the packetbuf, for outbound packets
136  * \return Length of the header in the packetbuf
137  *
138  * For outbound packets, the packetbuf consists of two
139  * parts: header and data. This function is used to get
140  * the length of the header in the packetbuf. The header is
141  * stored in the packetbuf and accessed via the
142  * packetbuf_hdrptr() function.
143  *
144  */
145 uint8_t packetbuf_hdrlen(void);
146 
147 
148 /**
149  * \brief Get the length of the data in the packetbuf
150  * \return Length of the data in the packetbuf
151  *
152  * For outbound packets, the packetbuf consists of two
153  * parts: header and data. This function is used to get
154  * the length of the data in the packetbuf. The data is
155  * stored in the packetbuf and accessed via the
156  * packetbuf_dataptr() function.
157  *
158  * For incoming packets, both the packet header and the
159  * packet data is stored in the data portion of the
160  * packetbuf. This function is then used to get the total
161  * length of the packet - both header and data.
162  *
163  */
164 uint16_t packetbuf_datalen(void);
165 
166 /**
167  * \brief Get the total length of the header and data in the packetbuf
168  * \return Length of data and header in the packetbuf
169  *
170  */
171 uint16_t packetbuf_totlen(void);
172 
173 /**
174  * \brief Set the length of the data in the packetbuf
175  * \param len The length of the data
176  *
177  * For outbound packets, the packetbuf consists of two
178  * parts: header and data. This function is used to set
179  * the length of the data in the packetbuf.
180  */
181 void packetbuf_set_datalen(uint16_t len);
182 
183 /**
184  * \brief Point the packetbuf to external data
185  * \param ptr A pointer to the external data
186  * \param len The length of the external data
187  *
188  * For outbound packets, the packetbuf consists of two
189  * parts: header and data. This function is used to make
190  * the packetbuf point to external data. The function also
191  * specifies the length of the external data that the
192  * packetbuf references.
193  */
194 void packetbuf_reference(void *ptr, uint16_t len);
195 
196 /**
197  * \brief Check if the packetbuf references external data
198  * \retval Non-zero if the packetbuf references external data, zero otherwise.
199  *
200  * For outbound packets, the packetbuf consists of two
201  * parts: header and data. This function is used to check
202  * if the packetbuf points to external data that has
203  * previously been referenced with packetbuf_reference().
204  *
205  */
206 int packetbuf_is_reference(void);
207 
208 /**
209  * \brief Get a pointer to external data referenced by the packetbuf
210  * \retval A pointer to the external data
211  *
212  * For outbound packets, the packetbuf consists of two
213  * parts: header and data. The data may point to external
214  * data that has previously been referenced with
215  * packetbuf_reference(). This function is used to get a
216  * pointer to the external data.
217  *
218  */
219 void *packetbuf_reference_ptr(void);
220 
221 /**
222  * \brief Compact the packetbuf
223  *
224  * This function compacts the packetbuf by copying the data
225  * portion of the packetbuf so that becomes consecutive to
226  * the header. It also copies external data that has
227  * previously been referenced with packetbuf_reference()
228  * into the packetbuf.
229  *
230  * This function is called by the Rime code before a
231  * packet is to be sent by a device driver. This assures
232  * that the entire packet is consecutive in memory.
233  *
234  */
235 void packetbuf_compact(void);
236 
237 /**
238  * \brief Copy from external data into the packetbuf
239  * \param from A pointer to the data from which to copy
240  * \param len The size of the data to copy
241  * \retval The number of bytes that was copied into the packetbuf
242  *
243  * This function copies data from a pointer into the
244  * packetbuf. If the data that is to be copied is larger
245  * than the packetbuf, only the data that fits in the
246  * packetbuf is copied. The number of bytes that could be
247  * copied into the rimbuf is returned.
248  *
249  */
250 int packetbuf_copyfrom(const void *from, uint16_t len);
251 
252 /**
253  * \brief Copy the entire packetbuf to an external buffer
254  * \param to A pointer to the buffer to which the data is to be copied
255  * \retval The number of bytes that was copied to the external buffer
256  *
257  * This function copies the packetbuf to an external
258  * buffer. Both the data portion and the header portion of
259  * the packetbuf is copied. If the packetbuf referenced
260  * external data (referenced with packetbuf_reference()) the
261  * external data is copied.
262  *
263  * The external buffer to which the packetbuf is to be
264  * copied must be able to accomodate at least
265  * (PACKETBUF_SIZE + PACKETBUF_HDR_SIZE) bytes. The number of
266  * bytes that was copied to the external buffer is
267  * returned.
268  *
269  */
270 int packetbuf_copyto(void *to);
271 
272 /**
273  * \brief Copy the header portion of the packetbuf to an external buffer
274  * \param to A pointer to the buffer to which the data is to be copied
275  * \retval The number of bytes that was copied to the external buffer
276  *
277  * This function copies the header portion of the packetbuf
278  * to an external buffer.
279  *
280  * The external buffer to which the packetbuf is to be
281  * copied must be able to accomodate at least
282  * PACKETBUF_HDR_SIZE bytes. The number of bytes that was
283  * copied to the external buffer is returned.
284  *
285  */
286 int packetbuf_copyto_hdr(uint8_t *to);
287 
288 /**
289  * \brief Extend the header of the packetbuf, for outbound packets
290  * \param size The number of bytes the header should be extended
291  * \retval Non-zero if the header could be extended, zero otherwise
292  *
293  * This function is used to allocate extra space in the
294  * header portion in the packetbuf, when preparing outbound
295  * packets for transmission. If the function is unable to
296  * allocate sufficient header space, the function returns
297  * zero and does not allocate anything.
298  *
299  */
300 int packetbuf_hdralloc(int size);
301 
302 /**
303  * \brief Reduce the header in the packetbuf, for incoming packets
304  * \param size The number of bytes the header should be reduced
305  * \retval Non-zero if the header could be reduced, zero otherwise
306  *
307  * This function is used to remove the first part of the
308  * header in the packetbuf, when processing incoming
309  * packets. If the function is unable to remove the
310  * requested amount of header space, the function returns
311  * zero and does not allocate anything.
312  *
313  */
314 int packetbuf_hdrreduce(int size);
315 
316 /* Packet attributes stuff below: */
317 
318 typedef uint16_t packetbuf_attr_t;
319 
320 struct packetbuf_attr {
321 /* uint8_t type; */
322  packetbuf_attr_t val;
323 };
324 struct packetbuf_addr {
325 /* uint8_t type; */
326  linkaddr_t addr;
327 };
328 
329 #define PACKETBUF_ATTR_PACKET_TYPE_DATA 0
330 #define PACKETBUF_ATTR_PACKET_TYPE_ACK 1
331 #define PACKETBUF_ATTR_PACKET_TYPE_STREAM 2
332 #define PACKETBUF_ATTR_PACKET_TYPE_STREAM_END 3
333 #define PACKETBUF_ATTR_PACKET_TYPE_TIMESTAMP 4
334 
335 enum {
336  PACKETBUF_ATTR_NONE,
337 
338  /* Scope 0 attributes: used only on the local node. */
339  PACKETBUF_ATTR_CHANNEL,
340  PACKETBUF_ATTR_NETWORK_ID,
341  PACKETBUF_ATTR_LINK_QUALITY,
342  PACKETBUF_ATTR_RSSI,
343  PACKETBUF_ATTR_TIMESTAMP,
344  PACKETBUF_ATTR_RADIO_TXPOWER,
345  PACKETBUF_ATTR_LISTEN_TIME,
346  PACKETBUF_ATTR_TRANSMIT_TIME,
347  PACKETBUF_ATTR_MAX_MAC_TRANSMISSIONS,
348  PACKETBUF_ATTR_MAC_SEQNO,
349  PACKETBUF_ATTR_MAC_ACK,
350 
351  /* Scope 1 attributes: used between two neighbors only. */
352  PACKETBUF_ATTR_RELIABLE,
353  PACKETBUF_ATTR_PACKET_ID,
354  PACKETBUF_ATTR_PACKET_TYPE,
355  PACKETBUF_ATTR_REXMIT,
356  PACKETBUF_ATTR_MAX_REXMIT,
357  PACKETBUF_ATTR_NUM_REXMIT,
358  PACKETBUF_ATTR_PENDING,
359 
360  /* Scope 2 attributes: used between end-to-end nodes. */
361  PACKETBUF_ATTR_HOPS,
362  PACKETBUF_ATTR_TTL,
363  PACKETBUF_ATTR_EPACKET_ID,
364  PACKETBUF_ATTR_EPACKET_TYPE,
365  PACKETBUF_ATTR_ERELIABLE,
366 
367  /* These must be last */
368  PACKETBUF_ADDR_SENDER,
369  PACKETBUF_ADDR_RECEIVER,
370  PACKETBUF_ADDR_ESENDER,
371  PACKETBUF_ADDR_ERECEIVER,
372 
373  PACKETBUF_ATTR_MAX
374 };
375 
376 #define PACKETBUF_NUM_ADDRS 4
377 #define PACKETBUF_NUM_ATTRS (PACKETBUF_ATTR_MAX - PACKETBUF_NUM_ADDRS)
378 #define PACKETBUF_ADDR_FIRST PACKETBUF_ADDR_SENDER
379 
380 #define PACKETBUF_IS_ADDR(type) ((type) >= PACKETBUF_ADDR_FIRST)
381 
382 #if PACKETBUF_CONF_ATTRS_INLINE
383 
384 extern struct packetbuf_attr packetbuf_attrs[];
385 extern struct packetbuf_addr packetbuf_addrs[];
386 
387 static int packetbuf_set_attr(uint8_t type, const packetbuf_attr_t val);
388 static packetbuf_attr_t packetbuf_attr(uint8_t type);
389 static int packetbuf_set_addr(uint8_t type, const linkaddr_t *addr);
390 static const linkaddr_t *packetbuf_addr(uint8_t type);
391 
392 static inline int
393 packetbuf_set_attr(uint8_t type, const packetbuf_attr_t val)
394 {
395 /* packetbuf_attrs[type].type = type; */
396  packetbuf_attrs[type].val = val;
397  return 1;
398 }
399 static inline packetbuf_attr_t
400 packetbuf_attr(uint8_t type)
401 {
402  return packetbuf_attrs[type].val;
403 }
404 
405 static inline int
406 packetbuf_set_addr(uint8_t type, const linkaddr_t *addr)
407 {
408 /* packetbuf_addrs[type - PACKETBUF_ADDR_FIRST].type = type; */
409  linkaddr_copy(&packetbuf_addrs[type - PACKETBUF_ADDR_FIRST].addr, addr);
410  return 1;
411 }
412 
413 static inline const linkaddr_t *
414 packetbuf_addr(uint8_t type)
415 {
416  return &packetbuf_addrs[type - PACKETBUF_ADDR_FIRST].addr;
417 }
418 #else /* PACKETBUF_CONF_ATTRS_INLINE */
419 int packetbuf_set_attr(uint8_t type, const packetbuf_attr_t val);
420 packetbuf_attr_t packetbuf_attr(uint8_t type);
421 int packetbuf_set_addr(uint8_t type, const linkaddr_t *addr);
422 const linkaddr_t *packetbuf_addr(uint8_t type);
423 #endif /* PACKETBUF_CONF_ATTRS_INLINE */
424 
425 void packetbuf_attr_clear(void);
426 
427 void packetbuf_attr_copyto(struct packetbuf_attr *attrs,
428  struct packetbuf_addr *addrs);
429 void packetbuf_attr_copyfrom(struct packetbuf_attr *attrs,
430  struct packetbuf_addr *addrs);
431 
432 #define PACKETBUF_ATTRIBUTES(...) { __VA_ARGS__ PACKETBUF_ATTR_LAST }
433 #define PACKETBUF_ATTR_LAST { PACKETBUF_ATTR_NONE, 0 }
434 
435 #define PACKETBUF_ATTR_BIT 1
436 #define PACKETBUF_ATTR_BYTE 8
437 #define PACKETBUF_ADDRSIZE (sizeof(linkaddr_t) * PACKETBUF_ATTR_BYTE)
438 
439 struct packetbuf_attrlist {
440  uint8_t type;
441  uint8_t len;
442 };
443 
444 #endif /* PACKETBUF_H_ */
445 /** @} */
446 /** @} */
Generated on Thu Apr 24 2014 16:26:12 for Contiki-Inga 3.x by   doxygen 1.8.3.1