src/phFriNfc_OvrHal.h

/*
 * Copyright (C) 2010 NXP Semiconductors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * 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.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * \file  phFriNfc_OvrHal.h
 * \brief Overlapped HAL
 *
 * Project: NFC-FRI
 * Creator: Gerald Kersch
 *
 * $Date: Tue May 19 10:30:18 2009 $
 * Changed by: $Author: ing07336 $
 * $Revision: 1.13 $
 * $Aliases: NFC_FRI1.1_WK922_PREP1,NFC_FRI1.1_WK920_R25_1,NFC_FRI1.1_WK922_R26_1,NFC_FRI1.1_WK924_PREP1,NFC_FRI1.1_WK924_R27_1,NFC_FRI1.1_WK926_R28_1,NFC_FRI1.1_WK928_R29_1,NFC_FRI1.1_WK930_R30_1,NFC_FRI1.1_WK934_PREP_1,NFC_FRI1.1_WK934_R31_1,NFC_FRI1.1_WK941_PREP1,NFC_FRI1.1_WK941_PREP2,NFC_FRI1.1_WK941_1,NFC_FRI1.1_WK943_R32_1,NFC_FRI1.1_WK949_PREP1,NFC_FRI1.1_WK943_R32_10,NFC_FRI1.1_WK943_R32_13,NFC_FRI1.1_WK943_R32_14,NFC_FRI1.1_WK1007_R33_1,NFC_FRI1.1_WK1007_R33_4,NFC_FRI1.1_WK1017_PREP1,NFC_FRI1.1_WK1017_R34_1,NFC_FRI1.1_WK1017_R34_2,NFC_FRI1.1_WK1023_R35_1 $
 *
 */

#ifndef PHFRINFC_OVRHAL_H
#define PHFRINFC_OVRHAL_H

#include <phFriNfc.h>
#ifdef PH_HAL4_ENABLE
#include <phHal4Nfc.h>
#else
#include <phHalNfc.h>
#endif
#include <phNfcCompId.h>
#include <phNfcStatus.h>


/**
 *  \name Overlapped HAL
 *
 * File: \ref phFriNfc_OvrHal.h
 *
 */
/*@{*/
#define PH_FRINFC_OVRHAL_FILEREVISION "$Revision: 1.13 $" /** \ingroup grp_file_attributes */
#define PH_FRINFC_OVRHAL_FILEALIASES  "$Aliases: NFC_FRI1.1_WK922_PREP1,NFC_FRI1.1_WK920_R25_1,NFC_FRI1.1_WK922_R26_1,NFC_FRI1.1_WK924_PREP1,NFC_FRI1.1_WK924_R27_1,NFC_FRI1.1_WK926_R28_1,NFC_FRI1.1_WK928_R29_1,NFC_FRI1.1_WK930_R30_1,NFC_FRI1.1_WK934_PREP_1,NFC_FRI1.1_WK934_R31_1,NFC_FRI1.1_WK941_PREP1,NFC_FRI1.1_WK941_PREP2,NFC_FRI1.1_WK941_1,NFC_FRI1.1_WK943_R32_1,NFC_FRI1.1_WK949_PREP1,NFC_FRI1.1_WK943_R32_10,NFC_FRI1.1_WK943_R32_13,NFC_FRI1.1_WK943_R32_14,NFC_FRI1.1_WK1007_R33_1,NFC_FRI1.1_WK1007_R33_4,NFC_FRI1.1_WK1017_PREP1,NFC_FRI1.1_WK1017_R34_1,NFC_FRI1.1_WK1017_R34_2,NFC_FRI1.1_WK1023_R35_1 $"      /** \ingroup grp_file_attributes */
/*@}*/


/** \defgroup grp_fri_nfc_ovr_hal Overlapped HAL
 *
 *  This component encapsulates the HAL functions, suited for the NFC-FRI overlapped way of operation. The HAL itself
 *  is used as it is, wrapped by this component. The purpose of the wrapper is to de-couple a blocking I/O, as used by
 *  the HAL, from the overlapped I/O operation mode the FRI is using.
 *
 *  \par Device Based Functions
 *  NFC Device Based Functions are used to address the NFC device (local device) directly.
 *  These are all functions that use no Remote Device Information.
 *
 *  \par Connection Based Functions
 *  Connection Based Functions use the Remote Device Information to describe a connection
 *  to a certain Remote Device.
 *
 *  \par Component Instance Sharing
 *  FRI components accessing one NFC device share one instance of the Overlapped HAL. Therefore
 *  each calling FRI component must specify - together with the call - where to deliver the
 *  response of the overlapped operation.
 *
 *  \par Lowest Layer
 *  The Overlapped HAL represents the NFC Device, the lowest layer of the FRI components.
 *
 *  \par Completion Forced
 *  The \b HAL \b functions (and underlying functions) of this library must complete before a new call can
 *  be issued. No HAL operation must be pending.
 *
 */
/*@{*/

/**
 *  \name OVR HAL Constants
 */
/*@{*/
#define PH_FRINFC_OVRHAL_MAX_NUM_MOCKUP_PARAM           255    /**< Number of mockup indices that are are prepared. */
/* Harsha: changed from 48 to 128, to work with the Mifare 4k TCs */
#define PH_FRINFC_OVRHAL_MAX_NUM_MOCKUP_RDI             4     /**< Max. number of mockup RDIs. */
#define PH_FRINFC_OVRHAL_MAX_TEST_DELAY                 1000  /**< Max. test delay in OVR HAL. */
#define PH_FRINFC_OVRHAL_POLL_PAYLOAD_LEN               5     /**< Length of the POLL payload. */ /* @GK/5.6.06 */
/*@}*/
/*@}*/ /* defgroup... */

/** \defgroup grp_ovr_hal_cmd Overlapped HAL Command List
 *  \ingroup grp_fri_nfc_ovr_hal
 *  These are the command definitions for the Overlapped HAL. They are used internally by the
 *  implementation of the component.
 */
/*@{*/
#define PH_FRINFC_OVRHAL_NUL             (0)     /**< \brief We're in NO command */

#define PH_FRINFC_OVRHAL_ENU             (1)     /**< \brief Enumerate */
#define PH_FRINFC_OVRHAL_OPE             (2)     /**< \brief Open */
#define PH_FRINFC_OVRHAL_CLO             (3)     /**< \brief Close */
#define PH_FRINFC_OVRHAL_GDC             (4)     /**< \brief Get Dev Caps */
#define PH_FRINFC_OVRHAL_POL             (5)     /**< \brief Poll */
#define PH_FRINFC_OVRHAL_CON             (6)     /**< \brief Connect */
#define PH_FRINFC_OVRHAL_DIS             (7)     /**< \brief Disconnect */
#define PH_FRINFC_OVRHAL_TRX             (8)     /**< \brief Transceive */
#define PH_FRINFC_OVRHAL_STM             (9)     /**< \brief Start Target Mode */
#define PH_FRINFC_OVRHAL_SND             (10)     /**< \brief Send */
#define PH_FRINFC_OVRHAL_RCV             (11)    /**< \brief Receive */
#define PH_FRINFC_OVRHAL_IOC             (12)    /**< \brief IOCTL */

#define PH_FRINFC_OVRHAL_TST             (255)   /**< \brief OVR HAL test-related command */

/** \ingroup grp_fri_nfc_ovr_hal
 *  \brief Post Message Function for Overlapped HAL
 *
 *  \copydoc page_reg
 *
 * This is required by the Overlapped HAL in order to call the blocking (original HAL) in another
 * thread. This function is required in addition to \ref pphFriNfc_OvrHalPresetParm to be
 * implemented in the integrating software.
 *
 * \par First Parameter: Context of the Integration
 *      Set to the value, the Integration has provided when initialising this component.
 */
typedef void (*pphFriNfc_OvrHalPostMsg_t)(void*);

/** \ingroup grp_fri_nfc_ovr_hal
 *  \brief Abort Function (to be defined/implemented by the Integration)
 *
 *  \copydoc page_reg
 *
 * This is required by the Overlapped HAL in order abort a pending Overlapped HAL operation. This funtion will be
 * internally called by the \ref phFriNfc_OvrHal_Abort function.
 *
 * \par First Parameter: Context of the Integration
 *      Set to the value, the Integration has provided when initialising this component.
 *
 * \par Return value:
 *      As defined by the integration
 */
typedef NFCSTATUS (*pphFriNfc_OvrHalAbort_t)(void*);


typedef void (*pphOvrHal_CB_t) (phHal_sRemoteDevInformation_t *RemoteDevHandle,
                                NFCSTATUS status,
                                phNfc_sData_t  *pRecvdata,
                                void *context);

/** \ingroup grp_fri_nfc_ovr_hal
 *  \brief Preset Function to prepare the parameters in the HAL
 *
 *  \copydoc page_reg
 *
 * This function (pointer) is called by the Overlapped HAL to prepare the function call parameters
 * in the HAL before posting the start message. As we have an asynchronously running FRI, but a
 * synchronous HAL, the calls need to be "decoupled". This means, the HAL needs to run under
 * a different time-base (or thread/task etc.). The consequence is that the data exchange between
 * FRI and HAL must be done as required by the integration/system itself. The declaration
 * of the function pointer allows for the integrating software to implement whatever functionality
 * is required to convey the data.
 *
 *
 * \par First Parameter
 *      Context of the Integration Set to the value, the Integration has provided when initialising
 *      this component.
 *
 * \par Second Parameter:
 *      \b HAL \b Command, as defined in the module \ref grp_ovr_hal_cmd.
 *
 * \par Third Parameter:
 *      \b Pointers to a specific structure containing the parameters of the HAL functions to be
 *      called.
 *
 * \par Forth parameter:
 *      Immediate Operation result (not the result of the HAL operation). Usually this is
 *      \ref NFCSTATUS_PENDING (for a successfully triggered HAL I/O or an error value that is
 *      returned by the HAL immediately, such as \ref NFCSTATUS_INVALID_PARAMETER.
 *
 * \par Return value:
 *      A boolean (\ref grp_special_conventions) value. The integration implementation must ensure
 *      that, if the function \b succeeds, the return value is \b TRUE, otherwise false.
 */
typedef uint8_t (*pphFriNfc_OvrHalPresetParm)(void*, uint16_t, void*, NFCSTATUS*);

/** \ingroup grp_fri_nfc_ovr_hal
 *  \brief Overlapped HAL Context
 *
 *  The Overlapped HAL structure. This structure contains the HAL "context" that
 *  is required by the FRI on a connection basis. Please note that the Overlapped HAL is
 *  a shared component, requiring a special completion notification mechanism.
 *  Read more in the description of this component.
 *
 */
typedef struct phFriNfc_OvrHal
{
    /** Currently active operation of the component. If no operation is pending, the content of this member is
     *  \ref PH_FRINFC_OVRHAL_NUL .  The component refuses a new call if the contenet is different, namely one
     *  of the other values defined in \ref grp_ovr_hal_cmd .
     */
    uint8_t                         Operation;

    /** The \b temporary pointer to the completion routine information. The HAL needs - for each call - to be told about the
     *  completion routine of the upper (calling) component. This major difference to other components is because
     *  some functions of the HAL are connection-based and some are not. Moreover it is because the HAL is shared
     *  among the FRI components. So, with a variety of potential callers it is required for each caller to instruct
     *  the HAL about the "delivery" address of the response for each individual call.
     */
    phFriNfc_CplRt_t                TemporaryCompletionInfo;
    phFriNfc_CplRt_t                TemporaryRcvCompletionInfo;
    phFriNfc_CplRt_t                TemporarySndCompletionInfo;

    /** Points to a function within the Integration that presets the parameters for the actual
     *  HAL call.
     */
    pphFriNfc_OvrHalPresetParm      Presetparameters;

    /** Posts a message to the actual HAL integration, starting a  NFC HAL I/O with the pre-set
     *  parameters.
     */
    pphFriNfc_OvrHalPostMsg_t       PostMsg;

    /** The context of the Integration (the SW around this component). This is needed to let
     *  the Overlapped HAL access the Integration's functionality to post a message to another
     *  thread.
     */
    void                           *IntegrationContext;

    /** Device reference returned during enumeration: This has to be filled in by the integrating software after
        a call to the HAL Enumerate function (not contained in the overlapped HAl API). */
    phHal_sHwReference_t           *psHwReference;

    /** This flag is set by the ABORT function. The OVR HAL then does no I/O to the real HAL
     *  or to the mockup any more but just completed with the ABORTED status.
     */
    uint8_t OperationAborted;

    /** Abort function to be implemented by the integration. This parameter can be (optionally) initialized
     *  via the call of \ref phFriNfc_OvrHal_Reset_Abort function.
     *  If it is not NULL, the function pointed by \ref will be internally called by the \ref phFriNfc_OvrHal_Abort function.
     */
    pphFriNfc_OvrHalAbort_t      AbortIntegrationFunction;

    /** Integration-defined Context passed as a parameter of the \ref AbortIntegrationFunction.
     */
    void*                        AbortIntegrationContext;
    
    void*                        OvrCompletion;

    phHal_sTransceiveInfo_t      TranceiveInfo;
    
    /** TODO
     */
    phNfc_sData_t                sReceiveData;

    /** TODO
     */
    phNfc_sData_t                sSendData;

    /** TODO
     */
    phHal4Nfc_TransactInfo_t     TransactInfo;

    uint16_t                     *pndef_recv_length;
} phFriNfc_OvrHal_t;

/**
 * \ingroup grp_fri_nfc_ovr_hal
 *
 * \brief Transceive Data to/from a Remote Device
 *
 * \copydoc page_ovr
 *
 * \param[in]      OvrHal               Component Context.
 * \param[in]      CompletionInfo       \copydoc phFriNfc_OvrHal_t::TemporaryCompletionInfo
 * \param[in,out]  RemoteDevInfo        Remote Device Information.
 * \param[in]      Cmd                  Command to perform.
 * \param[out]     DepAdditionalInfo    Protocol Information.
 * \param[in]      SendBuf              Pointer to the data to send.
 * \param[in]      SendLength           Length, in bytes, of the Send Buffer.
 * \param[out]     RecvBuf              Pointer to the buffer that receives the data.
 * \param[in,out]  RecvLength           Length, in bytes, of the received data.
 *
 * \retval NFCSTATUS_PENDING                The operation is pending.
 * \retval NFCSTATUS_INVALID_DEVICE_REQUEST \copydoc phFriNfc_OvrHal_t::Operation
 * \retval NFCSTATUS_SUCCESS                Success.
 * \retval NFCSTATUS_INVALID_PARAMETER      One or more of the supplied parameters could not be
 *                                          properly interpreted.
 * \retval NFCSTATUS_INVALID_DEVICE         The device has not been opened or has been disconnected
 *                                          meanwhile.
 * \retval NFCSTATUS_CMD_ABORTED            The caller/driver has aborted the request.
 * \retval NFCSTATUS_BUFFER_TOO_SMALL       The buffer provided by the caller is too small.
 * \retval NFCSTATUS_RF_TIMEOUT             No data has been received within the TIMEOUT period.
 *
 * \note Please refer to HAL Transceive for a detailed description of the
 *       underlying function and the propagated parameters.
 *
 */

NFCSTATUS phFriNfc_OvrHal_Transceive(phFriNfc_OvrHal_t              *OvrHal,
                                     phFriNfc_CplRt_t               *CompletionInfo,
                                     phHal_sRemoteDevInformation_t  *RemoteDevInfo,
                                     phHal_uCmdList_t                Cmd,
                                     phHal_sDepAdditionalInfo_t     *DepAdditionalInfo,
                                     uint8_t                        *SendBuf,
                                     uint16_t                        SendLength,
                                     uint8_t                        *RecvBuf,
                                     uint16_t                       *RecvLength);

/**
 * \ingroup grp_fri_nfc_ovr_hal
 *
 * \brief TODO
 *
 */
NFCSTATUS phFriNfc_OvrHal_Receive(phFriNfc_OvrHal_t              *OvrHal,
                                  phFriNfc_CplRt_t               *CompletionInfo,
                                  phHal_sRemoteDevInformation_t  *RemoteDevInfo,
                                  uint8_t                        *RecvBuf,
                                  uint16_t                       *RecvLength);

/**
 * \ingroup grp_fri_nfc_ovr_hal
 *
 * \brief TODO
 *
 */
NFCSTATUS phFriNfc_OvrHal_Send(phFriNfc_OvrHal_t              *OvrHal,
                               phFriNfc_CplRt_t               *CompletionInfo,
                               phHal_sRemoteDevInformation_t  *RemoteDevInfo,
                               uint8_t                        *SendBuf,
                               uint16_t                       SendLength);


NFCSTATUS phFriNfc_OvrHal_Reconnect(phFriNfc_OvrHal_t              *OvrHal,
                                    phFriNfc_CplRt_t               *CompletionInfo,
                                    phHal_sRemoteDevInformation_t  *RemoteDevInfo);


NFCSTATUS phFriNfc_OvrHal_Connect(phFriNfc_OvrHal_t              *OvrHal,
                                  phFriNfc_CplRt_t               *CompletionInfo,
                                  phHal_sRemoteDevInformation_t  *RemoteDevInfo,
                                  phHal_sDevInputParam_t         *DevInputParam);

#endif