Contiki 2.6

packetbuf.h

Go to the documentation of this file.
00001 /**
00002  * \addtogroup rime
00003  * @{
00004  */
00005 
00006 /**
00007  * \defgroup packetbuf Rime buffer management
00008  * @{
00009  *
00010  * The packetbuf module does Rime's buffer management.
00011  */
00012 
00013 /*
00014  * Copyright (c) 2006, Swedish Institute of Computer Science.
00015  * All rights reserved.
00016  *
00017  * Redistribution and use in source and binary forms, with or without
00018  * modification, are permitted provided that the following conditions
00019  * are met:
00020  * 1. Redistributions of source code must retain the above copyright
00021  *    notice, this list of conditions and the following disclaimer.
00022  * 2. Redistributions in binary form must reproduce the above copyright
00023  *    notice, this list of conditions and the following disclaimer in the
00024  *    documentation and/or other materials provided with the distribution.
00025  * 3. Neither the name of the Institute nor the names of its contributors
00026  *    may be used to endorse or promote products derived from this software
00027  *    without specific prior written permission.
00028  *
00029  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
00030  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00031  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00032  * ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
00033  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00034  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
00035  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
00036  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
00037  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
00038  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
00039  * SUCH DAMAGE.
00040  *
00041  * This file is part of the Contiki operating system.
00042  *
00043  * $Id: packetbuf.h,v 1.2 2010/12/16 22:41:43 adamdunkels Exp $
00044  */
00045 
00046 /**
00047  * \file
00048  *         Header file for the Rime buffer (packetbuf) management
00049  * \author
00050  *         Adam Dunkels <adam@sics.se>
00051  */
00052 
00053 #ifndef __PACKETBUF_H__
00054 #define __PACKETBUF_H__
00055 
00056 #include "contiki-conf.h"
00057 #include "net/rime/rimeaddr.h"
00058 
00059 /**
00060  * \brief      The size of the packetbuf, in bytes
00061  */
00062 #ifdef PACKETBUF_CONF_SIZE
00063 #define PACKETBUF_SIZE PACKETBUF_CONF_SIZE
00064 #else
00065 #define PACKETBUF_SIZE 128
00066 #endif
00067 
00068 /**
00069  * \brief      The size of the packetbuf header, in bytes
00070  */
00071 #ifdef PACKETBUF_CONF_HDR_SIZE
00072 #define PACKETBUF_HDR_SIZE PACKETBUF_CONF_HDR_SIZE
00073 #else
00074 #define PACKETBUF_HDR_SIZE 48
00075 #endif
00076 
00077 /**
00078  * \brief      Clear and reset the packetbuf
00079  *
00080  *             This function clears the packetbuf and resets all
00081  *             internal state pointers (header size, header pointer,
00082  *             external data pointer). It is used before preparing a
00083  *             packet in the packetbuf.
00084  *
00085  */
00086 void packetbuf_clear(void);
00087 
00088 /**
00089  * \brief      Clear and reset the header of the packetbuf
00090  *
00091  *             This function clears the header of the packetbuf and
00092  *             resets all the internal state pointers pertaining to
00093  *             the header (header size, header pointer, but not
00094  *             external data pointer). It is used before after sending
00095  *             a packet in the packetbuf, to be able to reuse the
00096  *             packet buffer for a later retransmission.
00097  *
00098  */
00099 void packetbuf_clear_hdr(void);
00100 
00101 void packetbuf_hdr_remove(int bytes);
00102 
00103 /**
00104  * \brief      Get a pointer to the data in the packetbuf
00105  * \return     Pointer to the packetbuf data
00106  *
00107  *             This function is used to get a pointer to the data in
00108  *             the packetbuf. The data is either stored in the packetbuf,
00109  *             or referenced to an external location.
00110  *
00111  *             For outbound packets, the packetbuf consists of two
00112  *             parts: header and data. The header is accessed with the
00113  *             packetbuf_hdrptr() function.
00114  *
00115  *             For incoming packets, both the packet header and the
00116  *             packet data is stored in the data portion of the
00117  *             packetbuf. Thus this function is used to get a pointer to
00118  *             the header for incoming packets.
00119  *
00120  */
00121 void *packetbuf_dataptr(void);
00122 
00123 /**
00124  * \brief      Get a pointer to the header in the packetbuf, for outbound packets
00125  * \return     Pointer to the packetbuf header
00126  *
00127  *             For outbound packets, the packetbuf consists of two
00128  *             parts: header and data. This function is used to get a
00129  *             pointer to the header in the packetbuf. The header is
00130  *             stored in the packetbuf.
00131  *
00132  */
00133 void *packetbuf_hdrptr(void);
00134 
00135 /**
00136  * \brief      Get the length of the header in the packetbuf, for outbound packets
00137  * \return     Length of the header in the packetbuf
00138  *
00139  *             For outbound packets, the packetbuf consists of two
00140  *             parts: header and data. This function is used to get
00141  *             the length of the header in the packetbuf. The header is
00142  *             stored in the packetbuf and accessed via the
00143  *             packetbuf_hdrptr() function.
00144  *
00145  */
00146 uint8_t packetbuf_hdrlen(void);
00147 
00148 
00149 /**
00150  * \brief      Get the length of the data in the packetbuf
00151  * \return     Length of the data in the packetbuf
00152  *
00153  *             For outbound packets, the packetbuf consists of two
00154  *             parts: header and data. This function is used to get
00155  *             the length of the data in the packetbuf. The data is
00156  *             stored in the packetbuf and accessed via the
00157  *             packetbuf_dataptr() function.
00158  *
00159  *             For incoming packets, both the packet header and the
00160  *             packet data is stored in the data portion of the
00161  *             packetbuf. This function is then used to get the total
00162  *             length of the packet - both header and data.
00163  *
00164  */
00165 uint16_t packetbuf_datalen(void);
00166 
00167 /**
00168  * \brief      Get the total length of the header and data in the packetbuf
00169  * \return     Length of data and header in the packetbuf
00170  *
00171  */
00172 uint16_t packetbuf_totlen(void);
00173 
00174 /**
00175  * \brief      Set the length of the data in the packetbuf
00176  * \param len  The length of the data
00177  *
00178  *             For outbound packets, the packetbuf consists of two
00179  *             parts: header and data. This function is used to set
00180  *             the length of the data in the packetbuf.
00181  */
00182 void packetbuf_set_datalen(uint16_t len);
00183 
00184 /**
00185  * \brief      Point the packetbuf to external data
00186  * \param ptr  A pointer to the external data
00187  * \param len  The length of the external data
00188  *
00189  *             For outbound packets, the packetbuf consists of two
00190  *             parts: header and data. This function is used to make
00191  *             the packetbuf point to external data. The function also
00192  *             specifies the length of the external data that the
00193  *             packetbuf references.
00194  */
00195 void packetbuf_reference(void *ptr, uint16_t len);
00196 
00197 /**
00198  * \brief      Check if the packetbuf references external data
00199  * \retval     Non-zero if the packetbuf references external data, zero otherwise.
00200  *
00201  *             For outbound packets, the packetbuf consists of two
00202  *             parts: header and data. This function is used to check
00203  *             if the packetbuf points to external data that has
00204  *             previously been referenced with packetbuf_reference().
00205  *
00206  */
00207 int packetbuf_is_reference(void);
00208 
00209 /**
00210  * \brief      Get a pointer to external data referenced by the packetbuf
00211  * \retval     A pointer to the external data
00212  *
00213  *             For outbound packets, the packetbuf consists of two
00214  *             parts: header and data. The data may point to external
00215  *             data that has previously been referenced with
00216  *             packetbuf_reference(). This function is used to get a
00217  *             pointer to the external data.
00218  *
00219  */
00220 void *packetbuf_reference_ptr(void);
00221 
00222 /**
00223  * \brief      Compact the packetbuf
00224  *
00225  *             This function compacts the packetbuf by copying the data
00226  *             portion of the packetbuf so that becomes consecutive to
00227  *             the header. It also copies external data that has
00228  *             previously been referenced with packetbuf_reference()
00229  *             into the packetbuf.
00230  *
00231  *             This function is called by the Rime code before a
00232  *             packet is to be sent by a device driver. This assures
00233  *             that the entire packet is consecutive in memory.
00234  *
00235  */
00236 void packetbuf_compact(void);
00237 
00238 /**
00239  * \brief      Copy from external data into the packetbuf
00240  * \param from A pointer to the data from which to copy
00241  * \param len  The size of the data to copy
00242  * \retval     The number of bytes that was copied into the packetbuf
00243  *
00244  *             This function copies data from a pointer into the
00245  *             packetbuf. If the data that is to be copied is larger
00246  *             than the packetbuf, only the data that fits in the
00247  *             packetbuf is copied. The number of bytes that could be
00248  *             copied into the rimbuf is returned.
00249  *
00250  */
00251 int packetbuf_copyfrom(const void *from, uint16_t len);
00252 
00253 /**
00254  * \brief      Copy the entire packetbuf to an external buffer
00255  * \param to   A pointer to the buffer to which the data is to be copied
00256  * \retval     The number of bytes that was copied to the external buffer
00257  *
00258  *             This function copies the packetbuf to an external
00259  *             buffer. Both the data portion and the header portion of
00260  *             the packetbuf is copied. If the packetbuf referenced
00261  *             external data (referenced with packetbuf_reference()) the
00262  *             external data is copied.
00263  *
00264  *             The external buffer to which the packetbuf is to be
00265  *             copied must be able to accomodate at least
00266  *             (PACKETBUF_SIZE + PACKETBUF_HDR_SIZE) bytes. The number of
00267  *             bytes that was copied to the external buffer is
00268  *             returned.
00269  *
00270  */
00271 int packetbuf_copyto(void *to);
00272 
00273 /**
00274  * \brief      Copy the header portion of the packetbuf to an external buffer
00275  * \param to   A pointer to the buffer to which the data is to be copied
00276  * \retval     The number of bytes that was copied to the external buffer
00277  *
00278  *             This function copies the header portion of the packetbuf
00279  *             to an external buffer.
00280  *
00281  *             The external buffer to which the packetbuf is to be
00282  *             copied must be able to accomodate at least
00283  *             PACKETBUF_HDR_SIZE bytes. The number of bytes that was
00284  *             copied to the external buffer is returned.
00285  *
00286  */
00287 int packetbuf_copyto_hdr(uint8_t *to);
00288 
00289 /**
00290  * \brief      Extend the header of the packetbuf, for outbound packets
00291  * \param size The number of bytes the header should be extended
00292  * \retval     Non-zero if the header could be extended, zero otherwise
00293  *
00294  *             This function is used to allocate extra space in the
00295  *             header portion in the packetbuf, when preparing outbound
00296  *             packets for transmission. If the function is unable to
00297  *             allocate sufficient header space, the function returns
00298  *             zero and does not allocate anything.
00299  *
00300  */
00301 int packetbuf_hdralloc(int size);
00302 
00303 /**
00304  * \brief      Reduce the header in the packetbuf, for incoming packets
00305  * \param size The number of bytes the header should be reduced
00306  * \retval     Non-zero if the header could be reduced, zero otherwise
00307  *
00308  *             This function is used to remove the first part of the
00309  *             header in the packetbuf, when processing incoming
00310  *             packets. If the function is unable to remove the
00311  *             requested amount of header space, the function returns
00312  *             zero and does not allocate anything.
00313  *
00314  */
00315 int packetbuf_hdrreduce(int size);
00316 
00317 /* Packet attributes stuff below: */
00318 
00319 typedef uint16_t packetbuf_attr_t;
00320 
00321 struct packetbuf_attr {
00322 /*   uint8_t type; */
00323   packetbuf_attr_t val;
00324 };
00325 struct packetbuf_addr {
00326 /*   uint8_t type; */
00327   rimeaddr_t addr;
00328 };
00329 
00330 #define PACKETBUF_ATTR_PACKET_TYPE_DATA      0
00331 #define PACKETBUF_ATTR_PACKET_TYPE_ACK       1
00332 #define PACKETBUF_ATTR_PACKET_TYPE_STREAM    2
00333 #define PACKETBUF_ATTR_PACKET_TYPE_STREAM_END 3
00334 #define PACKETBUF_ATTR_PACKET_TYPE_TIMESTAMP 4
00335 
00336 enum {
00337   PACKETBUF_ATTR_NONE,
00338 
00339   /* Scope 0 attributes: used only on the local node. */
00340   PACKETBUF_ATTR_CHANNEL,
00341   PACKETBUF_ATTR_NETWORK_ID,
00342   PACKETBUF_ATTR_LINK_QUALITY,
00343   PACKETBUF_ATTR_RSSI,
00344   PACKETBUF_ATTR_TIMESTAMP,
00345   PACKETBUF_ATTR_RADIO_TXPOWER,
00346   PACKETBUF_ATTR_LISTEN_TIME,
00347   PACKETBUF_ATTR_TRANSMIT_TIME,
00348   PACKETBUF_ATTR_MAX_MAC_TRANSMISSIONS,
00349   PACKETBUF_ATTR_MAC_SEQNO,
00350   PACKETBUF_ATTR_MAC_ACK,
00351 
00352   /* Scope 1 attributes: used between two neighbors only. */
00353   PACKETBUF_ATTR_RELIABLE,
00354   PACKETBUF_ATTR_PACKET_ID,
00355   PACKETBUF_ATTR_PACKET_TYPE,
00356   PACKETBUF_ATTR_REXMIT,
00357   PACKETBUF_ATTR_MAX_REXMIT,
00358   PACKETBUF_ATTR_NUM_REXMIT,
00359   PACKETBUF_ATTR_PENDING,
00360   
00361   /* Scope 2 attributes: used between end-to-end nodes. */
00362   PACKETBUF_ATTR_HOPS,
00363   PACKETBUF_ATTR_TTL,
00364   PACKETBUF_ATTR_EPACKET_ID,
00365   PACKETBUF_ATTR_EPACKET_TYPE,
00366   PACKETBUF_ATTR_ERELIABLE,
00367 
00368   /* These must be last */
00369   PACKETBUF_ADDR_SENDER,
00370   PACKETBUF_ADDR_RECEIVER,
00371   PACKETBUF_ADDR_ESENDER,
00372   PACKETBUF_ADDR_ERECEIVER,
00373   
00374   PACKETBUF_ATTR_MAX
00375 };
00376 
00377 #define PACKETBUF_NUM_ADDRS 4
00378 #define PACKETBUF_NUM_ATTRS (PACKETBUF_ATTR_MAX - PACKETBUF_NUM_ADDRS)
00379 #define PACKETBUF_ADDR_FIRST PACKETBUF_ADDR_SENDER
00380 
00381 #define PACKETBUF_IS_ADDR(type) ((type) >= PACKETBUF_ADDR_FIRST)
00382 
00383 #if PACKETBUF_CONF_ATTRS_INLINE
00384 
00385 extern struct packetbuf_attr packetbuf_attrs[];
00386 extern struct packetbuf_addr packetbuf_addrs[];
00387 
00388 static int               packetbuf_set_attr(uint8_t type, const packetbuf_attr_t val);
00389 static packetbuf_attr_t    packetbuf_attr(uint8_t type);
00390 static int               packetbuf_set_addr(uint8_t type, const rimeaddr_t *addr);
00391 static const rimeaddr_t *packetbuf_addr(uint8_t type);
00392 
00393 static inline int
00394 packetbuf_set_attr(uint8_t type, const packetbuf_attr_t val)
00395 {
00396 /*   packetbuf_attrs[type].type = type; */
00397   packetbuf_attrs[type].val = val;
00398   return 1;
00399 }
00400 static inline packetbuf_attr_t
00401 packetbuf_attr(uint8_t type)
00402 {
00403   return packetbuf_attrs[type].val;
00404 }
00405 
00406 static inline int
00407 packetbuf_set_addr(uint8_t type, const rimeaddr_t *addr)
00408 {
00409 /*   packetbuf_addrs[type - PACKETBUF_ADDR_FIRST].type = type; */
00410   rimeaddr_copy(&packetbuf_addrs[type - PACKETBUF_ADDR_FIRST].addr, addr);
00411   return 1;
00412 }
00413 
00414 static inline const rimeaddr_t *
00415 packetbuf_addr(uint8_t type)
00416 {
00417   return &packetbuf_addrs[type - PACKETBUF_ADDR_FIRST].addr;
00418 }
00419 #else /* PACKETBUF_CONF_ATTRS_INLINE */
00420 int               packetbuf_set_attr(uint8_t type, const packetbuf_attr_t val);
00421 packetbuf_attr_t packetbuf_attr(uint8_t type);
00422 int               packetbuf_set_addr(uint8_t type, const rimeaddr_t *addr);
00423 const rimeaddr_t *packetbuf_addr(uint8_t type);
00424 #endif /* PACKETBUF_CONF_ATTRS_INLINE */
00425 
00426 void              packetbuf_attr_clear(void);
00427 
00428 void              packetbuf_attr_copyto(struct packetbuf_attr *attrs,
00429                                       struct packetbuf_addr *addrs);
00430 void              packetbuf_attr_copyfrom(struct packetbuf_attr *attrs,
00431                                         struct packetbuf_addr *addrs);
00432 
00433 #define PACKETBUF_ATTRIBUTES(...) { __VA_ARGS__ PACKETBUF_ATTR_LAST }
00434 #define PACKETBUF_ATTR_LAST { PACKETBUF_ATTR_NONE, 0 }
00435 
00436 #define PACKETBUF_ATTR_BIT  1
00437 #define PACKETBUF_ATTR_BYTE 8
00438 #define PACKETBUF_ADDRSIZE (sizeof(rimeaddr_t) * PACKETBUF_ATTR_BYTE)
00439 
00440 struct packetbuf_attrlist {
00441   uint8_t type;
00442   uint8_t len;
00443 };
00444 
00445 #endif /* __PACKETBUF_H__ */
00446 /** @} */
00447 /** @} */