Momentum-Apps/lib/ST25RFAL002/include/rfal_nfcDep.h

/******************************************************************************
  * \attention
  *
  * <h2><center>&copy; COPYRIGHT 2020 STMicroelectronics</center></h2>
  *
  * Licensed under ST MYLIBERTY SOFTWARE LICENSE AGREEMENT (the "License");
  * You may not use this file except in compliance with the License.
  * You may obtain a copy of the License at:
  *
  *        www.st.com/myliberty
  *
  * Unless required by applicable law or agreed to in writing, software 
  * distributed under the License is distributed on an "AS IS" BASIS, 
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied,
  * AND SPECIFICALLY DISCLAIMING THE IMPLIED WARRANTIES OF MERCHANTABILITY,
  * FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  *
******************************************************************************/

/*
 *      PROJECT:   ST25R391x firmware
 *      Revision:
 *      LANGUAGE:  ISO C99
 */

/*! \file rfal_nfcDep.h
 *
 *  \author  Gustavo Patricio
 *
 *  \brief Implementation of NFC-DEP protocol
 *  
 *  NFC-DEP is also known as NFCIP - Near Field Communication 
 *  Interface and Protocol
 *  
 *  This implementation was based on the following specs:
 *    - NFC Forum Digital 1.1
 *    - ECMA 340 3rd Edition 2013
 *
 *
 * \addtogroup RFAL
 * @{
 *
 * \addtogroup RFAL-AL
 * \brief RFAL Abstraction Layer
 * @{
 *
 * \addtogroup NFC-DEP
 * \brief RFAL NFC-DEP Module
 * @{
 */

#ifndef RFAL_NFCDEP_H_
#define RFAL_NFCDEP_H_

/*
 ******************************************************************************
 * INCLUDES
 ******************************************************************************
 */
#include "platform.h"
#include "st_errno.h"
#include "rfal_rf.h"

/*
 ******************************************************************************
 * ENABLE SWITCH
 ******************************************************************************
 */

#ifndef RFAL_FEATURE_NFC_DEP
#define RFAL_FEATURE_NFC_DEP \
    false /*!< NFC-DEP module configuration missing. Disabled by default */
#endif

/* If module is disabled remove the need for the user to set lengths */
#if !RFAL_FEATURE_NFC_DEP
#undef RFAL_FEATURE_NFC_DEP_BLOCK_MAX_LEN
#undef RFAL_FEATURE_NFC_DEP_PDU_MAX_LEN

#define RFAL_FEATURE_NFC_DEP_BLOCK_MAX_LEN 1U /*!< NFC-DEP Block/Payload length, set to "none" */
#define RFAL_FEATURE_NFC_DEP_PDU_MAX_LEN 1U /*!< NFC-DEP PDU length, set to "none"           */
#endif /* !RFAL_FEATURE_NFC_DEP  */

/*
 ******************************************************************************
 * DEFINES
 ******************************************************************************
 */
#define RFAL_NFCDEP_FRAME_SIZE_MAX_LEN \
    254U /*!< Maximum Frame Size   Digital 2.0 Table 90                      */
#define RFAL_NFCDEP_DEPREQ_HEADER_LEN \
    5U /*!< DEP_REQ header length: CMD_TYPE + CMD_CMD + PBF + DID + NAD    */

/*! Length NFCIP DEP REQ or RES header (incl LEN)                                                                           */
#define RFAL_NFCDEP_DEP_HEADER \
    (RFAL_NFCDEP_LEN_LEN + RFAL_NFCDEP_CMDTYPE_LEN + RFAL_NFCDEP_CMD_LEN + RFAL_NFCDEP_DEP_PFB_LEN)
#define RFAL_NFCDEP_HEADER \
    (RFAL_NFCDEP_CMDTYPE_LEN + RFAL_NFCDEP_CMD_LEN) /*!< NFCIP header length           */
#define RFAL_NFCDEP_SB_LEN \
    1U /*!< SB length on NFCIP fram for NFC-A                              */
#define RFAL_NFCDEP_LEN_LEN \
    1U /*!< LEN length on NFCIP frame                                      */
#define RFAL_NFCDEP_CMDTYPE_LEN \
    1U /*!< Length of the cmd type (REQ | RES) on NFCIP frame              */
#define RFAL_NFCDEP_CMD_LEN \
    1U /*!< Length of the cmd on NFCIP frame                               */
#define RFAL_NFCDEP_DID_LEN \
    1U /*!< Length of did on NFCIP frame                                   */
#define RFAL_NFCDEP_DEP_PFB_LEN \
    1U /*!< Length of the PFB field on NFCIP frame                         */

#define RFAL_NFCDEP_DSL_RLS_LEN_NO_DID               \
    (RFAL_NFCDEP_LEN_LEN + RFAL_NFCDEP_CMDTYPE_LEN + \
     RFAL_NFCDEP_CMD_LEN) /*!< Length of DSL_REQ and RLS_REQ with no DID */
#define RFAL_NFCDEP_DSL_RLS_LEN_DID   \
    (RFAL_NFCDEP_DSL_RLS_LEN_NO_DID + \
     RFAL_NFCDEP_DID_LEN) /*!< Length of DSL_REQ and RLS_REQ with DID    */

#define RFAL_NFCDEP_FS_VAL_MIN \
    64U /*!< Minimum LR value                                               */
#define RFAL_NFCDEP_LR_VAL_MASK \
    0x03U /*!< Bit mask for a LR value                                        */
#define RFAL_NFCDEP_PP_LR_MASK \
    0x30U /*!< Bit mask for LR value in PP byte on a ATR REQ/RES              */
#define RFAL_NFCDEP_PP_LR_SHIFT \
    4U /*!< Position of LR value in PP byte on a ATR REQ/RES               */

#define RFAL_NFCDEP_DID_MAX \
    14U /*!< Max DID value Digital 14.6.2.3                                 */
#define RFAL_NFCDEP_DID_KEEP \
    0xFFU /*!< Keep DID value already configured                              */
#define RFAL_NFCDEP_DID_NO \
    0x00U /*!< No DID shall be used                                           */
#define RFAL_NFCDEP_NAD_NO \
    0x00U /*!< No NAD shall be used                                           */

#define RFAL_NFCDEP_OPER_RTOX_REQ_DIS \
    0x01U /*!< Operation config: RTOX REQ disable                             */
#define RFAL_NFCDEP_OPER_RTOX_REQ_EN \
    0x00U /*!< Operation config: RTOX REQ enable                              */

#define RFAL_NFCDEP_OPER_ATN_DIS \
    0x00U /*!< Operation config: ATN disable                                  */
#define RFAL_NFCDEP_OPER_ATN_EN \
    0x02U /*!< Operation config: ATN enable                                   */

#define RFAL_NFCDEP_OPER_EMPTY_DEP_DIS \
    0x04U /*!< Operation config: empty DEPs disable                           */
#define RFAL_NFCDEP_OPER_EMPTY_DEP_EN \
    0x00U /*!< Operation config: empty DEPs enable                            */

#define RFAL_NFCDEP_OPER_FULL_MI_DIS \
    0x00U /*!< Operation config: full chaining DEPs disable                   */
#define RFAL_NFCDEP_OPER_FULL_MI_EN \
    0x08U /*!< Operation config: full chaining DEPs enable                    */

#define RFAL_NFCDEP_BRS_MAINTAIN \
    0xC0U /*!< Value signalling that BR is to be maintained (no PSL)          */
#define RFAL_NFCDEP_BRS_Dx_MASK \
    0x07U /*!< Value signalling that BR is to be maintained (no PSL)          */
#define RFAL_NFCDEP_BRS_DSI_POS \
    3U /*!< Value signalling that BR is to be maintained (no PSL)          */

#define RFAL_NFCDEP_WT_DELTA \
    (16U - RFAL_NFCDEP_WT_DELTA_ADJUST) /*!< NFC-DEP dWRT (adjusted)  Digital 2.0 B.10  */
#define RFAL_NFCDEP_WT_DELTA_ADJUST \
    4U /*!< dWRT value adjustment                                          */

#define RFAL_NFCDEP_ATR_REQ_NFCID3_POS \
    2U /*!< NFCID3 offset in ATR_REQ frame                                 */
#define RFAL_NFCDEP_NFCID3_LEN \
    10U /*!< NFCID3 Length                                                  */

#define RFAL_NFCDEP_LEN_MIN \
    3U /*!< Minimum length byte LEN value                                  */
#define RFAL_NFCDEP_LEN_MAX \
    255U /*!< Maximum length byte LEN value                                  */

#define RFAL_NFCDEP_ATRRES_HEADER_LEN \
    2U /*!< ATR RES Header Len:  CmdType: 0xD5 + Cod: 0x01                 */
#define RFAL_NFCDEP_ATRRES_MIN_LEN \
    17U /*!< Minimum length for an ATR RES                                  */
#define RFAL_NFCDEP_ATRRES_MAX_LEN \
    64U /*!< Maximum length for an ATR RES  Digital 1.0 14.6.1              */
#define RFAL_NFCDEP_ATRREQ_MIN_LEN \
    16U /*!< Minimum length for an ATR REQ                                  */
#define RFAL_NFCDEP_ATRREQ_MAX_LEN \
    RFAL_NFCDEP_ATRRES_MAX_LEN /*!< Maximum length for an ATR REQ  Digital 1.0 14.6.1   */

#define RFAL_NFCDEP_GB_MAX_LEN    \
    (RFAL_NFCDEP_ATRREQ_MAX_LEN - \
     RFAL_NFCDEP_ATRREQ_MIN_LEN) /*!< Maximum length the General Bytes on ATR  Digital 1.1  16.6.3 */

#define RFAL_NFCDEP_WT_INI_DEFAULT \
    RFAL_NFCDEP_WT_INI_MAX /*!< WT Initiator default value Digital 1.0 14.6.3.8        */
#define RFAL_NFCDEP_WT_INI_MIN 0U /*!< WT Initiator minimum value Digital 1.0 14.6.3.8        */
#define RFAL_NFCDEP_WT_INI_MAX 14U /*!< WT Initiator maximum value Digital 1.0 14.6.3.8 A.10   */
#define RFAL_NFCDEP_RWT_INI_MAX \
    rfalNfcDepWT2RWT(RFAL_NFCDEP_WT_INI_MAX) /*!< RWT Initiator maximum value   */

#define RFAL_NFCDEP_WT_TRG_MAX_D10 8U /*!< WT target max Digital 1.0 14.6.3.8 A.10 */
#define RFAL_NFCDEP_WT_TRG_MAX_D11 14U /*!< WT target max Digital 1.1 16.6.3.9 A.9  */
#define RFAL_NFCDEP_WT_TRG_MAX_L13 10U /*!< WT target max [LLCP] 1.3 6.2.1          */
#define RFAL_NFCDEP_WT_TRG_MAX \
    RFAL_NFCDEP_WT_TRG_MAX_D11 /*!< WT target max Digital x.x | LLCP x.x    */
#define RFAL_NFCDEP_RWT_TRG_MAX \
    rfalNfcDepWT2RWT(RFAL_NFCDEP_WT_TRG_MAX) /*!< RWT Initiator maximum value         */

/*! Maximum Frame Waiting Time = ((256 * 16/fc)*2^FWImax) = ((256*16/fc)*2^14) = (1048576 / 64)/fc = (100000h*64)/fc         */
#define RFAL_NFCDEP_MAX_FWT ((uint32_t)1U << 20)

#define RFAL_NFCDEP_WT_MASK \
    0x0FU /*!< Bit mask for the Wait Time value                               */

#define RFAL_NFCDEP_BR_MASK_106 \
    0x01U /*!< Enable mask bit rate 106                                    */
#define RFAL_NFCDEP_BR_MASK_212 \
    0x02U /*!< Enable mask bit rate 242                                    */
#define RFAL_NFCDEP_BR_MASK_424 \
    0x04U /*!< Enable mask bit rate 424                                    */

/*
 ******************************************************************************
 * GLOBAL MACROS
 ******************************************************************************
 */

#define rfalNfcDepWT2RWT(wt)                    \
    ((uint32_t)1U                               \
     << (((uint32_t)(wt)&RFAL_NFCDEP_WT_MASK) + \
         12U)) /*!< Converts WT value to RWT (1/fc)               */

/*! Returns the BRS value from the given bit rate */
#define rfalNfcDepDx2BRS(br)                                                \
    ((((uint8_t)(br)&RFAL_NFCDEP_BRS_Dx_MASK) << RFAL_NFCDEP_BRS_DSI_POS) | \
     ((uint8_t)(br)&RFAL_NFCDEP_BRS_Dx_MASK))

#define rfalNfcDepBRS2DRI(brs) \
    (uint8_t)((                \
        uint8_t)(brs)&RFAL_NFCDEP_BRS_Dx_MASK) /*!< Returns the DRI value from the given BRS byte */
#define rfalNfcDepBRS2DSI(brs)                        \
    (uint8_t)(                                        \
        ((uint8_t)(brs) >> RFAL_NFCDEP_BRS_DSI_POS) & \
        RFAL_NFCDEP_BRS_Dx_MASK) /*!< Returns the DSI value from the given BRS byte */

#define rfalNfcDepPP2LR(PPx)                    \
    (((uint8_t)(PPx)&RFAL_NFCDEP_PP_LR_MASK) >> \
     RFAL_NFCDEP_PP_LR_SHIFT) /*!< Returns the LR value from the given PPx byte  */
#define rfalNfcDepLR2PP(LRx)                       \
    (((uint8_t)(LRx) << RFAL_NFCDEP_PP_LR_SHIFT) & \
     RFAL_NFCDEP_PP_LR_MASK) /*!< Returns the PP byte with the given LRx value  */

/*! Returns the Frame size value from the given LRx value  */
#define rfalNfcDepLR2FS(LRx) \
    (uint16_t)(              \
        MIN((RFAL_NFCDEP_FS_VAL_MIN * ((uint16_t)(LRx) + 1U)), RFAL_NFCDEP_FRAME_SIZE_MAX_LEN))

/*! 
 *  Despite DIGITAL 1.0 14.6.2.1 stating that the last two bytes may filled with 
 *  any value, some devices (Samsung Google Nexus) only accept when these are 0 */
#define rfalNfcDepSetNFCID(dst, src, len)           \
    ST_MEMSET((dst), 0x00, RFAL_NFCDEP_NFCID3_LEN); \
    if((len) > 0U) {                                \
        ST_MEMCPY((dst), (src), (len));             \
    }

/*
 ******************************************************************************
 * GLOBAL ENUMERATIONS
 ******************************************************************************
 */

/*! Enumeration of NFC-DEP bit rate in ATR    Digital 1.0 Table 93 and 94   */
enum {
    RFAL_NFCDEP_Bx_NO_HIGH_BR = 0x00, /*!< Peer supports no high bit rates      */
    RFAL_NFCDEP_Bx_08_848 = 0x01, /*!< Peer also supports 848               */
    RFAL_NFCDEP_Bx_16_1695 = 0x02, /*!< Peer also supports 1695              */
    RFAL_NFCDEP_Bx_32_3390 = 0x04, /*!< Peer also supports 3390              */
    RFAL_NFCDEP_Bx_64_6780 = 0x08 /*!< Peer also supports 6780              */
};

/*! Enumeration of NFC-DEP bit rate Dividor in PSL   Digital 1.0 Table 100  */
enum {
    RFAL_NFCDEP_Dx_01_106 = RFAL_BR_106, /*!< Divisor D =  1 : bit rate = 106      */
    RFAL_NFCDEP_Dx_02_212 = RFAL_BR_212, /*!< Divisor D =  2 : bit rate = 212      */
    RFAL_NFCDEP_Dx_04_424 = RFAL_BR_424, /*!< Divisor D =  4 : bit rate = 424      */
    RFAL_NFCDEP_Dx_08_848 = RFAL_BR_848, /*!< Divisor D =  8 : bit rate = 848      */
    RFAL_NFCDEP_Dx_16_1695 = RFAL_BR_1695, /*!< Divisor D = 16 : bit rate = 1695     */
    RFAL_NFCDEP_Dx_32_3390 = RFAL_BR_3390, /*!< Divisor D = 32 : bit rate = 3390     */
    RFAL_NFCDEP_Dx_64_6780 = RFAL_BR_6780 /*!< Divisor D = 64 : bit rate = 6780     */
};

/*! Enumeration of  NFC-DEP Length Reduction (LR)   Digital 1.0 Table 91    */
enum {
    RFAL_NFCDEP_LR_64 = 0x00, /*!< Maximum payload size is  64 bytes    */
    RFAL_NFCDEP_LR_128 = 0x01, /*!< Maximum payload size is 128 bytes    */
    RFAL_NFCDEP_LR_192 = 0x02, /*!< Maximum payload size is 192 bytes    */
    RFAL_NFCDEP_LR_254 = 0x03 /*!< Maximum payload size is 254 bytes    */
};

/*
 ******************************************************************************
 * GLOBAL DATA TYPES
 ******************************************************************************
 */

/*! NFC-DEP callback to check if upper layer has deactivation pending   */
typedef bool (*rfalNfcDepDeactCallback)(void);

/*! Enumeration of the nfcip communication modes */
typedef enum {
    RFAL_NFCDEP_COMM_PASSIVE, /*!< Passive communication mode    */
    RFAL_NFCDEP_COMM_ACTIVE /*!< Active communication mode     */
} rfalNfcDepCommMode;

/*! Enumeration of the nfcip roles */
typedef enum {
    RFAL_NFCDEP_ROLE_INITIATOR, /*!< Perform as Initiator          */
    RFAL_NFCDEP_ROLE_TARGET /*!< Perform as Target             */
} rfalNfcDepRole;

/*! Struct that holds all NFCIP configs                                                      */
typedef struct {
    rfalNfcDepRole role; /*!< Current NFCIP role                                      */
    rfalNfcDepCommMode commMode; /*!< Current NFCIP communication mode                        */
    uint8_t oper; /*!< Operation config similar to NCI 1.0 Table 81            */

    uint8_t did; /*!< Current Device ID (DID)                                 */
    uint8_t nad; /*!< Current Node Addressing (NAD)                           */
    uint8_t bs; /*!< Bit rate in Sending Direction                           */
    uint8_t br; /*!< Bit rate in Receiving Direction                         */
    uint8_t nfcid[RFAL_NFCDEP_NFCID3_LEN]; /*!< Pointer to the NFCID to be used    */
    uint8_t nfcidLen; /*!< Length of the given NFCID in nfcid                      */
    uint8_t gb[RFAL_NFCDEP_GB_MAX_LEN]; /*!< Pointer General Bytes (GB) to be used */
    uint8_t gbLen; /*!< Length of the given GB in gb                            */
    uint8_t lr; /*!< Length Reduction (LR) to be used                        */
    uint8_t to; /*!< Timeout (TO)  to be used                                */
    uint32_t fwt; /*!< Frame Waiting Time (FWT) to be used                     */
    uint32_t dFwt; /*!< Delta Frame Waiting Time (dFWT) to be used              */
} rfalNfcDepConfigs;

/*! ATR_REQ command    Digital 1.1 16.6.2   */
typedef struct {
    uint8_t CMD1; /*!< Command format 0xD4                    */
    uint8_t CMD2; /*!< Command Value                          */
    uint8_t NFCID3[RFAL_NFCDEP_NFCID3_LEN]; /*!< NFCID3 value                           */
    uint8_t DID; /*!< DID                                    */
    uint8_t BSi; /*!< Sending Bitrate for Initiator          */
    uint8_t BRi; /*!< Receiving Bitrate for Initiator        */
    uint8_t PPi; /*!< Optional Parameters presence indicator */
    uint8_t GBi[RFAL_NFCDEP_GB_MAX_LEN]; /*!< General Bytes                          */
} rfalNfcDepAtrReq;

/*! ATR_RES response    Digital 1.1 16.6.3  */
typedef struct {
    uint8_t CMD1; /*!< Response Byte 0xD5                     */
    uint8_t CMD2; /*!< Command Value                          */
    uint8_t NFCID3[RFAL_NFCDEP_NFCID3_LEN]; /*!< NFCID3 value                           */
    uint8_t DID; /*!< DID                                    */
    uint8_t BSt; /*!< Sending Bitrate for Initiator          */
    uint8_t BRt; /*!< Receiving Bitrate for Initiator        */
    uint8_t TO; /*!< Timeout                                */
    uint8_t PPt; /*!< Optional Parameters presence indicator */
    uint8_t GBt[RFAL_NFCDEP_GB_MAX_LEN]; /*!< General Bytes                          */
} rfalNfcDepAtrRes;

/*! Structure of transmit I-PDU Buffer format from caller                                    */
typedef struct {
    uint8_t prologue[RFAL_NFCDEP_DEPREQ_HEADER_LEN]; /*!< Prologue space for NFC-DEP header*/
    uint8_t inf[RFAL_FEATURE_NFC_DEP_BLOCK_MAX_LEN]; /*!< INF | Data area of the buffer    */
} rfalNfcDepBufFormat;

/*! Structure of APDU Buffer format from caller */
typedef struct {
    uint8_t prologue[RFAL_NFCDEP_DEPREQ_HEADER_LEN]; /*!< Prologue/SoD buffer                     */
    uint8_t pdu[RFAL_FEATURE_NFC_DEP_PDU_MAX_LEN]; /*!< Complete PDU/Payload buffer             */
} rfalNfcDepPduBufFormat;

/*! Activation info as Initiator and Target                                       */
typedef union { /*  PRQA S 0750 # MISRA 19.2 - Both members of the union will not be used concurrently , device is only initiatior or target a time. No problem can occur. */
    struct {
        rfalNfcDepAtrRes ATR_RES; /*!< ATR RES            (Initiator mode)  */
        uint8_t ATR_RESLen; /*!< ATR RES length     (Initiator mode)  */
    } Target; /*!< Target                               */
    struct {
        rfalNfcDepAtrReq ATR_REQ; /*!< ATR REQ            (Target mode)     */
        uint8_t ATR_REQLen; /*!< ATR REQ length     (Target mode)     */
    } Initiator; /*!< Initiator                            */
} rfalNfcDepActivation;

/*! NFC-DEP device Info */
typedef struct {
    uint8_t GBLen; /*!< General Bytes length                       */
    uint8_t WT; /*!< WT to be used (ignored in Listen Mode)     */
    uint32_t FWT; /*!< FWT to be used (1/fc)(ignored Listen Mode) */
    uint32_t dFWT; /*!< Delta FWT to be used (1/fc)                */
    uint8_t LR; /*!< Length Reduction coding the max payload    */
    uint16_t FS; /*!< Frame Size                                 */
    rfalBitRate DSI; /*!< Bit Rate coding from Initiator  to Target  */
    rfalBitRate DRI; /*!< Bit Rate coding from Target to Initiator   */
    uint8_t DID; /*!< Device ID (RFAL_NFCDEP_DID_NO if no DID)   */
    uint8_t NAD; /*!< Node ADdress (RFAL_NFCDEP_NAD_NO if no NAD)*/
} rfalNfcDepInfo;

/*! NFC-DEP Device structure */
typedef struct {
    rfalNfcDepActivation activation; /*!< Activation Info               */
    rfalNfcDepInfo info; /*!< NFC-DEP device Info           */
} rfalNfcDepDevice;

/*! NFCIP Protocol structure for P2P Target
 *
 *   operParam : derives from NFC-Forum NCI NFC-DEP Operation Parameter
 *               NCI 1.1 Table 86: NFC-DEP Operation Parameter
 *               and it's a bit mask composed as:
 *                  [ 0000b 
 *                    | Chain SHALL use max. Transport Data Byte[1b] 
 *                    | I-PDU with no Transport Data SHALL NOT be sent [1b]
 *                    | NFC-DEP Target SHALL NOT send RTOX request [1b]
 *                  ]
 * 
 */
typedef struct {
    rfalNfcDepCommMode commMode; /*!< Initiator in Active P2P or Passive P2P*/
    uint8_t operParam; /*!< NFC-DEP Operation Parameter           */
    uint8_t* nfcid; /*!< Initiator's NFCID2 or NFCID3          */
    uint8_t nfcidLen; /*!< Initiator's NFCID length (NFCID2/3)   */
    uint8_t DID; /*!< Initiator's Device ID DID             */
    uint8_t NAD; /*!< Initiator's Node ID NAD               */
    uint8_t BS; /*!< Initiator's Bit Rates supported in Tx */
    uint8_t BR; /*!< Initiator's Bit Rates supported in Rx */
    uint8_t LR; /*!< Initiator's Length reduction          */
    uint8_t* GB; /*!< Initiator's General Bytes (Gi)        */
    uint8_t GBLen; /*!< Initiator's General Bytes length      */
} rfalNfcDepAtrParam;

/*! Structure of parameters to be passed in for nfcDepListenStartActivation       */
typedef struct {
    rfalNfcDepBufFormat* rxBuf; /*!< Receive Buffer struct reference      */
    uint16_t* rxLen; /*!< Receive INF data length in bytes     */
    bool* isRxChaining; /*!< Received data is not complete        */
    rfalNfcDepDevice* nfcDepDev; /*!< NFC-DEP device info                  */
} rfalNfcDepListenActvParam;

/*! NFCIP Protocol structure for P2P Target
 *
 *   operParam : derives from NFC-Forum NCI NFC-DEP Operation Parameter
 *               NCI 1.1 Table 86: NFC-DEP Operation Parameter
 *               and it's a bit mask composed as:
 *                  [ 0000b 
 *                    | Chain SHALL use max. Transport Data Byte[1b] 
 *                    | I-PDU with no Transport Data SHALL NOT be sent [1b]
 *                    | NFC-DEP Target SHALL NOT send RTOX request [1b]
 *                  ]
 * 
 */
typedef struct {
    rfalNfcDepCommMode commMode; /*!< Target in Active P2P or Passive P2P   */
    uint8_t nfcid3[RFAL_NFCDEP_NFCID3_LEN]; /*!< Target's NFCID3                       */
    uint8_t bst; /*!< Target's Bit Rates supported in Tx    */
    uint8_t brt; /*!< Target's Bit Rates supported in Rx    */
    uint8_t to; /*!< Target's timeout (TO) value           */
    uint8_t ppt; /*!< Target's Presence optional Params(PPt)*/
    uint8_t GBt[RFAL_NFCDEP_GB_MAX_LEN]; /*!< Target's General Bytes (Gt)           */
    uint8_t GBtLen; /*!< Target's General Bytes length         */
    uint8_t operParam; /*!< NFC-DEP Operation Parameter           */
} rfalNfcDepTargetParam;

/*! Structure of parameters to be passed in for nfcDepStartIpduTransceive              */
typedef struct {
    rfalNfcDepBufFormat* txBuf; /*!< Transmit Buffer struct reference          */
    uint16_t txBufLen; /*!< Transmit Buffer INF field length in bytes */
    bool isTxChaining; /*!< Transmit data is not complete             */
    rfalNfcDepBufFormat* rxBuf; /*!< Receive Buffer struct reference           */
    uint16_t* rxLen; /*!< Receive INF data length                   */
    bool* isRxChaining; /*!< Received data is not complete             */
    uint32_t FWT; /*!< FWT to be used (ignored in Listen Mode)   */
    uint32_t dFWT; /*!< Delta FWT to be used                      */
    uint16_t FSx; /*!< Other device Frame Size (FSD or FSC)      */
    uint8_t DID; /*!< Device ID (RFAL_ISODEP_NO_DID if no DID)  */
} rfalNfcDepTxRxParam;

/*! Structure of parameters used on NFC DEP PDU Transceive */
typedef struct {
    rfalNfcDepPduBufFormat* txBuf; /*!< Transmit Buffer struct reference         */
    uint16_t txBufLen; /*!< Transmit Buffer INF field length in Bytes*/
    rfalNfcDepPduBufFormat* rxBuf; /*!< Receive Buffer struct reference in Bytes */
    uint16_t* rxLen; /*!< Received INF data length in Bytes        */
    rfalNfcDepBufFormat* tmpBuf; /*!< Temp buffer for single PDUs (internal)   */
    uint32_t FWT; /*!< FWT to be used (ignored in Listen Mode)  */
    uint32_t dFWT; /*!< Delta FWT to be used                     */
    uint16_t FSx; /*!< Other device Frame Size (FSD or FSC)     */
    uint8_t DID; /*!< Device ID (RFAL_ISODEP_NO_DID if no DID) */
} rfalNfcDepPduTxRxParam;

/*
 * *****************************************************************************
 * GLOBAL VARIABLE DECLARATIONS
 ******************************************************************************
 */

/*
 ******************************************************************************
 * GLOBAL FUNCTION PROTOTYPES
 ******************************************************************************
 */

/*!
 ******************************************************************************
 * \brief NFCIP Initialize
 * 
 * This method resets all NFC-DEP inner states, counters and context and sets
 * default values
 * 
 ******************************************************************************
 */
void rfalNfcDepInitialize(void);

/*!
 ******************************************************************************
 * \brief Set deactivating callback
 * 
 * Sets the deactivating callback so that nfcip layer can check if upper layer
 * has a deactivation pending, and not perform error recovery upon specific
 * errors
 * 
 * \param[in] pFunc : method pointer to deactivation flag check 
 ******************************************************************************
 */
void rfalNfcDepSetDeactivatingCallback(rfalNfcDepDeactCallback pFunc);

/*!
 ******************************************************************************
 * \brief Calculate Response Waiting Time
 * 
 * Calculates the Response Waiting Time (RWT) from the given Waiting Time (WT)
 * 
 * \param[in]  wt : the WT value to calculate RWT
 * 
 * \return RWT value in 1/fc
 ******************************************************************************
 */
uint32_t rfalNfcDepCalculateRWT(uint8_t wt);

/*!
 ******************************************************************************
 * \brief NFC-DEP Initiator ATR (Attribute Request)
 * 
 * This method configures the NFC-DEP layer with given parameters and then
 * sends an ATR to the Target with and checks for a valid response response
 *
 * \param[in]   param     : parameters to initialize and compose the ATR
 * \param[out]  atrRes    : location to store the ATR_RES
 * \param[out]  atrResLen : length of the ATR_RES received
 * 
 * \return ERR_NONE    : No error
 * \return ERR_TIMEOUT : Timeout occurred
 * \return ERR_PROTO   : Protocol error occurred
 ******************************************************************************
 */
ReturnCode
    rfalNfcDepATR(const rfalNfcDepAtrParam* param, rfalNfcDepAtrRes* atrRes, uint8_t* atrResLen);

/*!
 ******************************************************************************
 * \brief NFC-DEP Initiator PSL (Parameter Selection)
 * 
 * This method sends a PSL to the Target with the given parameters and checks
 * for a valid response response
 * 
 * The parameters must be coded according to  Digital 1.1  16.7.1
 * 
 * \param[in] BRS : the selected Bit Rates for Initiator and Target
 * \param[in] FSL : the maximum length of Commands and Responses
 * 
 * \return ERR_NONE    : No error
 * \return ERR_TIMEOUT : Timeout occurred
 * \return ERR_PROTO   : Protocol error occurred
 ******************************************************************************
 */
ReturnCode rfalNfcDepPSL(uint8_t BRS, uint8_t FSL);

/*!
 ******************************************************************************
 * \brief NFC-DEP Initiator DSL (Deselect)
 * 
 * This method checks if the NFCIP module is configured as initiator and if 
 * so sends a DSL REQ, waits  the target's response and checks it 
 * 
 * In case of performing as target no action is taken 
 * 
 * \return ERR_NONE       : No error
 * \return ERR_TIMEOUT    : Timeout occurred
 * \return ERR_MAX_RERUNS : Timeout occurred
 * \return ERR_PROTO      : Protocol error occurred
 ******************************************************************************
 */
ReturnCode rfalNfcDepDSL(void);

/*!
 ******************************************************************************
 * \brief NFC-DEP Initiator RLS (Release)
 * 
 * This method checks if the NFCIP module is configured as initiator and if 
 * so sends a RLS REQ, waits target's response and checks it 
 * 
 * In case of performing as target no action is taken 
 * 
 * \return ERR_NONE       : No error
 * \return ERR_TIMEOUT    : Timeout occurred
 * \return ERR_MAX_RERUNS : Timeout occurred
 * \return ERR_PROTO      : Protocol error occurred
 ******************************************************************************
 */
ReturnCode rfalNfcDepRLS(void);

/*! 
 *****************************************************************************
 *  \brief  NFC-DEP Initiator Handle  Activation
 *   
 *  This performs a Activation into NFC-DEP layer with the given
 *  parameters. It sends ATR_REQ and if the higher bit rates are supported by 
 *  both devices it additionally sends PSL
 *  Once Activated all details of the device are provided on nfcDepDev
 *   
 *  \param[in]  param     : required parameters to initialize and send ATR_REQ
 *  \param[in]  desiredBR : Desired bit rate supported by the Poller
 *  \param[out] nfcDepDev : NFC-DEP information of the activated Listen device
 *
 *  \return ERR_WRONG_STATE  : RFAL not initialized or incorrect mode
 *  \return ERR_PARAM        : Invalid parameters
 *  \return ERR_IO           : Generic internal error
 *  \return ERR_TIMEOUT      : Timeout error
 *  \return ERR_PAR          : Parity error detected
 *  \return ERR_CRC          : CRC error detected
 *  \return ERR_FRAMING      : Framing error detected
 *  \return ERR_PROTO        : Protocol error detected
 *  \return ERR_NONE         : No error, activation successful
 *****************************************************************************
 */
ReturnCode rfalNfcDepInitiatorHandleActivation(
    rfalNfcDepAtrParam* param,
    rfalBitRate desiredBR,
    rfalNfcDepDevice* nfcDepDev);

/*!
 ******************************************************************************
 * \brief Check if buffer contains valid ATR_REQ 
 * 
 * This method checks if the given ATR_REQ is valid
 * 
 * 
 * \param[in]  buf    : buffer holding Initiator's received request
 * \param[in]  bufLen : size of the msg contained on the buf in Bytes
 * \param[out] nfcid3 : pointer to where the NFCID3 may be outputed, 
 *                       nfcid3 has NFCF_SENSF_NFCID3_LEN as length
 *                       Pass NULL if output parameter not desired 
 *                       
 * \return true  : Valid ATR_REQ received, the ATR_RES has been computed in txBuf
 * \return false : Invalid protocol request
 * 
 ******************************************************************************
 */
bool rfalNfcDepIsAtrReq(const uint8_t* buf, uint16_t bufLen, uint8_t* nfcid3);

/*!
 ******************************************************************************
 * \brief Check is Target has received ATR 
 * 
 * This method checks if the NFCIP module is configured as target and if a
 * ATR REQ has been received ( whether is in activation or in data exchange)
 * 
 * \return true  : a ATR has already been received
 * \return false : no ATR has been received 
 ******************************************************************************
 */
bool rfalNfcDepTargetRcvdATR(void);

/*!
 *****************************************************************************
 * \brief NFCDEP Start Listen Activation Handling
 * 
 * Start Activation Handling and setup to receive first frame which may
 * contain complete or partial DEP-REQ after activation is completed 
 * 
 * Pass in ATR_REQ for NFC-DEP to handle ATR_RES. The Activation Handling 
 * handles ATR_RES and PSL_RES if a PSL_REQ is received
 * 
 * Activation is completed if PSL_RES is sent or if first I-PDU is received
 *  
 * \ref rfalNfcDepListenGetActivationStatus() provide status of the 
 *       ongoing activation
 * 
 * \warning nfcDepGetTransceiveStatus() shall be called right after activation 
 * is completed (i.e. rfalNfcDepListenGetActivationStatus() return ERR_NONE) 
 * to check for first received frame.
 * 
 * \param[in]  param       : Target parameters to be used
 * \param[in]  atrReq      : reference to buffer containing ATR_REQ 
 * \param[in]  atrReqLength: Length of ATR_REQ
 * \param[out] rxParam     : references to buffer, length and chaining indication 
 *                           for first complete LLCP to be received
 * 
 * \return ERR_NONE      : ATR_REQ is valid and activation ongoing
 * \return ERR_PARAM     : ATR_REQ or other params are invalid
 * \return ERR_LINK_LOSS : Remote Field is turned off
 *****************************************************************************
 */
ReturnCode rfalNfcDepListenStartActivation(
    const rfalNfcDepTargetParam* param,
    const uint8_t* atrReq,
    uint16_t atrReqLength,
    rfalNfcDepListenActvParam rxParam);

/*!
 *****************************************************************************
 * \brief Get the current NFC-DEP Activation Status
 * 
 * \return ERR_NONE      : Activation has completed successfully
 * \return ERR_BUSY      : Activation is ongoing
 * \return ERR_LINK_LOSS : Remote Field was turned off
 *****************************************************************************
 */
ReturnCode rfalNfcDepListenGetActivationStatus(void);

/*!
 *****************************************************************************
 * \brief Start Transceive 
 * 
 * Transceives a complete or partial DEP block
 * 
 * The txBuf contains complete or partial of DEP to be transmitted. 
 * The Prologue field of the I-PDU is handled internally
 * 
 * If the buffer contains partial LLCP and is not the last block, then 
 * isTxChaining must be set to true
 * 
 * \param[in] param: reference parameters to be used for the Transceive
 *                    
 * \return ERR_PARAM       : Bad request
 * \return ERR_WRONG_STATE : The module is not in a proper state
 * \return ERR_NONE        : The Transceive request has been started
 *****************************************************************************
 */
ReturnCode rfalNfcDepStartTransceive(const rfalNfcDepTxRxParam* param);

/*!
 *****************************************************************************
 * \brief Return the Transceive status
 *
 * Returns the status of the NFC-DEP Transceive
 * 
 * \warning  When the other device is performing chaining once a chained 
 *            block is received the error ERR_AGAIN is sent. At this point 
 *            caller must handle the received data immediately. 
 *            When ERR_AGAIN is returned an ACK has already been sent to 
 *            the other device and the next block might be incoming. 
 *            If rfalWorker() is called frequently it will place the next 
 *            block on the given buffer  
 * 
 * \return ERR_NONE      : Transceive has been completed successfully
 * \return ERR_BUSY      : Transceive is ongoing
 * \return ERR_PROTO     : Protocol error occurred
 * \return ERR_TIMEOUT   : Timeout error occurred
 * \return ERR_SLEEP_REQ : Deselect has been received and responded
 * \return ERR_NOMEM     : The received I-PDU does not fit into the
 *                            receive buffer
 * \return ERR_LINK_LOSS : Communication is lost because Reader/Writer 
 *                            has turned off its field
 * \return ERR_AGAIN     : received one chaining block, continue to call
 *                            this method to retrieve the remaining blocks
 *****************************************************************************
 */
ReturnCode rfalNfcDepGetTransceiveStatus(void);

/*!
 *****************************************************************************
 * \brief Start PDU Transceive 
 * 
 * This method triggers a NFC-DEP Transceive containing a complete PDU
 * It transmits the given message and handles all protocol retransmitions,
 * error handling and control messages
 * 
 * The txBuf  contains a complete PDU to be transmitted 
 * The Prologue field will be manipulated by the Transceive
 *  
 * \warning the txBuf will be modified during the transmission
 * \warning the maximum RF frame which can be received is limited by param.tmpBuf
 * 
 * \param[in] param: reference parameters to be used for the Transceive
 *                    
 * \return ERR_PARAM       : Bad request
 * \return ERR_WRONG_STATE : The module is not in a proper state
 * \return ERR_NONE        : The Transceive request has been started
 *****************************************************************************
 */
ReturnCode rfalNfcDepStartPduTransceive(rfalNfcDepPduTxRxParam param);

/*!
 *****************************************************************************
 * \brief Return the PSU Transceive status
 *
 * Returns the status of the NFC-DEP PDU Transceive
 * 
 * 
 * \return ERR_NONE      : Transceive has been completed successfully
 * \return ERR_BUSY      : Transceive is ongoing
 * \return ERR_PROTO     : Protocol error occurred
 * \return ERR_TIMEOUT   : Timeout error occurred
 * \return ERR_SLEEP_REQ : Deselect has been received and responded
 * \return ERR_NOMEM     : The received I-PDU does not fit into the
 *                            receive buffer
 * \return ERR_LINK_LOSS : Communication is lost because Reader/Writer 
 *                            has turned off its field
 *****************************************************************************
 */
ReturnCode rfalNfcDepGetPduTransceiveStatus(void);

#endif /* RFAL_NFCDEP_H_ */

/**
  * @}
  *
  * @}
  *
  * @}
  */