ca821x_api.h

Go to the documentation of this file.

/*
 *  Copyright (c) 2019, Cascoda Ltd.
 *  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 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 the copyright holder nor the
 *     names of its contributors may be used to endorse or promote products
 *     derived from this software without specific prior written permission.
 *
 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER 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 CA821X_API_H
#define CA821X_API_H
 
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
 
#include "ca821x_config.h"
#include "ca821x_endian.h"
#include "ca821x_error.h"
#include "ca821x_log.h"
#include "evbme_messages.h"
#include "mac_messages.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
#if CASCODA_CA_VER != 8210 && CASCODA_CA_VER != 8211 && CASCODA_CA_VER != 8212
#error "UNSUPPORTED CASCODA_CA_VER VERSION (or build incorrectly configured - use cmake)"
#endif
 
struct ca821x_dev;
 
/******************************************************************************/
/****** External function pointers                                       ******/
/******************************************************************************/
 
/***************************************************************************/ 
struct ca821x_api_callbacks
{
    MCPS_DATA_indication_callback MCPS_DATA_indication;
    MCPS_DATA_confirm_callback    MCPS_DATA_confirm;
#if CASCODA_CA_VER >= 8211
    PCPS_DATA_indication_callback PCPS_DATA_indication;
    PCPS_DATA_confirm_callback    PCPS_DATA_confirm;
    MLME_POLL_indication_callback MLME_POLL_indication;
#endif // CASCODA_CA_VER >= 8211
#if CASCODA_CA_VER >= 8212
    MLME_POLL_confirm_callback         MLME_POLL_confirm;
    MLME_IE_NOTIFY_indication_callback MLME_IE_NOTIFY_indication;
#endif // CASCODA_CA_VER >= 8212
    MLME_ASSOCIATE_indication_callback     MLME_ASSOCIATE_indication;
    MLME_ASSOCIATE_confirm_callback        MLME_ASSOCIATE_confirm;
    MLME_DISASSOCIATE_indication_callback  MLME_DISASSOCIATE_indication;
    MLME_DISASSOCIATE_confirm_callback     MLME_DISASSOCIATE_confirm;
    MLME_BEACON_NOTIFY_indication_callback MLME_BEACON_NOTIFY_indication;
    MLME_ORPHAN_indication_callback        MLME_ORPHAN_indication;
    MLME_SCAN_confirm_callback             MLME_SCAN_confirm;
    MLME_COMM_STATUS_indication_callback   MLME_COMM_STATUS_indication;
    MLME_SYNC_LOSS_indication_callback     MLME_SYNC_LOSS_indication;
    HWME_WAKEUP_indication_callback        HWME_WAKEUP_indication;
    TDME_RXPKT_indication_callback         TDME_RXPKT_indication;
    TDME_EDDET_indication_callback         TDME_EDDET_indication;
    TDME_ERROR_indication_callback         TDME_ERROR_indication;
    ca_error (*generic_dispatch)(const struct MAC_Message *msg, struct ca821x_dev *pDeviceRef);
};
 
struct ca821x_dev
{
    void *context;
    void *exchange_context;
 
    struct ca821x_api_callbacks callbacks;
 
#if CASCODA_CA_VER == 8210
    uint8_t  extaddr[8]; 
    uint16_t shortaddr;  
    uint8_t  lqi_mode;   
#endif                   // CASCODA_CA_VER == 8210
 
    //MAC Workarounds for V1.1 and MPW silicon (V0.x)
    uint8_t MAC_MPW; 
#if CASCODA_MAC_BLACKLIST != 0
    struct MacAddr blacklist[CASCODA_MAC_BLACKLIST];
 
#endif
};
 
/******************************************************************************/
/****** MAC MCPS/MLME Downlink                                           ******/
/******************************************************************************/
 
#if CASCODA_CA_VER >= 8212
/******************************************************************************/
/***************************************************************************/ 
ca_mac_status MCPS_DATA_request(uint8_t            SrcAddrMode,
                                struct FullAddr    DstAddr,
                                uint8_t            HeaderIELength,
                                uint8_t            PayloadIELength,
                                uint8_t            MsduLength,
                                uint8_t           *pMsdu,
                                uint8_t            MsduHandle,
                                uint8_t           *pTxOptions,
                                uint32_t           SchTimestamp,
                                uint16_t           SchPeriod,
                                uint8_t            TxChannel,
                                uint8_t           *pHeaderIEList,
                                uint8_t           *pPayloadIEList,
                                struct SecSpec    *pSecurity,
                                struct ca821x_dev *pDeviceRef);
#else
/******************************************************************************/
/***************************************************************************/ 
ca_mac_status MCPS_DATA_request(uint8_t            SrcAddrMode,
                                struct FullAddr    DstAddr,
                                uint8_t            MsduLength,
                                uint8_t           *pMsdu,
                                uint8_t            MsduHandle,
                                uint8_t            TxOptions,
                                struct SecSpec    *pSecurity,
                                struct ca821x_dev *pDeviceRef);
#endif // CASCODA_CA_VER >= 8212
 
/******************************************************************************/
/***************************************************************************/ 
ca_mac_status MCPS_PURGE_request_sync(uint8_t *MsduHandle, struct ca821x_dev *pDeviceRef);
 
#if CASCODA_CA_VER >= 8212
/******************************************************************************/
/***************************************************************************/ 
ca_mac_status PCPS_DATA_request(uint8_t            PsduHandle,
                                uint8_t            TxOpts,
                                uint8_t            PsduLength,
                                uint8_t           *pPsdu,
                                uint32_t           SchTimestamp,
                                uint16_t           SchPeriod,
                                struct ca821x_dev *pDeviceRef);
#else
/******************************************************************************/
/***************************************************************************/ 
ca_mac_status PCPS_DATA_request(uint8_t            PsduHandle,
                                uint8_t            TxOpts,
                                uint8_t            PsduLength,
                                uint8_t           *pPsdu,
                                struct ca821x_dev *pDeviceRef);
#endif // CASCODA_CA_VER >= 8212
 
/******************************************************************************/
/***************************************************************************/ 
ca_mac_status MLME_ASSOCIATE_request(uint8_t            LogicalChannel,
                                     struct FullAddr    DstAddr,
                                     uint8_t            CapabilityInfo,
                                     struct SecSpec    *pSecurity,
                                     struct ca821x_dev *pDeviceRef);
 
/******************************************************************************/
/***************************************************************************/ 
ca_mac_status MLME_ASSOCIATE_response(uint8_t           *pDeviceAddress,
                                      uint16_t           AssocShortAddress,
                                      uint8_t            Status,
                                      struct SecSpec    *pSecurity,
                                      struct ca821x_dev *pDeviceRef);
 
/******************************************************************************/
/***************************************************************************/ 
ca_mac_status MLME_DISASSOCIATE_request(struct FullAddr    DevAddr,
                                        uint8_t            DisassociateReason,
                                        uint8_t            TxIndirect,
                                        struct SecSpec    *pSecurity,
                                        struct ca821x_dev *pDeviceRef);
 
/******************************************************************************/
/***************************************************************************/ 
ca_mac_status MLME_GET_request_sync(uint8_t            PIBAttribute,
                                    uint8_t            PIBAttributeIndex,
                                    uint8_t           *pPIBAttributeLength,
                                    void              *pPIBAttributeValue,
                                    struct ca821x_dev *pDeviceRef);
 
/******************************************************************************/
/***************************************************************************/ 
ca_mac_status MLME_ORPHAN_response(uint8_t           *pOrphanAddress,
                                   uint16_t           ShortAddress,
                                   uint8_t            AssociatedMember,
                                   struct SecSpec    *pSecurity,
                                   struct ca821x_dev *pDeviceRef);
 
/******************************************************************************/
/***************************************************************************/ 
ca_mac_status MLME_RESET_request_sync(uint8_t SetDefaultPIB, struct ca821x_dev *pDeviceRef);
 
/******************************************************************************/
/***************************************************************************/ 
ca_mac_status MLME_RX_ENABLE_request_sync(uint8_t            DeferPermit,
                                          uint32_t           RxOnTime,
                                          uint32_t           RxOnDuration,
                                          struct ca821x_dev *pDeviceRef);
 
/******************************************************************************/
/***************************************************************************/ 
ca_mac_status MLME_SCAN_request(uint8_t            ScanType,
                                uint32_t           ScanChannels,
                                uint8_t            ScanDuration,
                                struct SecSpec    *pSecurity,
                                struct ca821x_dev *pDeviceRef);
 
/******************************************************************************/
/***************************************************************************/ 
ca_mac_status MLME_SET_request_sync(uint8_t            PIBAttribute,
                                    uint8_t            PIBAttributeIndex,
                                    uint8_t            PIBAttributeLength,
                                    const void        *pPIBAttributeValue,
                                    struct ca821x_dev *pDeviceRef);
 
/******************************************************************************/
/***************************************************************************/ 
ca_mac_status MLME_START_request_sync(uint16_t           PANId,
                                      uint8_t            LogicalChannel,
                                      uint8_t            BeaconOrder,
                                      uint8_t            SuperframeOrder,
                                      uint8_t            PANCoordinator,
                                      uint8_t            BatteryLifeExtension,
                                      uint8_t            CoordRealignment,
                                      struct SecSpec    *pCoordRealignSecurity,
                                      struct SecSpec    *pBeaconSecurity,
                                      struct ca821x_dev *pDeviceRef);
 
#if CASCODA_CA_VER >= 8212
/******************************************************************************/
/***************************************************************************/ 
ca_mac_status MLME_POLL_request(struct FullAddr    CoordAddress,
                                uint8_t            FrameVersion,
                                struct SecSpec    *pSecurity,
                                struct ca821x_dev *pDeviceRef);
#elif CASCODA_CA_VER == 8211
/******************************************************************************/
/***************************************************************************/ 
ca_mac_status MLME_POLL_request_sync(struct FullAddr    CoordAddress,
                                     struct SecSpec    *pSecurity,
                                     struct ca821x_dev *pDeviceRef);
#else
/******************************************************************************/
/***************************************************************************/ 
ca_mac_status MLME_POLL_request_sync(struct FullAddr    CoordAddress,
                                     uint8_t            Interval[2],
                                     struct SecSpec    *pSecurity,
                                     struct ca821x_dev *pDeviceRef);
#endif // CASCODA_CA_VER >= 8212
 
/******************************************************************************/
/****** HWME Downlink                                                    ******/
/******************************************************************************/
 
/******************************************************************************/
/***************************************************************************/ 
ca_mac_status HWME_SET_request_sync(uint8_t            HWAttribute,
                                    uint8_t            HWAttributeLength,
                                    uint8_t           *pHWAttributeValue,
                                    struct ca821x_dev *pDeviceRef);
 
/******************************************************************************/
/***************************************************************************/ 
ca_mac_status HWME_GET_request_sync(uint8_t            HWAttribute,
                                    uint8_t           *HWAttributeLength,
                                    uint8_t           *pHWAttributeValue,
                                    struct ca821x_dev *pDeviceRef);
 
/******************************************************************************/
/***************************************************************************/ 
ca_mac_status HWME_HAES_request_sync(uint8_t HAESMode, uint8_t *pHAESData, struct ca821x_dev *pDeviceRef);
 
/******************************************************************************/
/****** TDME Downlink                                                    ******/
/******************************************************************************/
 
/******************************************************************************/
/***************************************************************************/ 
ca_mac_status TDME_SETSFR_request_sync(uint8_t            SFRPage,
                                       uint8_t            SFRAddress,
                                       uint8_t            SFRValue,
                                       struct ca821x_dev *pDeviceRef);
 
/******************************************************************************/
/***************************************************************************/ 
ca_mac_status TDME_GETSFR_request_sync(uint8_t            SFRPage,
                                       uint8_t            SFRAddress,
                                       uint8_t           *SFRValue,
                                       struct ca821x_dev *pDeviceRef);
 
/******************************************************************************/
/***************************************************************************/ 
ca_mac_status TDME_TESTMODE_request_sync(uint8_t TestMode, struct ca821x_dev *pDeviceRef);
 
/******************************************************************************/
/***************************************************************************/ 
ca_mac_status TDME_SET_request_sync(uint8_t            TestAttribute,
                                    uint8_t            TestAttributeLength,
                                    void              *pTestAttributeValue,
                                    struct ca821x_dev *pDeviceRef);
 
/******************************************************************************/
/***************************************************************************/ 
ca_mac_status TDME_TXPKT_request_sync(uint8_t            TestPacketDataType,
                                      uint8_t           *TestPacketSequenceNumber,
                                      uint8_t           *TestPacketLength,
                                      void              *pTestPacketData,
                                      struct ca821x_dev *pDeviceRef);
 
/******************************************************************************/
/***************************************************************************/ 
ca_mac_status TDME_LOTLK_request_sync(uint8_t           *TestChannel,
                                      uint8_t           *TestRxTxb,
                                      uint8_t           *TestLOFDACValue,
                                      uint8_t           *TestLOAMPValue,
                                      uint8_t           *TestLOTXCALValue,
                                      struct ca821x_dev *pDeviceRef);
 
/******************************************************************************/
/****** TDME Register Default Initialisation and Checking Functions      ******/
/******************************************************************************/
 
/******************************************************************************/
/***************************************************************************/ 
ca_mac_status TDME_ChipInit(struct ca821x_dev *pDeviceRef);
 
/******************************************************************************/
/***************************************************************************/ 
ca_mac_status TDME_ChannelInit(uint8_t channel, struct ca821x_dev *pDeviceRef);
 
/******************************************************************************/
/***************************************************************************/ 
ca_mac_status TDME_CheckPIBAttribute(uint8_t PIBAttribute, uint8_t PIBAttributeLength, const void *pPIBAttributeValue);
 
/******************************************************************************/
/***************************************************************************/ 
ca_mac_status TDME_SetTxPower(uint8_t txp, struct ca821x_dev *pDeviceRef);
 
/******************************************************************************/
/***************************************************************************/ 
ca_mac_status TDME_GetTxPower(uint8_t *txp, struct ca821x_dev *pDeviceRef);
 
/******************************************************************************/
/***************************************************************************/ 
uint8_t TDME_tx_dbm_to_paib(int8_t txpdbm);
 
/******************************************************************************/
/***************************************************************************/ 
int8_t TDME_tx_paib_to_dbm(uint8_t paib);
 
/******************************************************************************/
/****** API meta functions                                           ******/
/******************************************************************************/
 
/******************************************************************************/
/***************************************************************************/ 
ca_error ca821x_api_init(struct ca821x_dev *pDeviceRef);
 
/******************************************************************************/
/***************************************************************************/ 
union ca821x_api_callback *ca821x_get_callback(uint8_t cmdid, struct ca821x_dev *pDeviceRef);
 
/******************************************************************************/
/***************************************************************************/ 
uint8_t ca821x_get_sync_response_id(uint8_t cmdid);
 
/***************************************************************************/ 
const char *ca821x_get_version(void);
 
/***************************************************************************/ 
const char *ca821x_get_version_nodate(void);
 
/******************************************************************************/
/***************************************************************************/ 
ca_error ca821x_upstream_dispatch(struct MAC_Message *msg, struct ca821x_dev *pDeviceRef);
 
/******************************************************************************/
/***************************************************************************/ 
ca_error ca821x_api_downstream(const uint8_t *buf, uint8_t *response, struct ca821x_dev *pDeviceRef);
 
#ifdef __cplusplus
}
#endif
 
#endif // CA821X_API_H