elopes / PFE15

Blame view

RIOT/sys/include/net/gnrc/sixlowpan.h 6.95 KB
Edit Raw Normal View History
a752c7ab   elopes   add first test an... 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
 
  /*
   * Copyright (C) 2015 Martine Lenders <mlenders@inf.fu-berlin.de>
   *
   * This file is subject to the terms and conditions of the GNU Lesser
   * General Public License v2.1. See the file LICENSE in the top level
   * directory for more details.
   */
  
  /**
   * @defgroup    net_gnrc_sixlowpan    6LoWPAN
   * @ingroup     net_gnrc
   * @brief       GNRC's 6LoWPAN implementation
   *
   * This module is for usage with the @ref net_gnrc_netapi.
   *
   * # NETAPI command documentation
   *
   * ## `GNRC_NETAPI_MSG_TYPE_RCV`
   *
   * @ref GNRC_NETAPI_MSG_TYPE_RCV expects a @ref net_gnrc_pkt (referred to as "packet" in the
   * following) in receive order (link-layer payload first, @ref net_gnrc_netif_hdr last) with the
   * payload marked with @ref GNRC_NETTYPE_SIXLOWPAN. Every other packet will be silently discarded.
   *
   * If the first byte of the payload is @ref SIXLOWPAN_UNCOMP this byte will be removed by marking
   * it with a new @ref gnrc_pktsnip_t and then removing this @ref gnrc_pktsnip_t, the remaining
   * payload will be marked with @ref GNRC_NETTYPE_IPV6 and this module will issue a
   * @ref GNRC_NETAPI_MSG_TYPE_RCV to all subscribers registered to @ref GNRC_NETTYPE_IPV6 with
   * demultiplex context @ref GNRC_NETREG_DEMUX_CTX_ALL in the @ref net_gnrc_netreg with the packet.
   * Otherwise, the packet will be silently discarded (except for the cases documented below).
   *
   * Depending on which other modules are included the behavior can be a little different:
   *
   *  1.  If @ref net_gnrc_sixlowpan_frag is included and @ref sixlowpan_frag_is() is true for the
   *      packet, the fragmentation header will be removed and its remaining data will be added to
   *      the reassembly buffer (using @ref rbuf_add()) in accordance to the fragmentation header.
   *      The packet containing the fragment will be discarded. When the fragmented datagram is
   *      complete, its payload will be marked with @ref GNRC_NETTYPE_IPV6 and issued via a
   *      @ref GNRC_NETAPI_MSG_TYPE_RCV to all subscribers registered to @ref GNRC_NETTYPE_IPV6 with
   *      demultiplex context @ref GNRC_NETREG_DEMUX_CTX_ALL in the @ref net_gnrc_netreg. If
   *      reassembly times out or if fragments overlap the datagram will be silently discarded.
   *  2.  If @ref net_gnrc_sixlowpan_iphc is included the packet will not be send to the subscribers
   *      to @ref GNRC_NETTYPE_IPV6 with demultiplex context @ref GNRC_NETREG_DEMUX_CTX_ALL
   *      immediately, but it will be checked first if @ref sixlowpan_iphc_is() is true for its
   *      payload. If false it will be send to the @ref GNRC_NETTYPE_IPV6 subscribers as usual. If
   *      true the IPHC dispatch will be decompressed to a full IPv6 header first. The IPv6 header
   *      will be included as a new @ref gnrc_pktsnip_t to the packet directly behind the payload.
   *      The IPHC dispatch will be removed. The resulting packet will then be issued to the
   *      @ref GNRC_NETTYPE_IPV6 subscribers as usual.
   *  3.  If both @ref net_gnrc_sixlowpan_frag and @ref net_gnrc_sixlowpan_iphc are included the
   *      and @ref sixlowpan_frag_is() is true for the packet, the fragmented datagram will be
   *      reassembled as described in (1). If for the remainder (after removal of the fragment
   *      header) of the first fragment @ref sixlowpan_iphc_is() is true, it will be decompressed as
   *      described in (2), with the exception that the packet will only be send to all receivers of
   *      @ref GNRC_NETTYPE_IPV6 as soon as the datagram was completely reassembled and not after
   *      directly after decompression. If @ref sixlowpan_iphc_is() is false, reassembly is handled
   *      completely as described in (1). It is assumed that a fragment can fit a full compression
   *      header (including inlined fields and possibly NHC/GHC headers) as specified in
   *      <a href="https://tools.ietf.org/html/rfc6282#section-2">RFC 6282, section 2</a>.
   *
   * ## `GNRC_NETAPI_MSG_TYPE_SND`
   *
   * @ref GNRC_NETAPI_MSG_TYPE_SND expects a @ref net_gnrc_pkt (referred to as "packet" in the
   * following) in send order (headers first, payload last) with the first header being a valid
   * @ref GNRC_NETTYPE_NETIF header and the second a @ref GNRC_NETTYPE_IPV6 header. Every other
   * packet will be silently discarded.
   *
   * The @ref GNRC_NETTYPE_SIXLOWPAN header must at least have the gnrc_netif_hdr_t::if_pid field
   * set to a legal, 6LoWPAN compatible interface (a @ref gnrc_sixlowpan_netif_t entry referred to as
   * `iface` in the following must exist) referred to as "the interface thread" in the following,
   * otherwise the packet will be discarded.
   *
   * If @ref net_gnrc_sixlowpan_iphc is included and gnrc_sixlowpan_netif_t::iphc_enable of `iface`
   * is true the @ref GNRC_NETTYPE_IPV6 header will be compressed according to
   * <a href="https://tools.ietf.org/html/rfc6282">RFC 6282</a>. If it is false the
   * @ref SIXLOWPAN_UNCOMP dispatch will be appended as a new @ref gnrc_pktsnip_t to the packet.
   * The false case also applies if @ref net_gnrc_sixlowpan_iphc is not included.
   *
   * If the packet without @ref GNRC_NETTYPE_NETIF header is shorter than
   * gnrc_sixlowpan_netif_t::max_frag_size of `iface` the packet will be send to the interface
   * thread. Otherwise if @ref net_gnrc_sixlowpan_frag is included the packet will be fragmented
   * according to <a href="https://tools.ietf.org/html/rfc4944">RFC 4944</a> if the packet is without
   * @ref GNRC_NETTYPE_NETIF header shorter than @ref SIXLOWPAN_FRAG_MAX_LEN. If none of these cases
   * apply, the packet will be discarded silently.
   *
   * ## `GNRC_NETAPI_MSG_TYPE_SET`
   *
   * `GNRC_NETAPI_MSG_TYPE_SET` is not supported.
   *
   * ## `GNRC_NETAPI_MSG_TYPE_GET`
   *
   * `GNRC_NETAPI_MSG_TYPE_GET` is not supported.
   *
   * @{
   *
   * @file
   * @brief   Definitions for 6LoWPAN
   *
   * @author  Martine Lenders <mlenders@inf.fu-berlin.de>
   */
  #ifndef NET_GNRC_SIXLOWPAN_H
  #define NET_GNRC_SIXLOWPAN_H
  
  #include <stdbool.h>
  
  #include "kernel_types.h"
  
  #include "net/gnrc/sixlowpan/frag.h"
  #include "net/gnrc/sixlowpan/iphc.h"
  #include "net/sixlowpan.h"
  
  #ifdef __cplusplus
  extern "C" {
  #endif
  
  /**
   * @brief   Default stack size to use for the 6LoWPAN thread.
   */
  #ifndef GNRC_SIXLOWPAN_STACK_SIZE
  #define GNRC_SIXLOWPAN_STACK_SIZE       (THREAD_STACKSIZE_DEFAULT)
  #endif
  
  /**
   * @brief   Default priority for the 6LoWPAN thread.
   */
  #ifndef GNRC_SIXLOWPAN_PRIO
  #define GNRC_SIXLOWPAN_PRIO             (THREAD_PRIORITY_MAIN - 4)
  #endif
  
  /**
   * @brief   Default message queue size to use for the 6LoWPAN thread.
   */
  #ifndef GNRC_SIXLOWPAN_MSG_QUEUE_SIZE
  #define GNRC_SIXLOWPAN_MSG_QUEUE_SIZE   (8U)
  #endif
  
  /**
   * @brief   Initialization of the 6LoWPAN thread.
   *
   * @details If 6LoWPAN was already initialized, it will just return the PID of
   *          the 6LoWPAN thread.
   *
   * @return  The PID to the 6LoWPAN thread, on success.
   * @return  -EINVAL, if @ref GNRC_SIXLOWPAN_PRIO was greater than or equal to
   *          @ref SCHED_PRIO_LEVELS
   * @return  -EOVERFLOW, if there are too many threads running already in general
   */
  kernel_pid_t gnrc_sixlowpan_init(void);
  
  #ifdef __cplusplus
  }
  #endif
  
  #endif /* NET_GNRC_SIXLOWPAN_H */
  /** @} */