bsd/net/frame802154.h

   1 /*
   2  * Copyright (c) 2017-2020 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. The rights granted to you under the License
  10  * may not be used to create, or enable the creation or redistribution of,
  11  * unlawful or unlicensed copies of an Apple operating system, or to
  12  * circumvent, violate, or enable the circumvention or violation of, any
  13  * terms of an Apple operating system software license agreement.
  14  *
  15  * Please obtain a copy of the License at
  16  * http://www.opensource.apple.com/apsl/ and read it before using this file.
  17  *
  18  * The Original Code and all software distributed under the License are
  19  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  20  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  21  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  22  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  23  * Please see the License for the specific language governing rights and
  24  * limitations under the License.
  25  *
  26  * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  27  */
  28 /*
  29  *  Copyright (c) 2008, Swedish Institute of Computer Science
  30  *  All rights reserved.
  31  *
  32  *  Additional fixes for AVR contributed by:
  33  *        Colin O'Flynn coflynn@newae.com
  34  *        Eric Gnoske egnoske@gmail.com
  35  *        Blake Leverett bleverett@gmail.com
  36  *        Mike Vidales mavida404@gmail.com
  37  *        Kevin Brown kbrown3@uccs.edu
  38  *        Nate Bohlmann nate@elfwerks.com
  39  *
  40  *  Additional fixes for MSP430 contributed by:
  41  *        Joakim Eriksson
  42  *        Niclas Finne
  43  *        Nicolas Tsiftes
  44  *
  45  *   All rights reserved.
  46  *
  47  *   Redistribution and use in source and binary forms, with or without
  48  *   modification, are permitted provided that the following conditions are met:
  49  *
  50  *   * Redistributions of source code must retain the above copyright
  51  *     notice, this list of conditions and the following disclaimer.
  52  *   * Redistributions in binary form must reproduce the above copyright
  53  *     notice, this list of conditions and the following disclaimer in
  54  *     the documentation and/or other materials provided with the
  55  *     distribution.
  56  *   * Neither the name of the copyright holders nor the names of
  57  *     contributors may be used to endorse or promote products derived
  58  *     from this software without specific prior written permission.
  59  *
  60  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  61  *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  62  *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  63  *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
  64  *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  65  *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  66  *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  67  *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  68  *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  69  *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  70  *  POSSIBILITY OF SUCH DAMAGE.
  71  */
  72
  73 /**
  74  *    \addtogroup net
  75  *    @{
  76  */
  77
  78 /**
  79  *    \defgroup frame802154 802.15.4 frame creation and parsing
  80  *    @{
  81  */
  82 /**
  83  *  \file
  84  *  \brief 802.15.4 frame creation and parsing functions
  85  *
  86  *  This file converts to and from a structure to a packed 802.15.4
  87  *  frame.
  88  *
  89  */
  90
  91 /* Includes */
  92 #ifndef FRAME_802154_H
  93 #define FRAME_802154_H
  94
  95 #include "contiki-conf.h"
  96
  97 #include <stdint.h>
  98 #include <sys/types.h>
  99 #ifdef IEEE802154_CONF_PANID
 100 #define IEEE802154_PANID        IEEE802154_CONF_PANID
 101 #else /* IEEE802154_CONF_PANID */
 102 #define IEEE802154_PANID        0xABCD
 103 #endif /* IEEE802154_CONF_PANID */
 104
 105 /* Macros & Defines */
 106
 107 /** \brief These are some definitions of values used in the FCF.  See the 802.15.4 spec for details.
 108  *  \name FCF element values definitions
 109  *  @{
 110  */
 111 #define FRAME802154_BEACONFRAME         (0x00)
 112 #define FRAME802154_DATAFRAME           (0x01)
 113 #define FRAME802154_ACKFRAME            (0x02)
 114 #define FRAME802154_CMDFRAME            (0x03)
 115
 116 #define FRAME802154_BEACONREQ           (0x07)
 117
 118 #define FRAME802154_IEEERESERVED        (0x00)
 119 #define FRAME802154_NOADDR              (0x00)      /**< Only valid for ACK or Beacon frames. */
 120 #define FRAME802154_SHORTADDRMODE       (0x02)
 121 #define FRAME802154_LONGADDRMODE        (0x03)
 122
 123 #define FRAME802154_NOBEACONS           (0x0F)
 124
 125 #define FRAME802154_BROADCASTADDR       (0xFFFF)
 126 #define FRAME802154_BROADCASTPANDID     (0xFFFF)
 127
 128 #define FRAME802154_IEEE802154_2003     (0x00)
 129 #define FRAME802154_IEEE802154_2006     (0x01)
 130
 131 #define FRAME802154_SECURITY_LEVEL_NONE         (0)
 132 #define FRAME802154_SECURITY_LEVEL_MIC_32       (1)
 133 #define FRAME802154_SECURITY_LEVEL_MIC_64       (2)
 134 #define FRAME802154_SECURITY_LEVEL_MIC_128      (3)
 135 #define FRAME802154_SECURITY_LEVEL_ENC          (4)
 136 #define FRAME802154_SECURITY_LEVEL_ENC_MIC_32   (5)
 137 #define FRAME802154_SECURITY_LEVEL_ENC_MIC_64   (6)
 138 #define FRAME802154_SECURITY_LEVEL_ENC_MIC_128  (7)
 139
 140 #define FRAME802154_IMPLICIT_KEY                (0)
 141 #define FRAME802154_1_BYTE_KEY_ID_MODE          (1)
 142 #define FRAME802154_5_BYTE_KEY_ID_MODE          (2)
 143 #define FRAME802154_9_BYTE_KEY_ID_MODE          (3)
 144
 145 /**
 146  *    @brief  The IEEE 802.15.4 frame has a number of constant/fixed fields that
 147  *            can be counted to make frame construction and max payload
 148  *            calculations easier.
 149  *
 150  *            These include:
 151  *            1. FCF                  - 2 bytes       - Fixed
 152  *            2. Sequence number      - 1 byte        - Fixed
 153  *            3. Addressing fields    - 4 - 20 bytes  - Variable
 154  *            4. Aux security header  - 0 - 14 bytes  - Variable
 155  *            5. CRC                  - 2 bytes       - Fixed
 156  */
 157
 158 /**
 159  * \brief Defines the bitfields of the frame control field (FCF).
 160  */
 161 typedef struct {
 162         uint8_t frame_type;        /**< 3 bit. Frame type field, see 802.15.4 */
 163         uint8_t security_enabled;  /**< 1 bit. True if security is used in this frame */
 164         uint8_t frame_pending;     /**< 1 bit. True if sender has more data to send */
 165         uint8_t ack_required;      /**< 1 bit. Is an ack frame required? */
 166         uint8_t panid_compression; /**< 1 bit. Is this a compressed header? */
 167         /*   uint8_t reserved; */  /**< 3 bit. Unused bits */
 168         uint8_t dest_addr_mode;    /**< 2 bit. Destination address mode, see 802.15.4 */
 169         uint8_t frame_version;     /**< 2 bit. 802.15.4 frame version */
 170         uint8_t src_addr_mode;     /**< 2 bit. Source address mode, see 802.15.4 */
 171 } frame802154_fcf_t;
 172
 173 /** \brief 802.15.4 security control bitfield.  See section 7.6.2.2.1 in 802.15.4 specification */
 174 typedef struct {
 175         uint8_t  security_level; /**< 3 bit. security level      */
 176         uint8_t  key_id_mode;    /**< 2 bit. Key identifier mode */
 177         uint8_t  reserved;       /**< 3 bit. Reserved bits       */
 178 } frame802154_scf_t;
 179
 180 typedef union {
 181         uint32_t u32;
 182         uint16_t u16[2];
 183         uint8_t u8[4];
 184 } frame802154_frame_counter_t;
 185
 186 typedef union {
 187         uint16_t u16[4];
 188         uint8_t u8[8];
 189 } frame802154_key_source_t;
 190
 191 /** \brief 802.15.4 Aux security header */
 192 typedef struct {
 193         frame802154_scf_t security_control;        /**< Security control bitfield */
 194         frame802154_frame_counter_t frame_counter; /**< Frame counter, used for security */
 195         frame802154_key_source_t key_source;       /**< Key Source subfield */
 196         uint8_t key_index;                         /**< Key Index subfield */
 197 } frame802154_aux_hdr_t;
 198
 199 /** \brief Parameters used by the frame802154_create() function.  These
 200  *  parameters are used in the 802.15.4 frame header.  See the 802.15.4
 201  *  specification for details.
 202  */
 203 struct frame802154 {
 204         /* The fields dest_addr and src_addr must come first to ensure they are aligned to the
 205          * CPU word size. Needed as they are accessed directly as linkaddr_t*. Note we cannot use
 206          * the type linkaddr_t directly here, as we always need 8 bytes, not LINKADDR_SIZE bytes. */
 207         uint8_t dest_addr[8];           /**< Destination address */
 208         uint8_t src_addr[8];            /**< Source address */
 209         frame802154_fcf_t fcf;          /**< Frame control field  */
 210         uint8_t seq;                    /**< Sequence number */
 211         uint16_t dest_pid;              /**< Destination PAN ID */
 212         uint16_t src_pid;               /**< Source PAN ID */
 213         frame802154_aux_hdr_t aux_hdr;  /**< Aux security header */
 214         //uint8_t *payload;               /**< Pointer to 802.15.4 payload */
 215         int payload_len;                /**< Length of payload field */
 216 };
 217 typedef struct frame802154 frame802154_t;
 218
 219 /* Prototypes */
 220
 221 int frame802154_hdrlen(frame802154_t *p);
 222 int frame802154_create(frame802154_t *p, uint8_t *buf);
 223 size_t frame802154_parse(uint8_t *data, size_t length, frame802154_t *pf, uint8_t **payload);
 224
 225 /** @} */
 226 #endif /* FRAME_802154_H */
 227 /** @} */
 228 /** @} */