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 352