Merge pull request #4636 from authmillenon/ieee802154/enh/general-hdr

ieee802154: provide general header build and read functions

Makefile.pseudomodules

@@ -14,7 +14,6 @@ PSEUDOMODULES += gnrc_sixlowpan_router
 PSEUDOMODULES += gnrc_sixlowpan_router_default
 PSEUDOMODULES += gnrc_sixlowpan_iphc_nhc
 PSEUDOMODULES += gnrc_pktbuf
-PSEUDOMODULES += ieee802154
 PSEUDOMODULES += log
 PSEUDOMODULES += log_printfnoformat
 PSEUDOMODULES += newlib

sys/Makefile

@@ -19,6 +19,9 @@ endif
 ifneq (,$(filter oneway_malloc,$(USEMODULE)))
     DIRS += oneway-malloc
 endif
+ifneq (,$(filter ieee802154,$(USEMODULE)))
+    DIRS += net/link_layer/ieee802154
+endif
 ifneq (,$(filter ipv4_addr,$(USEMODULE)))
     DIRS += net/network_layer/ipv4/addr
 endif

sys/include/net/ieee802154.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2015  Freie Universität Berlin
+ * Copyright (C) 2015-16 Freie Universität Berlin
  *
  * 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
@@ -21,14 +21,26 @@
 #ifndef IEEE802154_H_
 #define IEEE802154_H_
 
+#include <stdint.h>
 #include <stdlib.h>
 
+#include "byteorder.h"
 #include "net/eui64.h"
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/**
+ * @brief IEEE 802.15.4 address lengths
+ * @{
+ */
+#define IEEE802154_SHORT_ADDRESS_LEN        (2U)    /**< short (16-bit) address */
+#define IEEE802154_LONG_ADDRESS_LEN         (8U)    /**< long address (EUI-64) */
+/**
+ * @}
+ */
+
 /**
  * @brief IEEE802.15.4 FCF field definitions
  * @{
@@ -43,28 +55,146 @@ extern "C" {
 #define IEEE802154_FCF_TYPE_ACK             (0x02)
 #define IEEE802154_FCF_TYPE_MACCMD          (0x03)
 
-#define IEEE802154_FCF_SECURITY_EN          (0x08)
+#define IEEE802154_FCF_SECURITY_EN          (0x08)  /**< enable security */
-#define IEEE802154_FCF_FRAME_PEND           (0x10)
+#define IEEE802154_FCF_FRAME_PEND           (0x10)  /**< follow-up frame is pending */
-#define IEEE802154_FCF_ACK_REQ              (0x20)
+#define IEEE802154_FCF_ACK_REQ              (0x20)  /**< acknowledgement requested from receiver */
-#define IEEE802154_FCF_PAN_COMP             (0x40)
+#define IEEE802154_FCF_PAN_COMP             (0x40)  /**< compress source PAN ID */
 
 #define IEEE802154_FCF_DST_ADDR_MASK        (0x0c)
-#define IEEE802154_FCF_DST_ADDR_VOID        (0x00)
+#define IEEE802154_FCF_DST_ADDR_VOID        (0x00)  /**< no destination address */
-#define IEEE802154_FCF_DST_ADDR_SHORT       (0x08)
+#define IEEE802154_FCF_DST_ADDR_RESV        (0x04)  /**< reserved address mode */
-#define IEEE802154_FCF_DST_ADDR_LONG        (0x0c)
+#define IEEE802154_FCF_DST_ADDR_SHORT       (0x08)  /**< destination address length is 2 */
+#define IEEE802154_FCF_DST_ADDR_LONG        (0x0c)  /**< destination address length is 8 */
 
+#define IEEE802154_FCF_VERS_MASK            (0x30)
 #define IEEE802154_FCF_VERS_V0              (0x00)
 #define IEEE802154_FCF_VERS_V1              (0x10)
 
 #define IEEE802154_FCF_SRC_ADDR_MASK        (0xc0)
-#define IEEE802154_FCF_SRC_ADDR_VOID        (0x00)
+#define IEEE802154_FCF_SRC_ADDR_VOID        (0x00)  /**< no source address */
-#define IEEE802154_FCF_SRC_ADDR_SHORT       (0x80)
+#define IEEE802154_FCF_SRC_ADDR_RESV        (0x40)  /**< reserved address mode */
-#define IEEE802154_FCF_SRC_ADDR_LONG        (0xc0)
+#define IEEE802154_FCF_SRC_ADDR_SHORT       (0x80)  /**< source address length is 2 */
+#define IEEE802154_FCF_SRC_ADDR_LONG        (0xc0)  /**< source address length is 8 */
 /** @} */
 
+/**
+ * @brief   Flag for @ref ieee802154_set_frame_hdr to indicate to ignore @p dst
+ *          and @p dst_len and send broadcast.
+ * @note    This flag is RIOT internal and shall not be used in the FCF of
+ *          packets send over the air
+ */
+#define IEEE802154_BCAST                    (0x80)
+
+/**
+ * @brief   Initializes an IEEE 802.15.4 MAC frame header in @p buf.
+ *
+ * @pre Resulting header must fit in memory allocated at @p buf.
+ *
+ * @see IEEE Std 802.15.4-2011, 5.2.1 General MAC frame format.
+ *
+ * If @p dst is NULL the IEEE802154_FCF_ACK_REQ will be unset to prevent
+ * flooding the network.
+ *
+ * @param[out] buf  Target memory for frame header.
+ * @param[in] src       Source address for frame in network byteorder.
+ *                      May be NULL if @ref IEEE802154_FCF_SRC_ADDR_VOID is set
+ *                      in @p flags.
+ * @param[in] src_len   Length of @p src. Legal values are:
+ *                      * 0 (will set @ref IEEE802154_FCF_SRC_ADDR_VOID in MHR)
+ *                      * 2 (will set @ref IEEE802154_FCF_SRC_ADDR_SHORT in MHR)
+ *                      * 8 (will set @ref IEEE802154_FCF_SRC_ADDR_LONG in MHR)
+ * @param[in] dst       Destination address for frame in network byteorder.
+ *                      May be NULL if @ref IEEE802154_FCF_SRC_ADDR_VOID is set
+ *                      in @p flags.
+ * @param[in] dst_len   Length of @p dst. Legal values are:
+ *                      * 0 (will set @ref IEEE802154_FCF_DST_ADDR_VOID in MHR)
+ *                      * 2 (will set @ref IEEE802154_FCF_DST_ADDR_SHORT in MHR)
+ *                      * 8 (will set @ref IEEE802154_FCF_DST_ADDR_LONG in MHR)
+ * @param[in] src_pan   Source PAN ID in little-endian. May be 0 if
+ *                      @ref IEEE802154_FCF_PAN_COMP is set in @p flags.
+ *                      Otherwise, it will be ignored, when
+ *                      @ref IEEE802154_FCF_PAN_COMP is set.
+ * @param[in] dst_pan   Destination PAN ID in little-endian.
+ * @param[in] flags     Flags for the frame. These are interchangable with the
+ *                      first byte of the IEEE 802.15.4 FCF. This means that
+ *                      it encompasses the type values,
+ *                      @ref IEEE802154_FCF_SECURITY_EN,
+ *                      @ref IEEE802154_FCF_FRAME_PEND,
+ *                      @ref IEEE802154_FCF_ACK_REQ, and
+ *                      @ref IEEE802154_FCF_PAN_COMP.
+ *                      Additionally the @ref IEEE802154_BCAST flag can be set
+ *                      do ignore @p dst and @p dst_len and just set `ff:ff`
+ *                      (broadcast) as destination address
+ * @param[in] seq       Sequence number for frame.
+ *
+ * The version field in the FCF will be set implicitly to version 1.
+ *
+ * @return  Size of frame header on success.
+ * @return  0, on error (flags set to unexpected state).
+ */
+size_t ieee802154_set_frame_hdr(uint8_t *buf, const uint8_t *src, size_t src_len,
+                                const uint8_t *dst, size_t dst_len,
+                                le_uint16_t src_pan, le_uint16_t dst_pan,
+                                uint8_t flags, uint8_t seq);
+
+/**
+ * @brief   Get length of MAC header.
+ *
+ * @todo include security header implications
+ *
+ * @param[in] mhr   MAC header.
+ *
+ * @return  Length of MAC header on success.
+ * @return  0, on error (source mode or destination mode set to reserved).
+ */
+size_t ieee802154_get_frame_hdr_len(const uint8_t *mhr);
+
+/**
+ * @brief   Gets source address from MAC header.
+ *
+ * @pre (@p src != NULL) && (@p src_pan != NULL)
+ *
+ * @param[in] mhr       MAC header.
+ * @param[out] src      Source address in network byte order in MAC header.
+ * @param[out] src_pan  Source PAN little-endian byte order in MAC header.
+ *
+ * @return   Length of source address.
+ * @return  -EINVAL, if @p mhr contains unexpected flags.
+ */
+int ieee802154_get_src(const uint8_t *mhr, uint8_t *src, le_uint16_t *src_pan);
+
+/**
+ * @brief   Gets destination address from MAC header.
+ *
+ * @pre (@p dst != NULL) && (@p dst_pan != NULL)
+ *
+ * @param[in] mhr       MAC header.
+ * @param[out] dst      Destination address in network byte order in MAC header.
+ * @param[out] dst_pan  Destination PAN in little-endian byte order in MAC header.
+ *
+ * @return   Length of destination address.
+ * @return  -EINVAL, if @p mhr contains unexpected flags.
+ */
+int ieee802154_get_dst(const uint8_t *mhr, uint8_t *dst, le_uint16_t *dst_pan);
+
+/**
+ * @brief   Gets sequence number from MAC header.
+ *
+ * @pre length of allocated space at @p mhr > 3
+ *
+ * @param[in] mhr   MAC header.
+ *
+ * @return  The sequence number in @p mhr.
+ */
+static inline uint8_t ieee802154_get_seq(const uint8_t *mhr)
+{
+    return mhr[2];
+}
+
 /**
  * @brief   Generates an IPv6 interface identifier from an IEEE 802.15.4 address.
  *
+ * @pre (@p eui64 != NULL) && (@p addr != NULL)
  * @see <a href="https://tools.ietf.org/html/rfc4944#section-6">
  *          RFC 4944, section 6
  *      </a>
@@ -80,8 +210,8 @@ extern "C" {
  * @return Copy of @p eui64 on success.
  * @return NULL, if @p addr_len was of illegal length.
  */
-static inline eui64_t *ieee802154_get_iid(eui64_t *eui64, uint8_t *addr,
+static inline eui64_t *ieee802154_get_iid(eui64_t *eui64, const uint8_t *addr,
-        size_t addr_len)
+                                          size_t addr_len)
 {
     int i = 0;
 
@@ -119,7 +249,6 @@ static inline eui64_t *ieee802154_get_iid(eui64_t *eui64, uint8_t *addr,
     return eui64;
 }
 
-
 #ifdef __cplusplus
 }
 #endif

sys/net/link_layer/ieee802154/Makefile

@@ -0,0 +1 @@
+include $(RIOTBASE)/Makefile.base

sys/net/link_layer/ieee802154/ieee802154.c

@@ -0,0 +1,244 @@
+/*
+ * Copyright (C) 2016 Freie Universität Berlin
+ *
+ * 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.
+ */
+
+/**
+ * @{
+ *
+ * @file
+ * @author Martine Lenders <mlenders@inf.fu-berlin.de>
+ */
+
+#include <assert.h>
+#include <errno.h>
+
+#include "net/ieee802154.h"
+
+size_t ieee802154_set_frame_hdr(uint8_t *buf, const uint8_t *src, size_t src_len,
+                                const uint8_t *dst, size_t dst_len,
+                                le_uint16_t src_pan, le_uint16_t dst_pan,
+                                uint8_t flags, uint8_t seq)
+{
+    int pos = 3;    /* 0-1: FCS, 2: seq */
+    uint8_t type = (flags & IEEE802154_FCF_TYPE_MASK);
+    uint8_t bcast = (flags & IEEE802154_BCAST);
+
+    buf[0] = flags & (~IEEE802154_BCAST);
+    buf[1] = IEEE802154_FCF_VERS_V1;
+
+    if (((src_len != 0) && (src == NULL)) ||
+        ((!bcast) && (dst_len != 0) && (dst == NULL)) ||
+        ((flags & IEEE802154_FCF_PAN_COMP) &&
+         (((!bcast) && (dst_len == 0)) || (src_len == 0)))) {
+        return 0;
+    }
+
+    /* Frame type is not beacon or ACK, but both address modes are zero */
+    if ((type != IEEE802154_FCF_TYPE_BEACON) && (type != IEEE802154_FCF_TYPE_ACK) &&
+        (src_len == 0) && (dst_len == 0)) {
+        return 0;
+    }
+
+    /* set sequence number */
+    buf[2] = seq;
+
+    if (bcast || (dst_len != 0)) {
+        buf[pos++] = dst_pan.u8[0];
+        buf[pos++] = dst_pan.u8[1];
+    }
+
+    /* fill in destination address */
+    if (bcast) {
+        /* no AUTOACK for broadcast */
+        buf[0] &= ~IEEE802154_FCF_ACK_REQ;
+        buf[1] &= ~IEEE802154_FCF_DST_ADDR_MASK;
+        buf[1] |= IEEE802154_FCF_DST_ADDR_SHORT;
+        buf[pos++] = 0xff;
+        buf[pos++] = 0xff;
+    }
+    else {
+        switch (dst_len) {
+            case 0:
+                buf[1] |= IEEE802154_FCF_DST_ADDR_VOID;
+                break;
+            case 2:
+                buf[1] |= IEEE802154_FCF_DST_ADDR_SHORT;
+                buf[pos++] = dst[1];
+                buf[pos++] = dst[0];
+                break;
+            case 8:
+                buf[1] |= IEEE802154_FCF_DST_ADDR_LONG;
+                for (int i = 7; i >= 0; i--) {
+                    buf[pos++] = dst[i];
+                }
+                break;
+            default:
+                return 0;
+        }
+    }
+
+    /* fill in source PAN ID (if applicable) */
+    if (!(flags & IEEE802154_FCF_PAN_COMP) && (src_len != 0)) {
+        /* (little endian) */
+        buf[pos++] = src_pan.u8[0];
+        buf[pos++] = src_pan.u8[1];
+    }
+
+    /* fill in source address */
+    switch (src_len) {
+        case 0:
+            buf[1] |= IEEE802154_FCF_SRC_ADDR_VOID;
+            break;
+        case 2:
+            buf[1] |= IEEE802154_FCF_SRC_ADDR_SHORT;
+            buf[pos++] = src[1];
+            buf[pos++] = src[0];
+            break;
+        case 8:
+            buf[1] |= IEEE802154_FCF_SRC_ADDR_LONG;
+            for (int i = 7; i >= 0; i--) {
+                buf[pos++] = src[i];
+            }
+            break;
+        default:
+            return 0;
+    }
+
+    /* return actual header length */
+    return pos;
+}
+
+size_t ieee802154_get_frame_hdr_len(const uint8_t *mhr)
+{
+    /* TODO: include security header implications */
+    uint8_t tmp;
+    size_t len = 3; /* 2 byte FCF, 1 byte sequence number */
+
+    /* figure out address sizes */
+    tmp = (mhr[1] & IEEE802154_FCF_DST_ADDR_MASK);
+    if (tmp == IEEE802154_FCF_DST_ADDR_SHORT) {
+        len += 4;   /* 2 byte dst PAN + 2 byte dst short address */
+    }
+    else if (tmp == IEEE802154_FCF_DST_ADDR_LONG) {
+        len += 10;  /* 2 byte dst PAN + 2 byte dst long address */
+    }
+    else if (tmp != IEEE802154_FCF_DST_ADDR_VOID) {
+        return 0;
+    }
+    else if (mhr[0] & IEEE802154_FCF_PAN_COMP) {
+        /* PAN compression, but no destination address => illegal state */
+        return 0;
+    }
+    tmp = (mhr[1] & IEEE802154_FCF_SRC_ADDR_MASK);
+    if (tmp == IEEE802154_FCF_SRC_ADDR_VOID) {
+        return len;
+    }
+    else {
+        if (!(mhr[0] & IEEE802154_FCF_PAN_COMP)) {
+            len += 2;
+        }
+        if (tmp == IEEE802154_FCF_SRC_ADDR_SHORT) {
+            return len + 2;
+        }
+        else if (tmp == IEEE802154_FCF_SRC_ADDR_LONG) {
+            return len + 8;
+        }
+    }
+    return 0;
+}
+
+int ieee802154_get_src(const uint8_t *mhr, uint8_t *src, le_uint16_t *src_pan)
+{
+    int offset = 3; /* FCF: 0-1, Seq: 2 */
+    uint8_t tmp;
+
+    assert((src != NULL) && (src_pan != NULL));
+    tmp = mhr[1] & IEEE802154_FCF_DST_ADDR_MASK;
+    if (tmp == IEEE802154_FCF_DST_ADDR_SHORT) {
+        if (mhr[0] & IEEE802154_FCF_PAN_COMP) {
+            src_pan->u8[0] = mhr[offset];
+            src_pan->u8[1] = mhr[offset + 1];
+        }
+        offset += 4;
+    }
+    else if (tmp == IEEE802154_FCF_DST_ADDR_LONG) {
+        if (mhr[0] & IEEE802154_FCF_PAN_COMP) {
+            src_pan->u8[0] = mhr[offset];
+            src_pan->u8[1] = mhr[offset + 1];
+        }
+        offset += 10;
+    }
+    else if (tmp != IEEE802154_FCF_DST_ADDR_VOID) {
+        return -EINVAL;
+    }
+    else if (mhr[0] & IEEE802154_FCF_PAN_COMP) {
+        /* PAN compression, but no destination address => illegal state */
+        return -EINVAL;
+    }
+
+    tmp = mhr[1] & IEEE802154_FCF_SRC_ADDR_MASK;
+    if (tmp != IEEE802154_FCF_SRC_ADDR_VOID) {
+        if (!(mhr[0] & IEEE802154_FCF_PAN_COMP)) {
+            src_pan->u8[0] = mhr[offset++];
+            src_pan->u8[1] = mhr[offset++];
+        }
+    }
+    if (tmp == IEEE802154_FCF_SRC_ADDR_SHORT) {
+        /* read src PAN and address in little endian */
+        src[1] = mhr[offset++];
+        src[0] = mhr[offset++];
+        return 2;
+    }
+    else if (tmp == IEEE802154_FCF_SRC_ADDR_LONG) {
+        /* read src PAN and address in little endian */
+        for (int i = 7; i >= 0; i--) {
+            src[i] = mhr[offset++];
+        }
+        return 8;
+    }
+    else if (tmp != IEEE802154_FCF_SRC_ADDR_VOID) {
+        return -EINVAL;
+    }
+
+    return 0;
+}
+
+int ieee802154_get_dst(const uint8_t *mhr, uint8_t *dst, le_uint16_t *dst_pan)
+{
+    int offset = 3; /* FCF: 0-1, Seq: 2 */
+    uint8_t tmp;
+
+    assert((dst != NULL) && (dst_pan != NULL));
+    tmp = mhr[1] & IEEE802154_FCF_DST_ADDR_MASK;
+    if (tmp == IEEE802154_FCF_DST_ADDR_SHORT) {
+        /* read dst PAN and address in little endian */
+        dst_pan->u8[0] = mhr[offset++];
+        dst_pan->u8[1] = mhr[offset++];
+        dst[1] = mhr[offset++];
+        dst[0] = mhr[offset++];
+        return 2;
+    }
+    else if (tmp == IEEE802154_FCF_DST_ADDR_LONG) {
+        dst_pan->u8[0] = mhr[offset++];
+        dst_pan->u8[1] = mhr[offset++];
+        for (int i = 7; i >= 0; i--) {
+            dst[i] = mhr[offset++];
+        }
+        return 8;
+    }
+    else if (tmp != IEEE802154_FCF_DST_ADDR_VOID) {
+        return -EINVAL;
+    }
+    else if (mhr[0] & IEEE802154_FCF_PAN_COMP) {
+        /* PAN compression, but no destination address => illegal state */
+        return -EINVAL;
+    }
+
+    return 0;
+}
+
+/** @} */

tests/unittests/tests-ieee802154/Makefile

@@ -0,0 +1 @@
+include $(RIOTBASE)/Makefile.base

tests/unittests/tests-ieee802154/Makefile.include

@@ -0,0 +1 @@
+USEMODULE += ieee802154

tests/unittests/tests-ieee802154/tests-ieee802154.h

@@ -0,0 +1,37 @@
+/*
+ * Copyright (C) 2016 Freie Universität Berlin
+ *
+ * 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.
+ */
+
+/**
+ * @addtogroup  unittests
+ * @{
+ *
+ * @file
+ * @brief       Unittests for the ``ieee802154`` module
+ *
+ * @author      Martine Lenders <mlenders@inf.fu-berlin.de>
+ */
+#ifndef TESTS_IEEE802154_H_
+#define TESTS_IEEE802154_H_
+
+#include "embUnit.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief   The entry point of this test suite.
+ */
+void tests_ieee802154(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* TESTS_IEEE802154_H_ */
+/** @} */