Contiki 2.6
|
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 /** @} */