src/phFriNfc_OvrHal.h

   1 /*
   2  * Copyright (C) 2010 NXP Semiconductors
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /**
  18  * \file  phFriNfc_OvrHal.h
  19  * \brief Overlapped HAL
  20  *
  21  * Project: NFC-FRI
  22  * Creator: Gerald Kersch
  23  *
  24  * $Date: Tue May 19 10:30:18 2009 $
  25  * Changed by: $Author: ing07336 $
  26  * $Revision: 1.13 $
  27  * $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 $
  28  *
  29  */
  30
  31 #ifndef PHFRINFC_OVRHAL_H
  32 #define PHFRINFC_OVRHAL_H
  33
  34 #include <phFriNfc.h>
  35 #ifdef PH_HAL4_ENABLE
  36 #include <phHal4Nfc.h>
  37 #else
  38 #include <phHalNfc.h>
  39 #endif
  40 #include <phNfcCompId.h>
  41 #include <phNfcStatus.h>
  42
  43
  44 /**
  45  *  \name Overlapped HAL
  46  *
  47  * File: \ref phFriNfc_OvrHal.h
  48  *
  49  */
  50 /*@{*/
  51 #define PH_FRINFC_OVRHAL_FILEREVISION "$Revision: 1.13 $" /** \ingroup grp_file_attributes */
  52 #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 */
  53 /*@}*/
  54
  55
  56 /** \defgroup grp_fri_nfc_ovr_hal Overlapped HAL
  57  *
  58  *  This component encapsulates the HAL functions, suited for the NFC-FRI overlapped way of operation. The HAL itself
  59  *  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
  60  *  the HAL, from the overlapped I/O operation mode the FRI is using.
  61  *
  62  *  \par Device Based Functions
  63  *  NFC Device Based Functions are used to address the NFC device (local device) directly.
  64  *  These are all functions that use no Remote Device Information.
  65  *
  66  *  \par Connection Based Functions
  67  *  Connection Based Functions use the Remote Device Information to describe a connection
  68  *  to a certain Remote Device.
  69  *
  70  *  \par Component Instance Sharing
  71  *  FRI components accessing one NFC device share one instance of the Overlapped HAL. Therefore
  72  *  each calling FRI component must specify - together with the call - where to deliver the
  73  *  response of the overlapped operation.
  74  *
  75  *  \par Lowest Layer
  76  *  The Overlapped HAL represents the NFC Device, the lowest layer of the FRI components.
  77  *
  78  *  \par Completion Forced
  79  *  The \b HAL \b functions (and underlying functions) of this library must complete before a new call can
  80  *  be issued. No HAL operation must be pending.
  81  *
  82  */
  83 /*@{*/
  84
  85 /**
  86  *  \name OVR HAL Constants
  87  */
  88 /*@{*/
  89 #define PH_FRINFC_OVRHAL_MAX_NUM_MOCKUP_PARAM           255    /**< Number of mockup indices that are are prepared. */
  90 /* Harsha: changed from 48 to 128, to work with the Mifare 4k TCs */
  91 #define PH_FRINFC_OVRHAL_MAX_NUM_MOCKUP_RDI             4     /**< Max. number of mockup RDIs. */
  92 #define PH_FRINFC_OVRHAL_MAX_TEST_DELAY                 1000  /**< Max. test delay in OVR HAL. */
  93 #define PH_FRINFC_OVRHAL_POLL_PAYLOAD_LEN               5     /**< Length of the POLL payload. */ /* @GK/5.6.06 */
  94 /*@}*/
  95 /*@}*/ /* defgroup... */
  96
  97 /** \defgroup grp_ovr_hal_cmd Overlapped HAL Command List
  98  *  \ingroup grp_fri_nfc_ovr_hal
  99  *  These are the command definitions for the Overlapped HAL. They are used internally by the
 100  *  implementation of the component.
 101  */
 102 /*@{*/
 103 #define PH_FRINFC_OVRHAL_NUL             (0)     /**< \brief We're in NO command */
 104
 105 #define PH_FRINFC_OVRHAL_ENU             (1)     /**< \brief Enumerate */
 106 #define PH_FRINFC_OVRHAL_OPE             (2)     /**< \brief Open */
 107 #define PH_FRINFC_OVRHAL_CLO             (3)     /**< \brief Close */
 108 #define PH_FRINFC_OVRHAL_GDC             (4)     /**< \brief Get Dev Caps */
 109 #define PH_FRINFC_OVRHAL_POL             (5)     /**< \brief Poll */
 110 #define PH_FRINFC_OVRHAL_CON             (6)     /**< \brief Connect */
 111 #define PH_FRINFC_OVRHAL_DIS             (7)     /**< \brief Disconnect */
 112 #define PH_FRINFC_OVRHAL_TRX             (8)     /**< \brief Transceive */
 113 #define PH_FRINFC_OVRHAL_STM             (9)     /**< \brief Start Target Mode */
 114 #define PH_FRINFC_OVRHAL_SND             (10)     /**< \brief Send */
 115 #define PH_FRINFC_OVRHAL_RCV             (11)    /**< \brief Receive */
 116 #define PH_FRINFC_OVRHAL_IOC             (12)    /**< \brief IOCTL */
 117
 118 #define PH_FRINFC_OVRHAL_TST             (255)   /**< \brief OVR HAL test-related command */
 119
 120 /** \ingroup grp_fri_nfc_ovr_hal
 121  *  \brief Post Message Function for Overlapped HAL
 122  *
 123  *  \copydoc page_reg
 124  *
 125  * This is required by the Overlapped HAL in order to call the blocking (original HAL) in another
 126  * thread. This function is required in addition to \ref pphFriNfc_OvrHalPresetParm to be
 127  * implemented in the integrating software.
 128  *
 129  * \par First Parameter: Context of the Integration
 130  *      Set to the value, the Integration has provided when initialising this component.
 131  */
 132 typedef void (*pphFriNfc_OvrHalPostMsg_t)(void*);
 133
 134 /** \ingroup grp_fri_nfc_ovr_hal
 135  *  \brief Abort Function (to be defined/implemented by the Integration)
 136  *
 137  *  \copydoc page_reg
 138  *
 139  * This is required by the Overlapped HAL in order abort a pending Overlapped HAL operation. This funtion will be
 140  * internally called by the \ref phFriNfc_OvrHal_Abort function.
 141  *
 142  * \par First Parameter: Context of the Integration
 143  *      Set to the value, the Integration has provided when initialising this component.
 144  *
 145  * \par Return value:
 146  *      As defined by the integration
 147  */
 148 typedef NFCSTATUS (*pphFriNfc_OvrHalAbort_t)(void*);
 149
 150
 151 typedef void (*pphOvrHal_CB_t) (phHal_sRemoteDevInformation_t *RemoteDevHandle,
 152                                 NFCSTATUS status,
 153                                 phNfc_sData_t  *pRecvdata,
 154                                 void *context);
 155
 156 /** \ingroup grp_fri_nfc_ovr_hal
 157  *  \brief Preset Function to prepare the parameters in the HAL
 158  *
 159  *  \copydoc page_reg
 160  *
 161  * This function (pointer) is called by the Overlapped HAL to prepare the function call parameters
 162  * in the HAL before posting the start message. As we have an asynchronously running FRI, but a
 163  * synchronous HAL, the calls need to be "decoupled". This means, the HAL needs to run under
 164  * a different time-base (or thread/task etc.). The consequence is that the data exchange between
 165  * FRI and HAL must be done as required by the integration/system itself. The declaration
 166  * of the function pointer allows for the integrating software to implement whatever functionality
 167  * is required to convey the data.
 168  *
 169  *
 170  * \par First Parameter
 171  *      Context of the Integration Set to the value, the Integration has provided when initialising
 172  *      this component.
 173  *
 174  * \par Second Parameter:
 175  *      \b HAL \b Command, as defined in the module \ref grp_ovr_hal_cmd.
 176  *
 177  * \par Third Parameter:
 178  *      \b Pointers to a specific structure containing the parameters of the HAL functions to be
 179  *      called.
 180  *
 181  * \par Forth parameter:
 182  *      Immediate Operation result (not the result of the HAL operation). Usually this is
 183  *      \ref NFCSTATUS_PENDING (for a successfully triggered HAL I/O or an error value that is
 184  *      returned by the HAL immediately, such as \ref NFCSTATUS_INVALID_PARAMETER.
 185  *
 186  * \par Return value:
 187  *      A boolean (\ref grp_special_conventions) value. The integration implementation must ensure
 188  *      that, if the function \b succeeds, the return value is \b TRUE, otherwise false.
 189  */
 190 typedef uint8_t (*pphFriNfc_OvrHalPresetParm)(void*, uint16_t, void*, NFCSTATUS*);
 191
 192 /** \ingroup grp_fri_nfc_ovr_hal
 193  *  \brief Overlapped HAL Context
 194  *
 195  *  The Overlapped HAL structure. This structure contains the HAL "context" that
 196  *  is required by the FRI on a connection basis. Please note that the Overlapped HAL is
 197  *  a shared component, requiring a special completion notification mechanism.
 198  *  Read more in the description of this component.
 199  *
 200  */
 201 typedef struct phFriNfc_OvrHal
 202 {
 203     /** Currently active operation of the component. If no operation is pending, the content of this member is
 204      *  \ref PH_FRINFC_OVRHAL_NUL .  The component refuses a new call if the contenet is different, namely one
 205      *  of the other values defined in \ref grp_ovr_hal_cmd .
 206      */
 207     uint8_t                         Operation;
 208
 209     /** The \b temporary pointer to the completion routine information. The HAL needs - for each call - to be told about the
 210      *  completion routine of the upper (calling) component. This major difference to other components is because
 211      *  some functions of the HAL are connection-based and some are not. Moreover it is because the HAL is shared
 212      *  among the FRI components. So, with a variety of potential callers it is required for each caller to instruct
 213      *  the HAL about the "delivery" address of the response for each individual call.
 214      */
 215     phFriNfc_CplRt_t                TemporaryCompletionInfo;
 216     phFriNfc_CplRt_t                TemporaryRcvCompletionInfo;
 217     phFriNfc_CplRt_t                TemporarySndCompletionInfo;
 218
 219     /** Points to a function within the Integration that presets the parameters for the actual
 220      *  HAL call.
 221      */
 222     pphFriNfc_OvrHalPresetParm      Presetparameters;
 223
 224     /** Posts a message to the actual HAL integration, starting a  NFC HAL I/O with the pre-set
 225      *  parameters.
 226      */
 227     pphFriNfc_OvrHalPostMsg_t       PostMsg;
 228
 229     /** The context of the Integration (the SW around this component). This is needed to let
 230      *  the Overlapped HAL access the Integration's functionality to post a message to another
 231      *  thread.
 232      */
 233     void                           *IntegrationContext;
 234
 235     /** Device reference returned during enumeration: This has to be filled in by the integrating software after
 236         a call to the HAL Enumerate function (not contained in the overlapped HAl API). */
 237     phHal_sHwReference_t           *psHwReference;
 238
 239     /** This flag is set by the ABORT function. The OVR HAL then does no I/O to the real HAL
 240      *  or to the mockup any more but just completed with the ABORTED status.
 241      */
 242     uint8_t OperationAborted;
 243
 244     /** Abort function to be implemented by the integration. This parameter can be (optionally) initialized
 245      *  via the call of \ref phFriNfc_OvrHal_Reset_Abort function.
 246      *  If it is not NULL, the function pointed by \ref will be internally called by the \ref phFriNfc_OvrHal_Abort function.
 247      */
 248     pphFriNfc_OvrHalAbort_t      AbortIntegrationFunction;
 249
 250     /** Integration-defined Context passed as a parameter of the \ref AbortIntegrationFunction.
 251      */
 252     void*                        AbortIntegrationContext;
 253
 254     void*                        OvrCompletion;
 255
 256     phHal_sTransceiveInfo_t      TranceiveInfo;
 257
 258     /** TODO
 259      */
 260     phNfc_sData_t                sReceiveData;
 261
 262     /** TODO
 263      */
 264     phNfc_sData_t                sSendData;
 265
 266     /** TODO
 267      */
 268     phHal4Nfc_TransactInfo_t     TransactInfo;
 269
 270     uint16_t                     *pndef_recv_length;
 271 } phFriNfc_OvrHal_t;
 272
 273 /**
 274  * \ingroup grp_fri_nfc_ovr_hal
 275  *
 276  * \brief Transceive Data to/from a Remote Device
 277  *
 278  * \copydoc page_ovr
 279  *
 280  * \param[in]      OvrHal               Component Context.
 281  * \param[in]      CompletionInfo       \copydoc phFriNfc_OvrHal_t::TemporaryCompletionInfo
 282  * \param[in,out]  RemoteDevInfo        Remote Device Information.
 283  * \param[in]      Cmd                  Command to perform.
 284  * \param[out]     DepAdditionalInfo    Protocol Information.
 285  * \param[in]      SendBuf              Pointer to the data to send.
 286  * \param[in]      SendLength           Length, in bytes, of the Send Buffer.
 287  * \param[out]     RecvBuf              Pointer to the buffer that receives the data.
 288  * \param[in,out]  RecvLength           Length, in bytes, of the received data.
 289  *
 290  * \retval NFCSTATUS_PENDING                The operation is pending.
 291  * \retval NFCSTATUS_INVALID_DEVICE_REQUEST \copydoc phFriNfc_OvrHal_t::Operation
 292  * \retval NFCSTATUS_SUCCESS                Success.
 293  * \retval NFCSTATUS_INVALID_PARAMETER      One or more of the supplied parameters could not be
 294  *                                          properly interpreted.
 295  * \retval NFCSTATUS_INVALID_DEVICE         The device has not been opened or has been disconnected
 296  *                                          meanwhile.
 297  * \retval NFCSTATUS_CMD_ABORTED            The caller/driver has aborted the request.
 298  * \retval NFCSTATUS_BUFFER_TOO_SMALL       The buffer provided by the caller is too small.
 299  * \retval NFCSTATUS_RF_TIMEOUT             No data has been received within the TIMEOUT period.
 300  *
 301  * \note Please refer to HAL Transceive for a detailed description of the
 302  *       underlying function and the propagated parameters.
 303  *
 304  */
 305
 306 NFCSTATUS phFriNfc_OvrHal_Transceive(phFriNfc_OvrHal_t              *OvrHal,
 307                                      phFriNfc_CplRt_t               *CompletionInfo,
 308                                      phHal_sRemoteDevInformation_t  *RemoteDevInfo,
 309                                      phHal_uCmdList_t                Cmd,
 310                                      phHal_sDepAdditionalInfo_t     *DepAdditionalInfo,
 311                                      uint8_t                        *SendBuf,
 312                                      uint16_t                        SendLength,
 313                                      uint8_t                        *RecvBuf,
 314                                      uint16_t                       *RecvLength);
 315
 316 /**
 317  * \ingroup grp_fri_nfc_ovr_hal
 318  *
 319  * \brief TODO
 320  *
 321  */
 322 NFCSTATUS phFriNfc_OvrHal_Receive(phFriNfc_OvrHal_t              *OvrHal,
 323                                   phFriNfc_CplRt_t               *CompletionInfo,
 324                                   phHal_sRemoteDevInformation_t  *RemoteDevInfo,
 325                                   uint8_t                        *RecvBuf,
 326                                   uint16_t                       *RecvLength);
 327
 328 /**
 329  * \ingroup grp_fri_nfc_ovr_hal
 330  *
 331  * \brief TODO
 332  *
 333  */
 334 NFCSTATUS phFriNfc_OvrHal_Send(phFriNfc_OvrHal_t              *OvrHal,
 335                                phFriNfc_CplRt_t               *CompletionInfo,
 336                                phHal_sRemoteDevInformation_t  *RemoteDevInfo,
 337                                uint8_t                        *SendBuf,
 338                                uint16_t                       SendLength);
 339
 340
 341 NFCSTATUS phFriNfc_OvrHal_Reconnect(phFriNfc_OvrHal_t              *OvrHal,
 342                                     phFriNfc_CplRt_t               *CompletionInfo,
 343                                     phHal_sRemoteDevInformation_t  *RemoteDevInfo);
 344
 345
 346 NFCSTATUS phFriNfc_OvrHal_Connect(phFriNfc_OvrHal_t              *OvrHal,
 347                                   phFriNfc_CplRt_t               *CompletionInfo,
 348                                   phHal_sRemoteDevInformation_t  *RemoteDevInfo,
 349                                   phHal_sDevInputParam_t         *DevInputParam);
 350
 351 #endif