mac_sap.h

此程式庫有許多的zigbee程式源碼

/****************************************************************************
 *
 * MODULE:             ZED-MAC
 *
 * COMPONENT:          $RCSfile: mac_sap.h,v $
 *
 * VERSION:            $Name: zed003_cd $
 *
 * REVISION:           $Revision: 1.1 $
 *
 * DATED:              $Date: 2006/02/16 15:38:04 $
 *
 * STATUS:             $State: Exp $
 *
 * AUTHOR:             rcc
 *
 * DESCRIPTION:
 * ZED 802.15.4 Media Access Controller
 * SAP interface for MLME and MCPS
 *
 * LAST MODIFIED BY:   $Author: cjg $
 *                     $Modtime$
 *
 *
 ****************************************************************************
 *
 *  (c) Copyright 2005, Jennic Limited
 *
 ****************************************************************************/

/**
 * @defgroup g_mac_sap MAC layer Service Access Point (SAP)
 */

/**
 * @defgroup g_mac_sap_pib PIB parameters
 *
 * Parameters associated with setting or getting PIB values
 * @ingroup g_mac_sap
 */

/**
 * @defgroup g_mac_sap_addr Addressing parameters
 *
 * Parameters associated with addressing
 * @ingroup g_mac_sap
 */

/**
 * @defgroup g_mac_sap_pdu PDU Framing parameters
 *
 * Parameters associated with PDU framing
 * @ingroup g_mac_sap
 */

/**
 * @defgroup g_mac_sap_sec Security parameters
 *
 * Parameters associated with security
 * @ingroup g_mac_sap
 */

/**
 * @defgroup g_mac_sap_scan Scanning parameters
 *
 * Parameters associated with scanning
 * @ingroup g_mac_sap
 */

/**
 * @defgroup g_mac_sap_bcn Beacon parameters
 *
 * Parameters associated with beaconing
 * @ingroup g_mac_sap
 */

/**
 * @defgroup g_mac_sap_mlme MAC SAP sublayer management entity (MLME)
 *
 * The MLME SAP API provides calls to conforming to the MLME SAP in [1]
 * @ingroup g_mac_sap
 */

/**
 * @defgroup g_mac_sap_mcps MAC SAP common part sublayer (MCPS)
 *
 * The MCPS SAP API provides calls to conforming to the MCPS SAP in [1]
 * @ingroup g_mac_sap
 */

/**
 * @defgroup g_mac_sap_vs Vendor-specific interface
 *
 * The vendor-specific SAP API provides calls which are in addition to those specified in the 802.15.4
 * specification. They are currently handled as additions to the MLME SAP interface.
 * @ingroup g_mac_sap
 */

/**
 * @mainpage Medium Access Control Layer Service Access Point Application Programmer's Interface
 *
 * @section p_mac_sap_intro Introduction
 * The Medium Access Control (MAC) Layer Service Access Point (SAP) Application Programmer's Interface (API)
 * provides the interface to the top of the MAC layer required by higher layer in the application programming.
 * The next layer up is typically the network layer.
 *
 * @section p_mac_sap_app Application interface
 * There is an Application interface which sits on top of the MAC SAP. It wraps the
 * initialisation and baseband interrupt handling, and provides a simple call/callback API
 * for access to the MAC SAP.
 *
 * See @link g_app_sap Application interface@endlink
 *
 * @section p_mac_sap_categories Categories within MAC SAP
 * - MCPS SAP API: See @link g_mac_sap_mcps MCPS SAP pages@endlink
 * - MLME SAP API: See @link g_mac_sap_mlme MLME SAP pages@endlink
 * - Vendor-specific SAP API: See @link g_mac_sap_vs Vendor-specific pages@endlink
 * - MAC PIB Direct Access: See @link g_mac_pib PIB direct access pages@endlink
 *
 * @section p_disclaimer Disclaimer
 * This document is subject to change. Please contact Jennic Ltd. for more information
 */

#ifndef _mac_sap_h_
#define _mac_sap_h_

#ifdef __cplusplus
extern "C" {
#endif

/***********************/
/**** INCLUDE FILES ****/
/***********************/

#include "jendefs.h"

/************************/
/**** MACROS/DEFINES ****/
/************************/

/* Literals */

/**
 * @name PHY constants
 * @ingroup g_mac_sap
 * PHY constants 'used' by the MAC
 * @{
 */
/** Maximum PHY packet (PDU) size */
#define MAC_MAX_PHY_PKT_SIZE            127
/** PHY turnaround time */
#define MAC_PHY_TURNAROUND_TIME         12
/* @} */

/**
 * @name Address sizes
 * @ingroup g_mac_sap_addr
 * Sizes of address fields in SAP structures
 * @{
 */
/** PAN ID field size in octets */
#define MAC_PAN_ID_LEN                  2
/** Short address field size in octets */
#define MAC_SHORT_ADDR_LEN              2
/** Extended address field size in octets */
#define MAC_EXT_ADDR_LEN                8
/** Extended address field size in words (32 bit) */
#define MAC_EXT_ADDR_LEN_WORDS          2
/* @} */

/**
 * @name Frame overheads
 * @ingroup g_mac_sap_pdu
 * Header size overheads for frames
 * @{
 */
/** Minimum Data Frame overhead */
#define MAC_MIN_DATA_FRM_OVERHEAD       9
/** Maximum Data Frame overhead */
#define MAC_MAX_DATA_FRM_OVERHEAD       25
/** Minimum Beacon Frame overhead */
#define MAC_MIN_BEACON_FRM_OVERHEAD     9
/** Maximum Beacon Frame overhead */
#define MAC_MAX_BEACON_FRM_OVERHEAD     15
/* @} */

/**
 * @name Payload maxima
 * @ingroup g_mac_sap_pdu
 * Maximum size of payloads
 * @{
 */
/** Maximum Data Frame payload */
#define MAC_MAX_DATA_PAYLOAD_LEN      (MAC_MAX_PHY_PKT_SIZE - MAC_MIN_DATA_FRM_OVERHEAD)
/** Maximum Beacon Frame payload */
#define MAC_MAX_BEACON_PAYLOAD_LEN    (MAC_MAX_PHY_PKT_SIZE - MAC_MIN_BEACON_FRM_OVERHEAD)
/* @} */

/**
 * @name PIB constants
 * @ingroup g_mac_sap_pib
 * PIB constant values
 * @{
 */
/** @a aNumSuperframeSlots: Maximum number of superframe slots */
#define MAC_NUM_SUPERFRAME_SLOTS        16
/** @a aMaxBeaconOverhead: Maximum beacon overhead */
#define MAC_MAX_BEACON_OVERHEAD         75
/** @a aBaseSlotDuration */
#define MAC_BASE_SLOT_DURATION          60
/** @a aBaseSuperframeDuration */
#define MAC_BASE_SUPERFRAME_DURATION    (MAC_BASE_SLOT_DURATION * MAC_NUM_SUPERFRAME_SLOTS)
/** @a aResponseWaitTime */
#define MAC_RESPONSE_WAIT_TIME          (32 * MAC_BASE_SUPERFRAME_DURATION)
/** @a aMinLIFSPeriod: Minimum number of symbols in a LIFS period */
#define MAC_MIN_LIFS_PERIOD             40
/** @a aMinSIFSPeriod: Minimum number of symbols in a SIFS period */
#define MAC_MIN_SIFS_PERIOD             12
/** @a aMinCAPLength: Minimum CAP length */
#define MAC_MIN_CAP_LENGTH              440
/** @a aMaxFrameResponseTime: Maximum frame response time */
#define MAC_MAX_FRAME_RESPONSE_TIME     1220
/** @a aUnitBackoffPeriod: Number of symbols for CSMA/CA backoff */
#define MAC_UNIT_BACKOFF_PERIOD         20
/** @a aMaxFrameRetries: Maximum number of CSMA/CA retries */
#define MAC_MAX_FRAME_RETRIES           3
/** @a aMaxLostBeacons: Maximum number of lost beacons before sync loss */
#define MAC_MAX_LOST_BEACONS            4
/** @a aGTSDescPersistenceTime: How many beacons a GTS descriptor persists for */
#define MAC_GTS_DESC_PERSISTENCE_TIME   4
/* @} */

/**
 * @name Scan constants
 * @ingroup g_mac_sap_scan
 * Scan constant values not in PIB
 * @note MAC_MAX_SCAN_PAN_DESCRS is configurable
 * @{
 */
/** Maximum number of scan channel (2.4GHz) */
#define MAC_MAX_SCAN_CHANNELS           16
/** Maximum number of PAN descriptors in record */
#define MAC_MAX_SCAN_PAN_DESCRS         8
/* @} */

/**
 * @name Security constants
 * @ingroup g_mac_sap_sec
 * Security constant values not in PIB or compile-time configurable
 * @note MAC_MAX_ACL_ENTRIES is configurable and will determine how much memory is required.
 * @{
 */
/** Maximum security material length */
#define MAC_MAX_SECURITY_MATERIAL_LEN   26
/* @} */

#define PHY_PIB_CHANNELS_SUPPORTED_DEF 0x07fff800
#define PHY_PIB_CURRENT_CHANNEL_DEF    11
#define PHY_PIB_CURRENT_CHANNEL_MIN    11
#define PHY_PIB_CURRENT_CHANNEL_MAX    26

#define PHY_PIB_TX_POWER_DEF           PHY_PIB_TX_POWER_3DB_TOLERANCE
#define PHY_PIB_TX_POWER_MIN           0
#define PHY_PIB_TX_POWER_MAX           0xbf
#define PHY_PIB_TX_POWER_MASK          0x3f
#define PHY_PIB_TX_POWER_1DB_TOLERANCE 0x00
#define PHY_PIB_TX_POWER_3DB_TOLERANCE 0x40
#define PHY_PIB_TX_POWER_6DB_TOLERANCE 0x80

#define PHY_PIB_CCA_MODE_DEF           1
#define PHY_PIB_CCA_MODE_MIN           1
#define PHY_PIB_CCA_MODE_MAX           3

/**************************/
/**** TYPE DEFINITIONS ****/
/**************************/

/****************************/
/**** General Structures ****/
/****************************/

/**
 * @ingroup g_mac_sap
 * @brief MAC SAP Type.
 *
 * Enumeration of SAP type
 */
typedef enum
{
    MAC_SAP_MLME = 0,   /**< SAP Type is MLME */
    MAC_SAP_MCPS = 1,   /**< SAP Type is MCPS */
    NUM_MAC_SAP
} MAC_Sap_e;

/**
 * @ingroup g_mac_sap
 * @brief MAC Enumeration Type.
 *
 * Enumerations as defined in Table 64 (section 7.1.17) (d18)
 * @note Refer to specification for definitive definitions.
 */
typedef enum
{
    MAC_ENUM_SUCCESS = 0,             /**< Success (0x00) */
    MAC_ENUM_BEACON_LOSS = 0xE0,      /**< Beacon loss after synchronisation request (0xE0) */
    MAC_ENUM_CHANNEL_ACCESS_FAILURE,  /**< CSMA/CA channel access failure (0xE1) */
    MAC_ENUM_DENIED,                  /**< GTS request denied (0xE2) */
    MAC_ENUM_DISABLE_TRX_FAILURE,     /**< Could not disable transmit or receive (0xE3) */
    MAC_ENUM_FAILED_SECURITY_CHECK,   /**< Incoming frame failed security check (0xE4) */
    MAC_ENUM_FRAME_TOO_LONG,          /**< Frame too long after security processing to be sent (0xE5) */
    MAC_ENUM_INVALID_GTS,             /**< GTS transmission failed (0xE6) */
    MAC_ENUM_INVALID_HANDLE,          /**< Purge request failed to find entry in queue (0xE7) */
    MAC_ENUM_INVALID_PARAMETER,       /**< Out-of-range parameter in primitive (0xE8) */
    MAC_ENUM_NO_ACK,                  /**< No acknowledgement received when expected (0xE9) */
    MAC_ENUM_NO_BEACON,               /**< Scan failed to find any beacons (0xEA) */
    MAC_ENUM_NO_DATA,                 /**< No response data after a data request (0xEB) */
    MAC_ENUM_NO_SHORT_ADDRESS,        /**< No allocated short address for operation (0xEC) */
    MAC_ENUM_OUT_OF_CAP,              /**< Receiver enable request could not be executed as CAP finished (0xED) */
    MAC_ENUM_PAN_ID_CONFLICT,         /**< PAN ID conflict has been detected (0xEE) */
    MAC_ENUM_REALIGNMENT,             /**< Coordinator realignment has been received (0xEF) */
    MAC_ENUM_TRANSACTION_EXPIRED,     /**< Pending transaction has expired and data discarded (0xF0) */
    MAC_ENUM_TRANSACTION_OVERFLOW,    /**< No capacity to store transaction (0xF1) */
    MAC_ENUM_TX_ACTIVE,               /**< Receiver enable request could not be executed as in transmit state (0xF2) */
    MAC_ENUM_UNAVAILABLE_KEY,         /**< Appropriate key is not available in ACL (0xF3) */
    MAC_ENUM_UNSUPPORTED_ATTRIBUTE    /**< PIB Set/Get on unsupported attribute (0xF4) */
} MAC_Enum_e;

/**
 * @ingroup g_mac_sap_scan
 * @brief MAC MLME Scan type.
 *
 * Enumerations as defined in Table 53 (section 7.1.11.1.1) (d18)
 */
typedef enum
{
    MAC_MLME_SCAN_TYPE_ENERGY_DETECT = 0,   /**< Energy detect scan */
    MAC_MLME_SCAN_TYPE_ACTIVE = 1,          /**< Active scan */
    MAC_MLME_SCAN_TYPE_PASSIVE = 2,         /**< Passive scan */
    MAC_MLME_SCAN_TYPE_ORPHAN = 3,          /**< Orphan scan */
    NUM_MAC_MLME_SCAN_TYPE
} MAC_MlmeScanType_e;

/**
 * @ingroup g_mac_sap_mcps
 * @brief MAC MCPS transmit options type.
 *
 * Enumerations as defined in Table 27 (section 7.1.1.1.3) (d18)
 */
typedef enum
{
    MAC_TX_OPTION_ACK      = 1,             /**< Acknowledge required */
    MAC_TX_OPTION_GTS      = 2,             /**< Transmit in GTS */
    MAC_TX_OPTION_INDIRECT = 4,             /**< Transmit indirectly */
    MAC_TX_OPTION_SECURITY = 8              /**< Use security */
} MAC_TransmitOption_e;

/**
 * @ingroup g_mac_sap_pib
 * @brief MAC PIB attribute.
 *
 * Enumerations of PIB attribute as defined in Tables 71 and 72 (section 7.5) (d18)
 * @note Refer to specification for definitive definitions.
 */
typedef enum
{
    MAC_PIB_ATTR_ACK_WAIT_DURATION = 0x40,      /**< macAckWaitDuration */
    MAC_PIB_ATTR_ASSOCIATION_PERMIT,            /**< macAssociationPermit */
    MAC_PIB_ATTR_AUTO_REQUEST,                  /**< macAutoRequest */
    MAC_PIB_ATTR_BATT_LIFE_EXT,                 /**< macBattLifeExt */
    MAC_PIB_ATTR_BATT_LIFE_EXT_PERIODS,         /**< macBattLifeExtPeriods */
    MAC_PIB_ATTR_BEACON_PAYLOAD,                /**< macBeaconPayload */
    MAC_PIB_ATTR_BEACON_PAYLOAD_LENGTH,         /**< macBeaconPayloadLength */
    MAC_PIB_ATTR_BEACON_ORDER,                  /**< macBeaconOrder */
    MAC_PIB_ATTR_BEACON_TX_TIME,                /**< macBeaconTxTime */
    MAC_PIB_ATTR_BSN,                           /**< macBSN */
    MAC_PIB_ATTR_COORD_EXTENDED_ADDRESS,        /**< macCoordExtendedAddress */
    MAC_PIB_ATTR_COORD_SHORT_ADDRESS,           /**< macCoordShortAddress */
    MAC_PIB_ATTR_DSN,                           /**< macDSN */
    MAC_PIB_ATTR_GTS_PERMIT,                    /**< macGTSPermit */
    MAC_PIB_ATTR_MAX_CSMA_BACKOFFS,             /**< macMaxCSMABackoffs */
    MAC_PIB_ATTR_MIN_BE,                        /**< macMinBE */
    MAC_PIB_ATTR_PAN_ID,                        /**< macPANId */
    MAC_PIB_ATTR_PROMISCUOUS_MODE,              /**< macPromiscuousMode */
    MAC_PIB_ATTR_RX_ON_WHEN_IDLE,               /**< macRxOnWhenIdle */
    MAC_PIB_ATTR_SHORT_ADDRESS,                 /**< macShortAddress */
    MAC_PIB_ATTR_SUPERFRAME_ORDER,              /**< macSuperframeOrder */
    MAC_PIB_ATTR_TRANSACTION_PERSISTENCE_TIME,  /**< macTransactionPersistenceTime */
    /* New for TG4b */
    MAC_PIB_ATTR_MAX_TOTAL_FRAME_TX_TIME = 0x59,/**< macMaxTotalFrameTxTime */
    MAC_PIB_ATTR_RESPONSE_WAIT_TIME = 0x5c,     /**< macResponseWaitTime */
    /* Security attributes */
    MAC_PIB_ATTR_ACL_ENTRY_DESCRIPTOR_SET = 0x70,       /**< macACLEntryDescriptorSet */
    MAC_PIB_ATTR_ACL_ENTRY_DESCRIPTOR_SET_SIZE,         /**< macACLEntryDescriptorSetSize */
    MAC_PIB_ATTR_DEFAULT_SECURITY,                      /**< macDefaultSecurity */
    MAC_PIB_ATTR_ACL_DEFAULT_SECURITY_MATERIAL_LENGTH,  /**< macACLDefaultSecurityMaterialLength */
    MAC_PIB_ATTR_DEFAULT_SECURITY_MATERIAL,             /**< macDefaultSecurityMaterial */
    MAC_PIB_ATTR_DEFAULT_SECURITY_SUITE,                /**< macDefaultSecuritySuite */
    MAC_PIB_ATTR_SECURITY_MODE,                         /**< macSecurityMode */
    NUM_MAC_ATTR_PIB                                    /**< (endstop) */
} MAC_PibAttr_e;

/*
*******************************************************************
******************** README README README *************************
*******************************************************************
Splitting the defs. like this means that GDB recognises the packing.
Please use this format throughout.
*******************************************************************
*/

/**
 * @ingroup g_mac_sap_addr
 * @brief MAC Extended Address
 *
 * Full address specification
 */
typedef struct
{
    uint32 u32L;  /**< Low word */
    uint32 u32H;  /**< High word */
} MAC_ExtAddr_s;

/**
 * @ingroup g_mac_sap_addr