/**
 * Copyright (c) 2016 - 2021 Nordic Semiconductor ASA and Luxoft Global Operations Gmbh.
 *
 * All Rights Reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 *
 * 
 * 1. Redistributions of source code must retain the above copyright notice, this
 *    list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form, except as embedded into a Nordic
 *    Semiconductor ASA integrated circuit in a product or a software update for
 *    such product, must reproduce the above copyright notice, this list of
 *    conditions and the following disclaimer in the documentation and/or other
 *    materials provided with the distribution.
 *
 * 3. Neither the name of Nordic Semiconductor ASA nor the names of its
 *    contributors may be used to endorse or promote products derived from this
 *    software without specific prior written permission.
 *
 * 4. This software, with or without modification, must only be used with a
 *    Nordic Semiconductor ASA integrated circuit.
 *
 * 5. Any software provided in binary form under this license must not be reverse
 *    engineered, decompiled, modified and/or disassembled.
 *
 * 
 * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS
 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
 * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 */
#ifndef MAC_COMMON_H_INCLUDED
#define MAC_COMMON_H_INCLUDED

#include <stdint.h>
#include "phy_common.h"

#if (CONFIG_SECURE == 1)
#include "mac_security.h"
#endif

/** @file
 * Types and declarations common for different MLME transactions listed here.
 *
 * @defgroup mac_common MAC Common API
 * @ingroup mac_15_4
 * @{
 * @brief Module for declaring MAC Common API.
 * @details The Common MAC module contains declarations of commonly used MAC routines and necessary
 * macros and types.
 */

/**@brief Maximum interval for acknowledgement frame to arrive in microseconds.
 *
 * macAckWaitDuration = aUnitBackoffPeriod(only for beacon enabled PAN) +
 *                      aTurnaroundTime +
 *                      phySHRDuration + ceil(6 * phySymbolsPerOctet) =
 *                      20 + 12 + 10 + 6 * 2 =
 *                      54 symbols / 62.5 ksymbols/s = 864 us (544 us for beacon disabled PAN)
 */
#if (CONFIG_BEACON_ENABLED == 1)
#define macAckWaitDuration                864
#else
#define macAckWaitDuration                544
#endif

/**@brief The maximum number of octets added by the MAC
 * sublayer to the MAC payload of a beacon frame.
 */
#define aMaxBeaconOverhead                75

/**@brief The number of symbols forming the basic time period
 * used by the CSMA-CA algorithm.
 */
#define aUnitBackoffPeriod                20UL

/**@brief The number of symbols forming a superframe slot
 * when the superframe order is equal to 0.
 */
#define aBaseSlotDuration                 60UL

/**@brief The number of slots contained in any superframe. */
#define aNumSuperframeSlots               16UL

/**@brief The number of symbols forming a superframe when
 * the superframe order is equal to 0.
 */
#define aBaseSuperframeDuration          (aBaseSlotDuration * aNumSuperframeSlots)

/**@brief The maximum size, in octets, of a beacon payload. */
#define aMaxBeaconPayloadLength          (aMaxPHYPacketSize - aMaxBeaconOverhead)

/**@brief The maximum number of octets added by the MAC
 * sublayer to the PSDU without security.
 */
#define aMaxMPDUUnsecuredOverhead         25

/**@brief The maximum number of octets that can be transmitted in the MAC Payload
 * field of an unsecured MAC frame that will be guaranteed not to exceed aMaxPHYPacketSize.
 */
#define aMaxMACSafePayloadSize           (aMaxPHYPacketSize - aMaxMPDUUnsecuredOverhead)

/**@brief The minimum number of octets added by the MAC sublayer to the PSDU.*/
#define aMinMPDUOverhead                  9

/**@brief The maximum number of octets that can be transmitted in the MAC
 * Payload field.
 */
#define aMaxMACPayloadSize               (aMaxPHYPacketSize - aMinMPDUOverhead)

/**@brief The maximum size of an MPDU, in octets, that can be followed by a SIFS period. */
#define aMaxSIFSFrameSize                 18

/**@brief The minimum number of symbols forming the CAP.
 *
 * @details This ensures that MAC commands can still be transferred to devices
 * when GTSs are being used.
 */
#define aMinCAPLength                     440

/**@brief The number of superframes in which a GTS descriptor exists
 * in the beacon frame of the PAN coordinator.
 */
#define aGTSDescPersistenceTime           4

/**@brief The number of consecutive lost beacons that will cause the MAC sublayer
 * of a receiving device to declare a loss of synchronization.
 */
#define aMaxLostBeacons                   4

/**@brief   Maximum number of battery life extension periods. */
#define MAC_MIN_BATT_LIFE_EXT_PERIODS     6
/**@brief   Minimum number of battery life extension periods. */
#define MAC_MAX_BATT_LIFE_EXT_PERIODS     41

/**@brief   Minimum value for macBeaconOrder parameter. */
#define MAC_MIN_BEACON_ORDER              0
/**@brief   Maximum value for macBeaconOrder parameter. */
#define MAC_MAX_BEACON_ORDER              15

/**@brief   Minimum value for macMaxCSMABackoffs parameter. */
#define MAC_MIN_MAX_CSMA_BACKOFFS         0
/**@brief   Maximum value for macMaxCSMABackoffs parameter. */
#define MAC_MAX_MAX_CSMA_BACKOFFS         5

/**@brief   Minimum value for macMinBE parameter. */
#define MAC_MIN_MIN_BE                    0

/**@brief   Minimum value for macMaxBE parameter. */
#define MAC_MIN_MAX_BE                    3
/**@brief   Maximum value for macMaxBE parameter. */
#define MAC_MAX_MAX_BE                    8

/**@brief   Minimum value for macSuperframeOrder parameter. */
#define MAC_MIN_SUPERFRAME_ORDER          0
/**@brief   Maximum value for macSuperframeOrder parameter. */
#define MAC_MAX_SUPERFRAME_ORDER          15

/**@brief   Minimum value for macMaxFrameRetries parameter. */
#define MAC_MIN_MAX_FRAME_RETRIES         0
/**@brief   Maximum value for macMaxFrameRetries parameter. */
#define MAC_MAX_MAX_FRAME_RETRIES         7

/**@brief   Minimum value for macResponseWaitTime parameter. */
#define MAC_MIN_RESPONSE_WAIT_TIME        2
/**@brief   Maximum value for macResponseWaitTime parameter. */
#define MAC_MAX_RESPONSE_WAIT_TIME        64

/**@brief A handy macro for a never initialized short address. */
#define MAC_SHORT_ADDRESS_NOT_SET         0xFFFF

/**@brief A handy macro for a never initialized short address. */
#define MAC_EXTENDED_ADDRESS_NOT_SET      0xFFFFFFFFFFFFFFFFULL

/**@brief A value of MAC beacon order attribute which determines
 * a state with no periodic beacons.
 */
#define MAC_NO_BEACONS                    15

/**@brief A handy macro for broadcast address. */
#define MAC_BROADCAST_SHORT_ADDRESS       0xFFFF

/**@brief A handy macro for unknown PAN ID. */
#define MAC_BROADCAST_PANID               0xFFFF

/**@brief Short address field value that is used when the device does not
 * support short addressing mode.
 */
#define MAC_EXTENDED_ADDRESS_ONLY         0xFFFE

/**@brief Final CAP slot field value in the beacon for non-beacon enabled PAN. */
#define MAC_FINAL_CAP_SLOT_NBPAN          15

/**@brief Total amount of slots available in beacon enabled PAN. */
#define MAC_SLOT_AMOUNT                   16

/**@brief This is the value of auto request key index until it has been set. */
#define MAC_SECURITY_KEY_INDEX_NOT_SET    0xFF

/**@brief Length of short MAC address in bytes. */
#define MAC_ADDR_SHORT_LEN                2

/**@brief Length of extended MAC address in bytes. */
#define MAC_ADDR_EXTENDED_LEN             8

/**@brief Length of PAN ID field in bytes. */
#define MAC_PAN_ID_LEN                    2

/**@brief MAC footer (FCS) size. */
#define MAC_MFR_SIZE                      2

/**@brief   Maximum auxiliary header length */
#if (CONFIG_SECURE == 1)
#define MAC_MAX_AUX_HEADER_SIZE  14
#else
#define MAC_MAX_AUX_HEADER_SIZE  0
#endif

/**@brief   Maximum MAC header length */
#define MAC_MAX_MHR_SIZE         (PHY_MAX_HEADER_SIZE + \
                                  2 /* Frame control */ + \
                                  1 /* Data sequence number */ + \
                                  2 * (sizeof(uint16_t) + (sizeof(uint64_t))) /* Two PAN IDs and extended addresses */ + \
                                  MAC_MAX_AUX_HEADER_SIZE)
/**@brief   Maximum MAC header length for beacon frame */
#define MAC_MAX_BCN_MHR_SIZE     (PHY_MAX_HEADER_SIZE + \
                                  2 /* Frame control field */ + \
                                  1 /* Beacon sequence number */ + \
                                  sizeof(uint16_t) /* PAN ID */ + \
                                  sizeof(uint64_t) /* Extended address */ + \
                                  MAC_MAX_AUX_HEADER_SIZE)


/**@brief   Memory which should be reserved for MAC fields  */
#if (CONFIG_SECURE == 1)
#define MAC_MEMORY_RESERVE       (MAC_MAX_MHR_SIZE + MAX_MIC_SIZE + MAC_MFR_SIZE)
#else
#define MAC_MEMORY_RESERVE       (MAC_MAX_MHR_SIZE + MAC_MFR_SIZE)
#endif

/**@brief   Offset of MAC payload in the frame buffer */
#define MAC_MAX_MSDU_OFFSET           MAC_MAX_MHR_SIZE

/**@brief Possible MAC frame types. */
typedef enum
{
    MAC_BEACON,                         /**< Frame is a beacon. */
    MAC_DATA,                           /**< Frame is a data frame. */
    MAC_ACK,                            /**< Frame is a MAC ACKnowledgement. */
    MAC_COMMAND                         /**< Frame is a MAC command. */
} mac_frame_type_t;

/**@brief MAC ADDRESS. */
typedef union
{
    uint16_t short_address;             /**< 16-bit short address. */
    uint64_t long_address;              /**< 64-bit long address. */
} mac_addr_t;

/**@brief MAC ADDR MODE. */
typedef enum
{
    MAC_ADDR_NONE  = 0,                 /**< NO address is used. */
    MAC_ADDR_SHORT = 2,                 /**< Short address is used. */
    MAC_ADDR_LONG  = 3                  /**< Long address is used. */
} mac_addr_mode_t;

typedef enum
{
    MAC_FRAME_VERSION_2003,             /**< IEEE 802.15.4-2003 compliant. */
    MAC_FRAME_VERSION_2006              /**< IEEE 802.15.4-2006 compliant. */
} mac_frame_version_t;

/**
 * @brief MAC status
 *
 * In accordance with IEEE Std 802.15.4-2006, section 7.1.17
 * excluding:
 * MAC_IS_NOT_AVAILABLE
 * This status is necessary for synchronous API.
 */
typedef enum
{
    MAC_SUCCESS                   = 0x00, /* 0   */     /**< Operation is successful. */
    MAC_COUNTER_ERROR             = 0xDB, /* 219 */     /**< The frame counter purportedly applied
                                                             by the originator of the received
                                                             frame is invalid. */
    MAC_IMPROPER_KEY_TYPE         = 0xDC, /* 220 */     /**< The key purportedly applied by the
                                                             originator of the received frame is
                                                             not allowed to be used with that
                                                             frame type according to the key usage
                                                             policy of the recipient. */
    MAC_IMPROPER_SECURITY_LEVEL   = 0xDD, /* 221 */     /**< The security level purportedly applied
                                                             by the originator of the received
                                                             frame does not meet the minimum
                                                             security level required/expected by
                                                             the recipient for that frame type. */
    MAC_UNSUPPORTED_LEGACY        = 0xDE, /* 222 */     /**< The received frame was purportedly
                                                             secured using security based on IEEE
                                                             Std 802.15.4-2003, and such security
                                                             is not supported by this standard. */
    MAC_UNSUPPORTED_SECURITY      = 0xDF, /* 223 */     /**< The security purportedly applied by
                                                             the originator of the received frame
                                                             is not supported. */
    MAC_BEACON_LOSS               = 0xE0, /* 224 */     /**< The beacon was lost following a
                                                             synchronization request. */
    MAC_CHANNEL_ACCESS_FAILURE    = 0xE1, /* 225 */     /**< A transmission could not take place
                                                             due to activity on the channel, i.e.
                                                             the CSMA-CA mechanism has failed. */
    MAC_DENIED                    = 0xE2, /* 226 */     /**< The GTS request has been denied by
                                                             the PAN coordinator. */
    MAC_DISABLE_TRX_FAILURE       = 0xE3, /* 227 */     /**< The attempt to disable the
                                                             transceiver has failed. */
    MAC_SECURITY_ERROR            = 0xE4, /* 228 */     /**< Cryptographic processing of the
                                                             received secured frame failed. */
    MAC_FRAME_TOO_LONG            = 0xE5, /* 229 */     /**< Either a frame resulting from
                                                             processing has a length that is
                                                             greater than aMaxPHYPacketSize or
                                                             a requested transaction is too large
                                                             to fit in the CAP or GTS. */
    MAC_INVALID_GTS               = 0xE6, /* 230 */     /**< The requested GTS transmission failed
                                                             because the specified GTS either did
                                                             not have a transmit GTS direction or
                                                             was not defined. */
    MAC_INVALID_HANDLE            = 0xE7, /* 231 */     /**< A request to purge an MSDU from the
                                                             transaction queue was made using an
                                                             MSDU handle that was not found in
                                                             the transaction table. */
    MAC_INVALID_PARAMETER         = 0xE8, /* 232 */     /**< A parameter in the primitive is
                                                             either not supported or is out of
                                                             the valid range. */
    MAC_NO_ACK                    = 0xE9, /* 233 */     /**< No acknowledgment was received after
                                                             macMaxFrameRetries. */
    MAC_NO_BEACON                 = 0xEA, /* 234 */     /**< A scan operation failed to find any
                                                             network beacons. */
    MAC_NO_DATA                   = 0xEB, /* 235 */     /**< No response data was available
                                                             following a request. */
    MAC_NO_SHORT_ADDRESS          = 0xEC, /* 236 */     /**< The operation failed because a 16-bit
                                                             short address was not allocated. */
    MAC_OUT_OF_CAP                = 0xED, /* 237 */     /**< A receiver enable request was
                                                             unsuccessful because it could not be
                                                             completed within the CAP.
                                                             @note The enumeration description is
                                                             not used in this standard, and it is
                                                             included only to meet the backwards
                                                             compatibility requirements for
                                                             IEEE Std 802.15.4-2003. */
    MAC_PAN_ID_CONFLICT           = 0xEE, /* 238 */     /**< A PAN identifier conflict has been
                                                             detected and communicated to the PAN
                                                             coordinator. */
    MAC_REALIGNMENT               = 0xEF, /* 239 */     /**< A coordinator realignment command has
                                                             been received. */
    MAC_TRANSACTION_EXPIRED       = 0xF0, /* 240 */     /**< The transaction has expired and its
                                                             information was discarded. */
    MAC_TRANSACTION_OVERFLOW      = 0xF1, /* 241 */     /**< There is no capacity to store the
                                                             transaction. */
    MAC_TX_ACTIVE                 = 0xF2, /* 242 */     /**< The transceiver was in the transmitter
                                                             enabled state when the receiver was
                                                             requested to be enabled.
                                                             @note The enumeration description is
                                                             not used in this standard, and it is
                                                             included only to meet the backwards
                                                             compatibility requirements for
                                                             IEEE Std 802.15.4-2003. */
    MAC_UNAVAILABLE_KEY           = 0xF3, /* 243 */     /**< The key purportedly used by the
                                                             originator of the received frame is
                                                             not available or, if available, the
                                                             originating device is not known or is
                                                             blacklisted with that particular
                                                             key. */
    MAC_UNSUPPORTED_ATTRIBUTE     = 0xF4, /* 244 */     /**< A SET/GET request was issued with the
                                                             identifier of a PIB attribute that is
                                                             not supported. */
    MAC_INVALID_ADDRESS           = 0xF5, /* 245 */     /**< A request to send data was
                                                             unsuccessful because neither the source
                                                             address parameters nor the destination
                                                             address parameters were present. */
    MAC_ON_TIME_TOO_LONG          = 0xF6, /* 246 */     /**< A receiver enable request was
                                                             unsuccessful because it specified a
                                                             number of symbols that was longer than
                                                             the beacon interval. */
    MAC_PAST_TIME                 = 0xF7, /* 247 */     /**< A receiver enable request was
                                                             unsuccessful because it could not be
                                                             completed within the current superframe
                                                             and was not permitted to be deferred
                                                             until the next superframe. */
    MAC_TRACKING_OFF              = 0xF8, /* 248 */     /**< The device was instructed to start
                                                             sending beacons based on the timing
                                                             of the beacon transmissions of its
                                                             coordinator, but the device is not
                                                             currently tracking the beacon of its
                                                             coordinator. */
    MAC_INVALID_INDEX             = 0xF9, /* 249 */     /**< An attempt to write to a MAC PIB
                                                             attribute that is in a table failed
                                                             because the specified table index
                                                             was out of range. */
    MAC_LIMIT_REACHED             = 0xFA, /* 250 */     /**< A scan operation terminated
                                                             prematurely because the number of
                                                             PAN descriptors stored reached an
                                                             implementation specified maximum. */
    MAC_READ_ONLY                 = 0xFB, /* 251 */     /**< A SET/GET request was issued with the
                                                             identifier of an attribute that is
                                                             read only. */
    MAC_SCAN_IN_PROGRESS          = 0xFC, /* 252 */     /**< A request to perform a scan operation
                                                             failed because the MLME was in the
                                                             process of performing a previously
                                                             initiated scan operation. */
    MAC_SUPERFRAME_OVERLAP        = 0xFD, /* 253 */     /**< The device was instructed to start
                                                             sending beacons based on the timing
                                                             of the beacon transmissions of its
                                                             coordinator, but the instructed start
                                                             time overlapped the transmission time
                                                             of the beacon of its coordinator. */
    /* Statuses out from standard. It is used for synchronous API */
    MAC_IS_NOT_AVAILABLE          = 0xFF  /* 255 */     /**< MAC is not available. */
} mac_status_t;

/**
 * @brief   Payload descriptor.
 *
 * @details Not covered by the standard.
 *          Contains information sufficient to allow the next higher layer to clean
 *          the memory allocated for incoming frames.
 */
typedef struct
{
    /**
     * Pointer to the set of octets forming the frame payload being indicated by
     * the MAC sublayer entity.
     */
    uint8_t               * p_payload;
    /**
     * Offset of the payload data relative to the beginning of the frame.
     * Equal to the MAC header.
     */
    uint8_t                 payload_offset;
} mac_payload_descriptor_t;

/** @brief Command frame IDs defined by the MAC sublayer that are listed
 *  in Table 82 of the standard.
 */
typedef enum
{
    MAC_CMD_ASSOC_REQ            = 0x01, /**< Association request.*/
    MAC_CMD_ASSOC_RESP           = 0x02, /**< Association response.*/
    MAC_CMD_DISASSOC_NTF         = 0x03, /**< Disassociation notification.*/
    MAC_CMD_DATA_REQ             = 0x04, /**< Data request.*/
    MAC_CMD_PANID_CONFLICT_NTF   = 0x05, /**< PAN ID conflict notification.*/
    MAC_CMD_ORPHAN_NTF           = 0x06, /**< Orphan notification.*/
    MAC_CMD_BEACON_REQ           = 0x07, /**< Beacon request.*/
    MAC_CMD_COORD_REALIGN        = 0x08, /**< Coordinator realignment.*/
    MAC_CMD_GTS_REQ              = 0x09  /**< GTS request.*/
} mac_command_id_t;
/** @} */


#endif // MAC_COMMON_H_INCLUDED
