Contiki-NG
tsch-packet.c
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2014, SICS Swedish ICT.
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  * 1. Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  * 2. Redistributions in binary form must reproduce the above copyright
11  * notice, this list of conditions and the following disclaimer in the
12  * documentation and/or other materials provided with the distribution.
13  * 3. Neither the name of the Institute nor the names of its contributors
14  * may be used to endorse or promote products derived from this software
15  * without specific prior written permission.
16  *
17  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
18  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20  * ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
21  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27  * SUCH DAMAGE.
28  *
29  * This file is part of the Contiki operating system.
30  *
31  */
32 
33 /**
34  * \file
35  * TSCH packet format management
36  * \author
37  * Simon Duquennoy <simonduq@sics.se>
38  * Beshr Al Nahas <beshr@sics.se>
39  */
40 
41 /**
42  * \addtogroup tsch
43  * @{
44 */
45 
46 #include "contiki.h"
47 #include "net/packetbuf.h"
48 #include "net/mac/tsch/tsch.h"
51 #include "net/netstack.h"
52 #include "lib/ccm-star.h"
53 #include "lib/aes-128.h"
54 
55 /* Log configuration */
56 #include "sys/log.h"
57 #define LOG_MODULE "TSCH Pkt"
58 #define LOG_LEVEL LOG_LEVEL_MAC
59 
60 /*
61  * We use a local packetbuf_attr array to collect necessary frame settings to
62  * create an EACK because EACK is generated in the interrupt context where
63  * packetbuf and packetbuf_attrs[] may be in use for another purpose.
64  *
65  * We have accessors of eackbuf_attrs: tsch_packet_eackbuf_set_attr() and
66  * tsch_packet_eackbuf_attr(). For some platform, they might need to be
67  * implemented as inline functions. However, for now, we don't provide the
68  * inline option. Such an optimization is left to the compiler for a target
69  * platform.
70  */
71 static struct packetbuf_attr eackbuf_attrs[PACKETBUF_NUM_ATTRS];
72 
73 /* The offset of the frame pending bit flag within the first byte of FCF */
74 #define IEEE802154_FRAME_PENDING_BIT_OFFSET 4
75 
76 /*---------------------------------------------------------------------------*/
77 void
78 tsch_packet_eackbuf_set_attr(uint8_t type, const packetbuf_attr_t val)
79 {
80  eackbuf_attrs[type].val = val;
81  return;
82 }
83 /*---------------------------------------------------------------------------*/
84 /* Return the value of a specified attribute */
85 packetbuf_attr_t
87 {
88  return eackbuf_attrs[type].val;
89 }
90 /*---------------------------------------------------------------------------*/
91 /* Construct enhanced ACK packet and return ACK length */
92 int
93 tsch_packet_create_eack(uint8_t *buf, uint16_t buf_len,
94  const linkaddr_t *dest_addr, uint8_t seqno,
95  int16_t drift, int nack)
96 {
97  frame802154_t params;
98  struct ieee802154_ies ies;
99  int hdr_len;
100  int ack_len;
101 
102  if(buf == NULL) {
103  return -1;
104  }
105 
106  memset(eackbuf_attrs, 0, sizeof(eackbuf_attrs));
107 
108  tsch_packet_eackbuf_set_attr(PACKETBUF_ATTR_FRAME_TYPE, FRAME802154_ACKFRAME);
109  tsch_packet_eackbuf_set_attr(PACKETBUF_ATTR_MAC_METADATA, 1);
110  tsch_packet_eackbuf_set_attr(PACKETBUF_ATTR_MAC_SEQNO, seqno);
111 
112  tsch_packet_eackbuf_set_attr(PACKETBUF_ATTR_MAC_NO_DEST_ADDR, 1);
113 #if TSCH_PACKET_EACK_WITH_DEST_ADDR
114  if(dest_addr != NULL) {
115  tsch_packet_eackbuf_set_attr(PACKETBUF_ATTR_MAC_NO_DEST_ADDR, 0);
116  linkaddr_copy((linkaddr_t *)&params.dest_addr, dest_addr);
117  }
118 #endif
119 
120  tsch_packet_eackbuf_set_attr(PACKETBUF_ATTR_MAC_NO_SRC_ADDR, 1);
121 #if TSCH_PACKET_EACK_WITH_SRC_ADDR
122  tsch_packet_eackbuf_set_attr(PACKETBUF_ATTR_MAC_NO_SRC_ADDR, 0);
123  linkaddr_copy((linkaddr_t *)&params.src_addr, &linkaddr_node_addr);
124 #endif
125 
126 #if LLSEC802154_ENABLED
127  tsch_security_set_packetbuf_attr(FRAME802154_ACKFRAME);
128 #endif /* LLSEC802154_ENABLED */
129 
130  framer_802154_setup_params(tsch_packet_eackbuf_attr, 0, &params);
131  hdr_len = frame802154_hdrlen(&params);
132 
133  memset(buf, 0, buf_len);
134 
135  /* Setup IE timesync */
136  memset(&ies, 0, sizeof(ies));
137  ies.ie_time_correction = drift;
138  ies.ie_is_nack = nack;
139 
140  ack_len =
142  buf_len - hdr_len, &ies);
143  if(ack_len < 0) {
144  return -1;
145  }
146  ack_len += hdr_len;
147 
148  frame802154_create(&params, buf);
149 
150  return ack_len;
151 }
152 /*---------------------------------------------------------------------------*/
153 /* Parse enhanced ACK packet, extract drift and nack */
154 int
155 tsch_packet_parse_eack(const uint8_t *buf, int buf_size,
156  uint8_t seqno, frame802154_t *frame, struct ieee802154_ies *ies, uint8_t *hdr_len)
157 {
158  uint8_t curr_len = 0;
159  int ret;
160  linkaddr_t dest;
161 
162  if(frame == NULL || buf_size < 0) {
163  return 0;
164  }
165  /* Parse 802.15.4-2006 frame, i.e. all fields before Information Elements */
166  if((ret = frame802154_parse((uint8_t *)buf, buf_size, frame)) < 3) {
167  return 0;
168  }
169  if(hdr_len != NULL) {
170  *hdr_len = ret;
171  }
172  curr_len += ret;
173 
174  /* Check seqno */
175  if(seqno != frame->seq) {
176  return 0;
177  }
178 
179  /* Check destination PAN ID */
180  if(frame802154_check_dest_panid(frame) == 0) {
181  return 0;
182  }
183 
184  /* Check destination address (if any) */
185  if(frame802154_extract_linkaddr(frame, NULL, &dest) == 0 ||
187  && !linkaddr_cmp(&dest, &linkaddr_null))) {
188  return 0;
189  }
190 
191  if(ies != NULL) {
192  memset(ies, 0, sizeof(struct ieee802154_ies));
193  }
194 
195  if(frame->fcf.ie_list_present) {
196  int mic_len = 0;
197 #if LLSEC802154_ENABLED
198  /* Check if there is space for the security MIC (if any) */
199  mic_len = tsch_security_mic_len(frame);
200  if(buf_size < curr_len + mic_len) {
201  return 0;
202  }
203 #endif /* LLSEC802154_ENABLED */
204  /* Parse information elements. We need to substract the MIC length, as the exact payload len is needed while parsing */
205  if((ret = frame802154e_parse_information_elements(buf + curr_len, buf_size - curr_len - mic_len, ies)) == -1) {
206  return 0;
207  }
208  curr_len += ret;
209  }
210 
211  if(hdr_len != NULL) {
212  *hdr_len += ies->ie_payload_ie_offset;
213  }
214 
215  return curr_len;
216 }
217 /*---------------------------------------------------------------------------*/
218 /* Create an EB packet */
219 int
220 tsch_packet_create_eb(uint8_t *hdr_len, uint8_t *tsch_sync_ie_offset)
221 {
222  struct ieee802154_ies ies;
223  uint8_t *p;
224  int ie_len;
225  const uint16_t payload_ie_hdr_len = 2;
226 
227  packetbuf_clear();
228 
229  /* Prepare Information Elements for inclusion in the EB */
230  memset(&ies, 0, sizeof(ies));
231 
232  /* Add TSCH timeslot timing IE. */
233 #if TSCH_PACKET_EB_WITH_TIMESLOT_TIMING
234  {
235  int i;
236  ies.ie_tsch_timeslot_id = 1;
237  for(i = 0; i < tsch_ts_elements_count; i++) {
238  ies.ie_tsch_timeslot[i] = RTIMERTICKS_TO_US(tsch_timing[i]);
239  }
240  }
241 #endif /* TSCH_PACKET_EB_WITH_TIMESLOT_TIMING */
242 
243  /* Add TSCH hopping sequence IE */
244 #if TSCH_PACKET_EB_WITH_HOPPING_SEQUENCE
245  if(tsch_hopping_sequence_length.val <= sizeof(ies.ie_hopping_sequence_list)) {
246  ies.ie_channel_hopping_sequence_id = 1;
247  ies.ie_hopping_sequence_len = tsch_hopping_sequence_length.val;
248  memcpy(ies.ie_hopping_sequence_list, tsch_hopping_sequence,
249  ies.ie_hopping_sequence_len);
250  }
251 #endif /* TSCH_PACKET_EB_WITH_HOPPING_SEQUENCE */
252 
253  /* Add Slotframe and Link IE */
254 #if TSCH_PACKET_EB_WITH_SLOTFRAME_AND_LINK
255  {
256  /* Send slotframe 0 with link at timeslot 0 and channel offset 0 */
258  struct tsch_link *link0 = tsch_schedule_get_link_by_timeslot(sf0, 0, 0);
259  if(sf0 && link0) {
260  ies.ie_tsch_slotframe_and_link.num_slotframes = 1;
261  ies.ie_tsch_slotframe_and_link.slotframe_handle = sf0->handle;
262  ies.ie_tsch_slotframe_and_link.slotframe_size = sf0->size.val;
263  ies.ie_tsch_slotframe_and_link.num_links = 1;
264  ies.ie_tsch_slotframe_and_link.links[0].timeslot = link0->timeslot;
265  ies.ie_tsch_slotframe_and_link.links[0].channel_offset =
266  link0->channel_offset;
267  ies.ie_tsch_slotframe_and_link.links[0].link_options =
268  link0->link_options;
269  }
270  }
271 #endif /* TSCH_PACKET_EB_WITH_SLOTFRAME_AND_LINK */
272 
273  p = packetbuf_dataptr();
274 
275  ie_len = frame80215e_create_ie_tsch_synchronization(p,
277  &ies);
278  if(ie_len < 0) {
279  return -1;
280  }
281  p += ie_len;
283 
284  ie_len = frame80215e_create_ie_tsch_timeslot(p,
286  &ies);
287  if(ie_len < 0) {
288  return -1;
289  }
290  p += ie_len;
292 
293  ie_len = frame80215e_create_ie_tsch_channel_hopping_sequence(p,
295  &ies);
296  if(ie_len < 0) {
297  return -1;
298  }
299  p += ie_len;
301 
302  ie_len = frame80215e_create_ie_tsch_slotframe_and_link(p,
304  &ies);
305  if(ie_len < 0) {
306  return -1;
307  }
308  p += ie_len;
310 
311 #if 0
312  /* Payload IE list termination: optional */
313  ie_len = frame80215e_create_ie_payload_list_termination(p,
315  &ies);
316  if(ie_len < 0) {
317  return -1;
318  }
319  p += ie_len;
321 #endif
322 
323  ies.ie_mlme_len = packetbuf_datalen();
324 
325  /* make room for Payload IE header */
326  memmove((uint8_t *)packetbuf_dataptr() + payload_ie_hdr_len,
328  packetbuf_set_datalen(packetbuf_datalen() + payload_ie_hdr_len);
329  ie_len = frame80215e_create_ie_mlme(packetbuf_dataptr(),
331  &ies);
332  if(ie_len < 0) {
333  return -1;
334  }
335 
336  /* allocate space for Header Termination IE, the size of which is 2 octets */
338  ie_len = frame80215e_create_ie_header_list_termination_1(packetbuf_hdrptr(),
340  &ies);
341  if(ie_len < 0) {
342  return -1;
343  }
344 
345  packetbuf_set_attr(PACKETBUF_ATTR_FRAME_TYPE, FRAME802154_BEACONFRAME);
346  packetbuf_set_attr(PACKETBUF_ATTR_MAC_METADATA, 1);
347 
348  packetbuf_set_addr(PACKETBUF_ADDR_SENDER, &linkaddr_node_addr);
349  packetbuf_set_addr(PACKETBUF_ADDR_RECEIVER, &tsch_eb_address);
350 
351 #if LLSEC802154_ENABLED
352  tsch_security_set_packetbuf_attr(FRAME802154_BEACONFRAME);
353 #endif /* LLSEC802154_ENABLED */
354 
355  if(NETSTACK_FRAMER.create() < 0) {
356  return -1;
357  }
358 
359  if(hdr_len != NULL) {
360  *hdr_len = packetbuf_hdrlen();
361  }
362 
363  /*
364  * Save the offset of the TSCH Synchronization IE, which is expected to be
365  * located just after the Payload IE header, needed to update ASN and join
366  * priority before sending.
367  */
368  if(tsch_sync_ie_offset != NULL) {
369  *tsch_sync_ie_offset = packetbuf_hdrlen() + payload_ie_hdr_len;
370  }
371 
372  return packetbuf_totlen();
373 }
374 /*---------------------------------------------------------------------------*/
375 /* Update ASN in EB packet */
376 int
377 tsch_packet_update_eb(uint8_t *buf, int buf_size, uint8_t tsch_sync_ie_offset)
378 {
379  struct ieee802154_ies ies;
380  ies.ie_asn = tsch_current_asn;
381  ies.ie_join_priority = tsch_join_priority;
382  return frame80215e_create_ie_tsch_synchronization(buf+tsch_sync_ie_offset, buf_size-tsch_sync_ie_offset, &ies) != -1;
383 }
384 /*---------------------------------------------------------------------------*/
385 /* Parse a IEEE 802.15.4e TSCH Enhanced Beacon (EB) */
386 int
387 tsch_packet_parse_eb(const uint8_t *buf, int buf_size,
388  frame802154_t *frame, struct ieee802154_ies *ies, uint8_t *hdr_len, int frame_without_mic)
389 {
390  uint8_t curr_len = 0;
391  int ret;
392 
393  if(frame == NULL || buf_size < 0) {
394  return 0;
395  }
396 
397  /* Parse 802.15.4-2006 frame, i.e. all fields before Information Elements */
398  if((ret = frame802154_parse((uint8_t *)buf, buf_size, frame)) == 0) {
399  LOG_ERR("! parse_eb: failed to parse frame\n");
400  return 0;
401  }
402 
403  if(frame->fcf.frame_version < FRAME802154_IEEE802154_2015
404  || frame->fcf.frame_type != FRAME802154_BEACONFRAME) {
405  LOG_INFO("! parse_eb: frame is not a TSCH beacon." \
406  " Frame version %u, type %u, FCF %02x %02x\n",
407  frame->fcf.frame_version, frame->fcf.frame_type, buf[0], buf[1]);
408  LOG_INFO("! parse_eb: frame was from 0x%x/", frame->src_pid);
409  LOG_INFO_LLADDR((const linkaddr_t *)&frame->src_addr);
410  LOG_INFO_(" to 0x%x/", frame->dest_pid);
411  LOG_INFO_LLADDR((const linkaddr_t *)&frame->dest_addr);
412  LOG_INFO_("\n");
413  return 0;
414  }
415 
416  if(hdr_len != NULL) {
417  *hdr_len = ret;
418  }
419  curr_len += ret;
420 
421  if(ies != NULL) {
422  memset(ies, 0, sizeof(struct ieee802154_ies));
423  ies->ie_join_priority = 0xff; /* Use max value in case the Beacon does not include a join priority */
424  }
425  if(frame->fcf.ie_list_present) {
426  /* Calculate space needed for the security MIC, if any, before attempting to parse IEs */
427  int mic_len = 0;
428 #if LLSEC802154_ENABLED
429  if(!frame_without_mic) {
430  mic_len = tsch_security_mic_len(frame);
431  if(buf_size < curr_len + mic_len) {
432  return 0;
433  }
434  }
435 #endif /* LLSEC802154_ENABLED */
436 
437  /* Parse information elements. We need to substract the MIC length, as the exact payload len is needed while parsing */
438  if((ret = frame802154e_parse_information_elements(buf + curr_len, buf_size - curr_len - mic_len, ies)) == -1) {
439  LOG_ERR("! parse_eb: failed to parse IEs\n");
440  return 0;
441  }
442  curr_len += ret;
443  }
444 
445  if(hdr_len != NULL) {
446  *hdr_len += ies->ie_payload_ie_offset;
447  }
448 
449  return curr_len;
450 }
451 /*---------------------------------------------------------------------------*/
452 /* Set frame pending bit in a packet (whose header was already build) */
453 void
454 tsch_packet_set_frame_pending(uint8_t *buf, int buf_size)
455 {
456  buf[0] |= (1 << IEEE802154_FRAME_PENDING_BIT_OFFSET);
457 }
458 /*---------------------------------------------------------------------------*/
459 /* Get frame pending bit from a packet */
460 int
461 tsch_packet_get_frame_pending(uint8_t *buf, int buf_size)
462 {
463  return (buf[0] >> IEEE802154_FRAME_PENDING_BIT_OFFSET) & 1;
464 }
465 /*---------------------------------------------------------------------------*/
466 /** @} */
uint16_t src_pid
Source PAN ID.
Definition: frame802154.h:207
void * packetbuf_dataptr(void)
Get a pointer to the data in the packetbuf.
Definition: packetbuf.c:143
int tsch_packet_create_eb(uint8_t *hdr_len, uint8_t *tsch_sync_ie_offset)
Create an EB packet directly in packetbuf.
Definition: tsch-packet.c:220
frame802154_fcf_t fcf
Frame control field.
Definition: frame802154.h:204
void packetbuf_clear(void)
Clear and reset the packetbuf.
Definition: packetbuf.c:75
int packetbuf_hdralloc(int size)
Extend the header of the packetbuf, for outbound packets.
Definition: packetbuf.c:107
uint16_t packetbuf_remaininglen(void)
Get the total length of the remaining space in the packetbuf.
Definition: packetbuf.c:173
int frame802154_parse(uint8_t *data, int len, frame802154_t *pf)
Parses an input frame.
Definition: frame802154.c:500
802.15.4e slotframe (contains links)
Definition: tsch-types.h:84
uint8_t packetbuf_hdrlen(void)
Get the length of the header in the packetbuf.
Definition: packetbuf.c:161
uint8_t src_addr[8]
Source address.
Definition: frame802154.h:203
int frame802154_hdrlen(frame802154_t *p)
Calculates the length of the frame header.
Definition: frame802154.c:358
A MAC framer for IEEE 802.15.4
const linkaddr_t linkaddr_null
The null link-layer address.
int tsch_packet_update_eb(uint8_t *buf, int buf_size, uint8_t tsch_sync_ie_offset)
Update ASN in EB packet.
Definition: tsch-packet.c:377
uint16_t packetbuf_datalen(void)
Get the length of the data in the packetbuf.
Definition: packetbuf.c:155
linkaddr_t linkaddr_node_addr
The link-layer address of the node.
Definition: linkaddr.c:48
struct tsch_slotframe * tsch_schedule_get_slotframe_by_handle(uint16_t handle)
Looks up a slotframe by handle.
unsigned int tsch_security_mic_len(const frame802154_t *frame)
Return MIC length.
uint8_t frame_version
2 bit.
Definition: frame802154.h:162
uint16_t packetbuf_totlen(void)
Get the total length of the header and data in the packetbuf.
Definition: packetbuf.c:167
CCM* header file.
int tsch_packet_parse_eack(const uint8_t *buf, int buf_size, uint8_t seqno, frame802154_t *frame, struct ieee802154_ies *ies, uint8_t *hdr_len)
Parse enhanced ACK packet.
Definition: tsch-packet.c:155
Main API declarations for TSCH.
void tsch_packet_eackbuf_set_attr(uint8_t type, const packetbuf_attr_t val)
Set a packet attribute for the current eack.
Definition: tsch-packet.c:78
802.15.4 frame creation and parsing functions
void tsch_security_set_packetbuf_attr(uint8_t frame_type)
Set packetbuf (or eackbuf) attributes depending on a given frame type.
uint8_t frame_type
3 bit.
Definition: frame802154.h:153
uint16_t dest_pid
Destination PAN ID.
Definition: frame802154.h:206
Parameters used by the frame802154_create() function.
Definition: frame802154.h:198
void linkaddr_copy(linkaddr_t *dest, const linkaddr_t *src)
Copy a link-layer address.
Definition: linkaddr.c:63
void tsch_packet_set_frame_pending(uint8_t *buf, int buf_size)
Set frame pending bit in a packet (whose header was already build)
Definition: tsch-packet.c:454
int linkaddr_cmp(const linkaddr_t *addr1, const linkaddr_t *addr2)
Compare two link-layer addresses.
Definition: linkaddr.c:69
void * packetbuf_hdrptr(void)
Get a pointer to the header in the packetbuf, for outbound packets.
Definition: packetbuf.c:149
struct tsch_link * tsch_schedule_get_link_by_timeslot(struct tsch_slotframe *slotframe, uint16_t timeslot, uint16_t channel_offset)
Looks within a slotframe for a link with a given timeslot.
uint8_t ie_list_present
1 bit.
Definition: frame802154.h:160
uint8_t seq
Sequence number.
Definition: frame802154.h:205
int tsch_packet_get_frame_pending(uint8_t *buf, int buf_size)
Get frame pending bit from a packet.
Definition: tsch-packet.c:461
Header file for the Packet buffer (packetbuf) management
Include file for the Contiki low-layer network stack (NETSTACK)
uint8_t dest_addr[8]
Destination address.
Definition: frame802154.h:202
Header file for the logging system
AES-128.
packetbuf_attr_t tsch_packet_eackbuf_attr(uint8_t type)
Return the value of a specified attribute.
Definition: tsch-packet.c:86
int tsch_packet_parse_eb(const uint8_t *buf, int buf_size, frame802154_t *frame, struct ieee802154_ies *ies, uint8_t *hdr_len, int frame_without_mic)
Parse EB.
Definition: tsch-packet.c:387
void packetbuf_set_datalen(uint16_t len)
Set the length of the data in the packetbuf.
Definition: packetbuf.c:136
int frame80215e_create_ie_header_ack_nack_time_correction(uint8_t *buf, int len, struct ieee802154_ies *ies)
Insert various Information Elements.
int frame802154_create(frame802154_t *p, uint8_t *buf)
Creates a frame for transmission over the air.
Definition: frame802154.c:392
int tsch_packet_create_eack(uint8_t *buf, uint16_t buf_len, const linkaddr_t *dest_addr, uint8_t seqno, int16_t drift, int nack)
Construct Enhanced ACK packet.
Definition: tsch-packet.c:93