doc/sicslowpan-doc.txt

   1 /**
   2 \addtogroup uip
   3 @{
   4 */
   5
   6 /**
   7  * \defgroup sicslowpan 6LoWPAN implementation
   8  * @{
   9
  10 6lowpan is a Working Group in IETF which defines the use of IPv6 on
  11 IEEE 802.15.4 links.
  12
  13 Our implementation is based on RFC4944 <em>Transmission of IPv6
  14 Packets over IEEE 802.15.4 Networks</em>, draft-hui-6lowpan-interop-00
  15 <em>Interoperability Test for 6LoWPAN</em>, and draft-hui-6lowpan-hc-01
  16 <em>Compression format for IPv6 datagrams in 6lowpan Networks</em>.
  17
  18 <HR>
  19
  20 \section drafts Specifications implemented
  21
  22 \note We currently only support 802.15.4 64-bit addresses.
  23
  24 \subsection rfc4944 RFC 4944
  25
  26 RFC4944 defines address configuration mechanisms based on 802.15.4
  27 16-bit and 64-bit addresses, fragmentation of IPv6 packets below IP
  28 layer, IPv6 and UDP header compression, a mesh header to enable link-layer
  29 forwarding in a mesh under topology, and a broadcast header to enable
  30 broadcast in a mesh under topology.
  31
  32
  33 We implement addressing, fragmentation, and header compression. We support
  34 the header compression scenarios defined in draft-hui-6lowpan-interop-00.
  35 This draft defines an interoperability scenario which was used between
  36 ArchRock and Sensinode implementations.
  37
  38 We do not implement mesh under related features, as we target route over
  39 techniques.
  40
  41 \subsection hc01 draft-hui-6lowpan-hc-01
  42
  43 draft-hui-6lowpan-hc-01 defines a stateful header compression mechanism
  44 which should soon deprecate the stateless header compression mechanism
  45 defined in RFC4944. It is much more powerfull and flexible, in
  46 particular it allows compression of some multicast addresses and of all
  47 global unicast addresses.
  48
  49 <HR>
  50
  51 \section general Implementation overview
  52
  53 6lowpan does not run as a separate process. It is called by the MAC %process
  54 when a 6lowpan packet is received, and by the tcpip %process when an
  55 IPv6 packet needs to be sent.
  56
  57 It is initialized from the MAC %process, which calls sicslowpan_init
  58 (giving as argument a pointer to the mac_driver structure).
  59
  60 The main 6lowpan functions are implemented in the sicslowpan.h and
  61 sicslowpan.c files. They are used to format packets between the
  62 802.15.4 and the IPv6 layers.
  63
  64 6lowpan also creates a few IPv6 and link-layer dependencies which are
  65 detailed in the next section.
  66
  67 <HR>
  68
  69 \section implementation Implementation details
  70
  71 \subsection Addressing
  72
  73 <b>Link-layer addresses</b><br>
  74 The format of a 802.15.4 address is defined in uip.h.
  75 \code
  76 /** \brief 64 bit 802.15.4 address */
  77 struct uip_802154_shortaddr {
  78   u8_t addr[2];
  79 };
  80 /** \brief 16 bit 802.15.4 address */
  81 struct uip_802154_longaddr {
  82   u8_t addr[8];
  83 };
  84 /** \brief 802.15.4 address */
  85 typedef struct uip_802154_longaddr uip_lladdr_t;
  86 #define UIP_802154_SHORTADDR_LEN 2
  87 #define UIP_802154_LONGADDR_LEN  8
  88 #define UIP_LLADDR_LEN UIP_802154_LONGADDR_LEN
  89 \endcode
  90
  91 <b>Neighbor Discovery Link Layer Address options </b><br>
  92 The format of ND link-layer address options depends on the length of
  93 the link-layer addresses.
  94 802.15.4 specificities regarding link-layer address options are implemented in uip-nd6.h.
  95 \code
  96 #define UIP_ND6_OPT_SHORT_LLAO_LEN     8
  97 #define UIP_ND6_OPT_LONG_LLAO_LEN      16
  98 #define UIP_ND6_OPT_LLAO_LEN UIP_ND6_OPT_LONG_LLAO_LEN
  99 \endcode
 100
 101 <b>Address Autoconfiguration</b><br>
 102 The address autoconfiguration mechanism also depends on the format of
 103 the link-layer address. The dependency is reflected in the
 104 #uip_netif_addr_autoconf_set function in #uip-netif.c.
 105 \code
 106 #if (UIP_LLADDR_LEN == 8)
 107   memcpy(ipaddr->u8 + 8, lladdr, UIP_LLADDR_LEN);
 108   ipaddr->u8[8] ^= 0x02;
 109 \endcode
 110
 111 \subsection io Packet Input/Output
 112
 113 At initialization, the #input function in sicslowpan.c is set as the
 114 function to be called by the MAC upon packet reception. The #output
 115 function is set as the tcpip_output function.<br>
 116 At packet reception, the link-layer copies the 802.15.4 payload in the
 117 rime buffer, and sets its length. It also stores the source and
 118 destination link-layer addresses as two rime addresses.
 119 \code
 120 packetbuf_copyfrom(&rx_frame.payload, rx_frame.payload_length);
 121 packetbuf_set_datalen(rx_frame.payload_length);
 122 packetbuf_set_addr(PACKETBUF_ADDR_RECEIVER, (const rimeaddr_t *)&rx_frame.dest_addr);
 123 packetbuf_set_addr(PACKETBUF_ADDR_SENDER, (const rimeaddr_t *)&rx_frame.src_addr);
 124 \endcode
 125 It then calls the sicslowpan #input function. Similarly, when the IPv6 layer
 126 has a packet to send over the radio, it puts the packet in uip_buf,
 127 sets uip_len and calls the sicslowpan #output function.
 128
 129 \subsection frag Fragmentation
 130
 131 \li #output function: When an IP packet, after header compression, is
 132 too big to fit in a 802.15.4 frame, it is fragmented in several packets
 133 which are sent successively over the radio. The packets are formatted
 134 as defined in RFC 4944. Only the first fragment contains the IP/UDP
 135 compressed or uncompressed header fields.
 136
 137 \li #input function: This function takes care of fragment
 138 reassembly. We do not assume that the fragments are received in order.
 139 When reassembly of a packet is ongoing, we discard any non fragmented
 140 packet or fragment from another packet. Reassembly times out after
 141 #SICSLOWPAN_REASS_MAXAGE = 20s.
 142
 143 \note Fragmentation support is enabled by setting the #SICSLOWPAN_CONF_FRAG
 144 compilation option.
 145
 146 \note As we do not support complex buffer allocation mechanism, for now
 147 we define a new 1280 bytes buffer (#sicslowpan_buf) to reassemble packets.
 148 At reception, once all the fragments are received, we copy the packet
 149 to #uip_buf, set #uip_len, and call #tcpip_input.
 150
 151 \note #MAC_MAX_PAYLOAD defines the maximum payload
 152 length in a 802.15.4 frame. For now it is constant and equal to 102
 153 bytes (the 802.15.4 frame can be maximum 127 bytes long, and
 154 the header 25 bytes long).
 155
 156 \subsection hc Header Compression
 157
 158 <b>Compression schemes</b><br>
 159 The #SICSLOWPAN_CONF_COMPRESSION compilation option defines the
 160  compression scheme supported. We support HC1, HC01, and IPv6 compression.
 161 HC1 and IPv6 compression are defined in RFC4944, HC01 in
 162 draft-hui-6lowpan-hc. What we call IPv6 compression means sending packets
 163 with no compression, and adding the IPv6 dispatch before the IPv6 header.<br>
 164 If at compile time IPv6 "compression" is chosen, packets sent will never
 165 be compressed, and compressed packets will not be processed at reception.<br>
 166 If at compile time either HC1 or HC01 are chosen, we will try to compress
 167 all fields at sending, and will accept packets compressed with the
 168 chosen scheme, as well as uncompressed packets.<br>
 169 Note that HC1 and HC01 supports are mutually exclusive. HC01 should soon
 170 deprecate HC1.
 171
 172 <b>Compression related functions</b><br>
 173 When a packet is received, the #input function is called. Fragmentation
 174 issues are handled, then we check the dispatch byte: if it is IPv6, we
 175 treat the packet inline. If it is HC1 or HC01, the corresponding
 176 decompression function (#uncompress_hdr_hc1 or #uncompress_hdr_hc01)
 177 is called.<br>
 178 When a packet needs to be sent, we try to compress it. If only the IPv6
 179 compression support is enabled, we just add the IPv6 dispatch before the
 180 802.15.4 payload. If HC1 or HC01 support is enabled, we call the
 181 corresponding compression function (#compress_hdr_hc1 or #compress_hdr_hc01)
 182 to compress the packet as much as possible.
 183
 184 <b>HC1 comments</b><br>
 185 In HC1, if the IPv6 flow label is not compressed, we would need to copy
 186 the fields after the flow label starting in the middle of a byte (the
 187 flow label is 20 bits long). To avoid this, we compress the packets only
 188 if all fields can be compressed. If we cannot, we use the IPv6 dispatch
 189 and send all headers fields inline. This behavior is the one defined in
 190 draft-hui-6lowpan-interop-00.<br>
 191 In the same way, if the packet is an UDP packet, we compress the UDP
 192 header only if all fields can be compressed.<br>
 193 Note that HC1 can only compress unicast link local addresses. For this
 194 reason, we recommend using HC01.
 195
 196 <b>HC01 comments</b><br>
 197 HC01 uses address contexts to enable compression of global unicast
 198 addresses. All nodes must share context (namely the global prefixes in
 199 use) to compress and uncompress such addresses successfully. The context
 200 number is defined by 2 bits. Context 00 is reserved for the link local
 201 context. Other contexts have to be distributed within the LoWPAN
 202 dynamically, by means of ND extensions yet to be defined.<br>
 203 Until then, if you want to test global address compression, you need
 204 to configure the global contexts manually.
 205
 206 <HR>
 207
 208 */
 209 /** @} */
 210 /** @} */