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 /** 19 * \file phHal4Nfc.h 20 * \brief HAL Function Prototypes 21 * The HAL4.0 API provides the user to have a interface for PN544(PN54x)/PN65N 22 * NFC device.The API is a non-blocking API, asynchronous API. This means that 23 * when ever an API function call results in waiting for a response from the 24 * NFC device, the API function will return immediately with status 'PENDING' 25 * and the actual result will be returned through specific callback functions 26 * on receiving the response from the NFC device 27 * 28 * \note This is the representative header file of the HAL 4.0. The release 29 * TAG or label is representing the release TAG (alias) of the entire 30 * library.A mechanism (see documentation \ref hal_release_label near 31 * the include guards of this file) is used to propagate the alias to 32 * the main documentation page. 33 * 34 * Project: NFC-FRI-1.1 / HAL4.0 35 * 36 * $Date: Mon Jun 14 11:36:12 2010 $ 37 * $Author: ing07385 $ 38 * $Revision: 1.171 $ 39 * $Aliases: NFC_FRI1.1_WK1023_R35_2,NFC_FRI1.1_WK1023_R35_1 $ 40 * 41 */ 42 43 /** page hal_release_label HAL 4.0 Release Label 44 * SDK_HAL_4.0 v 0.1 Draft 45 * \note This is the TAG (label, alias) of the HAL. If the string is empty,the 46 * current documentation has not been generated from an official release. 47 */ 48 /*@{*/ 49 #ifndef PHHAL4NFC_H 50 #define PHHAL4NFC_H 51 /*@}*/ 52 53 54 /** 55 * \name HAL4 56 * 57 * File: \ref phHal4Nfc.h 58 *\def hal 59 */ 60 61 /*@{*/ 62 #define PH_HAL4NFC_FILEREVISION "$Revision: 1.171 $" /**< \ingroup grp_file_attributes */ 63 #define PH_HAL4NFC_FILEALIASES "$Aliases: NFC_FRI1.1_WK1023_R35_2,NFC_FRI1.1_WK1023_R35_1 $" /**< \ingroup grp_file_attributes */ 64 /*@}*/ 65 66 /* -----------------Include files ---------------------------------------*/ 67 #include <phNfcStatus.h> 68 #include <phNfcCompId.h> 69 #include <phNfcHalTypes.h> 70 #include <phNfcInterface.h> 71 #include <phNfcIoctlCode.h> 72 #include <phNfcConfig.h> 73 #include <phDbgTrace.h> 74 #ifdef ANDROID 75 #include <string.h> 76 #endif 77 78 /*************************** Includes *******************************/ 79 /** \defgroup grp_mw_external_hal_funcs NFC HAL4.0 80 * 81 * 82 * 83 */ 84 /* ---------------- Macros ----------------------------------------------*/ 85 86 /** HAL Implementation Version Macros : Updated for every feature release of 87 HAL functionality */ 88 #define PH_HAL4NFC_VERSION 8 89 #define PH_HAL4NFC_REVISION 21 90 #define PH_HAL4NFC_PATCH 1 91 #define PH_HAL4NFC_BUILD 0 92 93 /** HAL Interface Version Macros : Updated for every external release of 94 HAL Interface */ 95 #define PH_HAL4NFC_INTERFACE_VERSION 0 96 #define PH_HAL4NFC_INTERFACE_REVISION 6 97 #define PH_HAL4NFC_INTERFACE_PATCH 0 98 #define PH_HAL4NFC_INTERAFECE_BUILD 0 99 100 /**Maximum length of receive buffer maintained by HAL*/ 101 #define PH_HAL4NFC_MAX_RECEIVE_BUFFER 4096U 102 103 /**Send length used for Transceive*/ 104 #define PH_HAL4NFC_MAX_SEND_LEN PHHAL_MAX_DATASIZE 105 106 /* -----------------Structures and Enumerations -------------------------*/ 107 108 /** 109 * \ingroup grp_mw_external_hal_funcs 110 * 111 * Structure containing information about discovered remote device, like 112 * the number of remote devices found, device specific information 113 * like type of device (eg: ISO14443-4A/4B, NFCIP1 target etc) and 114 * the type sepcific information (eg: UID, SAK etc). This structure is 115 * returned as part of the disocvery notification. For more info refer 116 * \ref phHal4Nfc_ConfigureDiscovery, 117 * \ref phHal4Nfc_RegisterNotification, 118 * \ref pphHal4Nfc_Notification_t, 119 * phHal4Nfc_NotificationInfo_t 120 * 121 * 122 */ 123 typedef struct phHal4Nfc_DiscoveryInfo 124 { 125 uint32_t NumberOfDevices;/**< Number of devices found */ 126 phHal_sRemoteDevInformation_t **ppRemoteDevInfo;/**< Pointer to Remote 127 device info list*/ 128 }phHal4Nfc_DiscoveryInfo_t; 129 130 /** 131 * \ingroup grp_mw_external_hal_funcs 132 * 133 * This is a union returned as part of the \ref pphHal4Nfc_Notification_t 134 * callback. It contains either discovery information or other event 135 * information for which the client has registered using the 136 * \ref phHal4Nfc_RegisterNotification. 137 */ 138 typedef union 139 { 140 phHal4Nfc_DiscoveryInfo_t *psDiscoveryInfo; 141 phHal_sEventInfo_t *psEventInfo; 142 }phHal4Nfc_NotificationInfo_t; 143 144 145 146 /** 147 * \ingroup grp_mw_external_hal_funcs 148 * 149 * Prototype for Generic callback type provided by upper layer. This is used 150 * to return the success or failure status an asynchronous API function which 151 * does not have any other additional information to be returned. Refer 152 * specific function for applicable status codes. 153 */ 154 typedef void (*pphHal4Nfc_GenCallback_t)( 155 void *context, 156 NFCSTATUS status 157 ); 158 159 /** 160 * \ingroup grp_mw_external_hal_funcs 161 * 162 * Disconnect callback type provided by upper layer to called on completion 163 * of disconnect call \ref phHal4Nfc_Disconnect. 164 * 165 */ 166 typedef void (*pphHal4Nfc_DiscntCallback_t)( 167 void *context, 168 phHal_sRemoteDevInformation_t *psDisconnectDevInfo, 169 NFCSTATUS status 170 ); 171 172 /** 173 * \ingroup grp_mw_external_hal_funcs 174 * 175 * Notification callback type used by HAL to provide a Discovery or 176 * Event notification to the upper layer. 177 * 178 */ 179 typedef void (*pphHal4Nfc_Notification_t) ( 180 void *context, 181 phHal_eNotificationType_t type, 182 phHal4Nfc_NotificationInfo_t info, 183 NFCSTATUS status 184 ); 185 186 187 /** 188 * \ingroup grp_mw_external_hal_funcs 189 * 190 * Callback type used to provide a Connect Success or Failure indication to 191 * the upper layer as a result of \ref phHal4Nfc_Connect call used to connect 192 * to discovered remote device. 193 * 194 */ 195 typedef void (*pphHal4Nfc_ConnectCallback_t)( 196 void *context, 197 phHal_sRemoteDevInformation_t *psRemoteDevInfo, 198 NFCSTATUS status 199 ); 200 201 /** 202 * \ingroup grp_mw_external_hal_funcs 203 * 204 * This callback type is used to provide received data and it's size to the 205 * upper layer in \ref phNfc_sData_t format ,when the upper layer has performed 206 * a Transceive operation on a tag or when the Device acts as an Initiator in a 207 * P2P transaction. 208 * 209 * 210 */ 211 typedef void (*pphHal4Nfc_TransceiveCallback_t) ( 212 void *context, 213 phHal_sRemoteDevInformation_t *ConnectedDevice, 214 phNfc_sData_t *pRecvdata, 215 NFCSTATUS status 216 ); 217 218 /** 219 * \ingroup grp_mw_external_hal_funcs 220 * 221 * This callback type is used to provide received data and it's size to the 222 * upper layer in \ref phNfc_sData_t structure, when the upper layer when the 223 * Device acts as a Target in a P2P transaction. 224 * 225 * 226 */ 227 typedef void (*pphHal4Nfc_ReceiveCallback_t) ( 228 void *context, 229 phNfc_sData_t *pDataInfo, 230 NFCSTATUS status 231 ); 232 233 /** 234 * \ingroup grp_mw_external_hal_funcs 235 * 236 * Callback type to inform success or failure of the Ioctl calls 237 * made by upper layer. It may optionally contain response data 238 * depending on the Ioctl command issued. 239 * 240 */ 241 typedef void (*pphHal4Nfc_IoctlCallback_t) (void *context, 242 phNfc_sData_t *pOutData, 243 NFCSTATUS status ); 244 245 /** 246 * \ingroup grp_mw_external_hal_funcs 247 *\if hal 248 * \sa \ref pphHal4Nfc_GenCallback_t 249 * \endif 250 * 251 */ 252 253 /** Same as general callback type, used to inform the completion of 254 * \ref phHal4Nfc_Send call done by when in NFCIP1 Target mode 255 */ 256 typedef pphHal4Nfc_GenCallback_t pphHal4Nfc_SendCallback_t; 257 258 /** 259 * \ingroup grp_mw_external_hal_funcs 260 * 261 * Enum type to distinguish between normal init and test mode init 262 * to be done as part of phHal4Nfc_Open 263 * In test mode init only minimal initialization of the NFC Device 264 * sufficient to run the self test is performed. 265 * 266 * \note Note: No functional features can be accessed when 267 * phHal4Nfc_Open is called with TestModeOn 268 * \ref phHal4Nfc_Open 269 * 270 */ 271 typedef enum{ 272 eInitDefault = 0x00, /**<Complete initialization for normal 273 firmware operation*/ 274 eInitTestModeOn, /**<Limited Initialization used for running self 275 tests */ 276 eInitCustom /**<Reserved for Future Use */ 277 } phHal4Nfc_InitType_t; 278 279 /** 280 * \ingroup grp_mw_external_hal_funcs 281 * 282 * Type to select the type of notification registration 283 * for Tags, P2P and SecureElement and Host Card Emulation events 284 * 285 * \if hal 286 * \ref phHal4Nfc_RegisterNotification,phHal4Nfc_UnregisterNotification 287 * \endif 288 * 289 */ 290 typedef enum{ 291 eRegisterDefault = 0x00, /**<For All other generic notifications 292 like Host Wakeup Notification */ 293 eRegisterTagDiscovery, /**<For Tag Discovery notification*/ 294 eRegisterP2PDiscovery, /**<For P2P Discovery notification*/ 295 eRegisterSecureElement, /**<For Secure Element notification*/ 296 eRegisterHostCardEmulation /**<For notification related to Virtual 297 Card Emulation from host */ 298 } phHal4Nfc_RegisterType_t; 299 300 /** 301 * \ingroup grp_mw_external_hal_funcs 302 * 303 * Specifies the Remote Reader type,either initiator or ISO A/B or Felica 304 * 305 */ 306 typedef struct phHal4Nfc_TransactInfo{ 307 phHal_eRFDevType_t remotePCDType; 308 }phHal4Nfc_TransactInfo_t; 309 310 /*preliminary definitions end*/ 311 312 /* -----------------Exported Functions----------------------------------*/ 313 /** 314 * \if hal 315 * \ingroup grp_hal_common 316 * \else 317 * \ingroup grp_mw_external_hal_funcs 318 * \endif 319 * 320 * This function initializes and establishes a link to the NFC Device. This is 321 * a asynchronous call as it requires a series of setup calls with the NFC 322 * device. The open is complete when the status response callback <em> 323 * pOpenCallback </em> is called. It uses a Hardware Reference 324 * \ref phHal_sHwReference, allocated by the upper layer and the p_board_driver 325 * member initialized with the dal_instance (handle to the communication driver) 326 * and other members initialized to zero or NULL. 327 * 328 * \note 329 * - The device is in initialized state after the command has completed 330 * successfully. 331 * 332 * 333 * \param[in,out] psHwReference Hardware Reference, pre-initialized by upper 334 * layer. Members of this structure are made valid if 335 * this function is successful. \n 336 * 337 * \param[in] InitType Initialization type, used to differentiate between 338 * test mode limited initialization and normal init. 339 * 340 * \param[in] pOpenCallback The open callback function called by the HAL 341 * when open (initialization) sequence is completed or if there 342 * is an error in initialization. \n 343 * 344 * \param[in] pContext Upper layer context which will be included in the 345 * call back when request is completed. \n 346 * 347 * \retval NFCSTATUS_PENDING Open sequence has been successfully 348 * started and result will be conveyed 349 * via the pOpenCallback function. 350 * \retval NFCSTATUS_ALREADY_INITIALISED Device initialization already in 351 * progress. 352 * \retval NFCSTATUS_INVALID_PARAMETER The parameter could not be properly 353 * interpreted (structure uninitialized?). 354 * \retval NFCSTATUS_INSUFFICIENT_RESOURCES Insufficient resources for 355 * completing the request. 356 * \retval Others Errors related to the lower layers. 357 * 358 * \if hal 359 * \sa \ref phHal4Nfc_Close, 360 * \endif 361 */ 362 extern NFCSTATUS phHal4Nfc_Open( 363 phHal_sHwReference_t *psHwReference, 364 phHal4Nfc_InitType_t InitType, 365 pphHal4Nfc_GenCallback_t pOpenCallback, 366 void *pContext 367 ); 368 369 370 371 /** 372 * \if hal 373 * \ingroup grp_hal_common 374 * \else 375 * \ingroup grp_mw_external_hal_funcs 376 * \endif 377 * 378 * Retrieves the capabilities of the device represented by the Hardware 379 * Reference parameter.The HW, FW versions,model-id and other capability 380 * information are located inside the pDevCapabilities parameter. 381 * 382 * \param[in] psHwReference Hardware Reference, pre-initialized 383 * by upper layer. \n 384 * \param[out] psDevCapabilities Pointer to the device capabilities structure 385 * where all relevant capabilities of the 386 * peripheral are stored. \n 387 * \param[in] pContext Upper layer context which will be included in 388 * the call back when request is completed. \n 389 * 390 * \retval NFCSTATUS_SUCCESS Success and the psDevCapabilities is 391 * updated with info. 392 * \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied parameters 393 * could not be properly interpreted. 394 * \retval NFCSTATUS_NOT_INITIALISED Hal is not yet initialized. 395 * \retval Others Errors related to the lower layers. 396 * 397 */ 398 extern NFCSTATUS phHal4Nfc_GetDeviceCapabilities( 399 phHal_sHwReference_t *psHwReference, 400 phHal_sDeviceCapabilities_t *psDevCapabilities, 401 void *pContext 402 ); 403 404 405 /** 406 * \if hal 407 * \ingroup grp_hal_common 408 * \else 409 * \ingroup grp_mw_external_hal_funcs 410 * \endif 411 * 412 * This function is used to Configure discovery wheel (and start if 413 * required) based on the discovery configuration passed. 414 * This includes enabling/disabling of the Reader phases (A, B, F), 415 * NFCIP1 Initiator Speed and duration of the Emulation phase. 416 * Additional optional parameters for each of the features i.e. Reader, 417 * Emulation and Peer2Peer can be set using the 418 * \ref phHal4Nfc_ConfigParameters function 419 * 420 * \param[in] psHwReference Hardware Reference, pre-initialized by 421 * upper layer. \n 422 * 423 * \param[in] discoveryMode Discovery Mode allows to choose between: 424 * discovery configuration and start, stop 425 * discovery and start discovery (with last 426 * set configuration). 427 * \ref phHal_eDiscoveryConfigMode_t 428 * \note Note: Presently only NFC_DISCOVERY_CONFIG is supported, other values 429 * are for future use. When in Reader/Initiator mode it mandatory 430 * to call phHal4Nfc_Connect before any transaction can be performed 431 * with the discovered device. 432 * 433 * \param[in] discoveryCfg Discovery configuration parameters. 434 * Reader A/Reader B, Felica 212, Felica 424, 435 * NFCIP1 Speed, Emulation Enable and Duration. 436 * 437 * 438 * \param[in] pConfigCallback This callback has to be called once Hal 439 * completes the Configuration. 440 * 441 * \param[in] pContext Upper layer context to be returned in the 442 * callback. 443 * 444 * \retval NFCSTATUS_INVALID_PARAMETER Wrong Parameter values. 445 * 446 * \retval NFCSTATUS_NOT_INITIALISED Hal is not initialized. 447 * 448 * \retval NFCSTATUS_BUSY Cannot Configure Hal in 449 * Current state. 450 * 451 * \retval NFCSTATUS_INSUFFICIENT_RESOURCES System Resources insufficient. 452 * 453 * \retval NFCSTATUS_PENDING Configuration request accepted 454 * and Configuration is in progress. 455 * 456 * \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied 457 * parameters could not be properly 458 * interpreted. 459 * \retval Others Errors related to the lower layers 460 * 461 * \note Note: When in Reader/Initiator mode it mandatory 462 * to call phHal4Nfc_Connect before any transaction can be performed 463 * with the discovered device. Even if the HAL client is not 464 * interested in using any of the discovered phHal4Nfc_Connect and 465 * phHal4Nfc_Disconnect should be called to restart the Discovery 466 * wheel 467 * 468 * \ref phHal4Nfc_Connect, phHal4Nfc_Disconnect 469 * 470 */ 471 extern NFCSTATUS phHal4Nfc_ConfigureDiscovery( 472 phHal_sHwReference_t *psHwReference, 473 phHal_eDiscoveryConfigMode_t discoveryMode, 474 phHal_sADD_Cfg_t *discoveryCfg, 475 pphHal4Nfc_GenCallback_t pConfigCallback, 476 void *pContext 477 ); 478 /** 479 * \if hal 480 * \ingroup grp_hal_common 481 * \else 482 * \ingroup grp_mw_external_hal_funcs 483 * \endif 484 * 485 * This function is used to set parameters of various features of the Hal, 486 * based on the CfgType parameter. Presently following configuration 487 * types are supported :- 488 * \n 1. NFC_RF_READER_CONFIG (optional)-> Configure parameters for Reader A 489 * or Reader B based on the configuration passed 490 * \n 2. NFC_P2P_CONFIG (optional)-> Congfigure P2P parameters like 491 * 'General bytes', 'PSL Request' etc. 492 * \n 3. NFC_EMULATION_CONFIG -> Enable and configure the emulation mode 493 * parameters for either NFC Target, SmartMX, UICC and 494 * \n Card Emulation from Host (A, B, F) 495 * All the configuration modes can be called independent of each other. The 496 * setting will typically take effect for the next cycle of the relevant 497 * phase of discovery. For optional configuration internal defaults will be 498 * used in case the configuration is not set. 499 * \note Card emulation from Host and Card Emulation from UICC are mutually 500 * exclusive modes, i.e: only one can be enabled at a time. Using 501 * this function to enable one of the emulation modes implicitly disables the 502 * the other. eg. Setting Type A (or Type B) Emulation from Host disables 503 * card emulation from UICC and vice versa. 504 * 505 * \param[in] psHwReference Hardware Reference, pre-initialized by 506 * upper layer. \n 507 * 508 * \param[in] eCfgType Configuration type which can take one of the 509 * enum values of \ref phHal_eConfigType_t. Each 510 * config type is associated with its corresponding 511 * information which is passed using the uCfg structure. 512 * 513 * 514 * \param[in] uCfg Union containing configuration information, 515 * which will be interpreted based on eCfgType 516 * parameter. 517 * 518 * 519 * \param[in] pConfigCallback This callback has to be called once Hal 520 * completes the Configuration. 521 * 522 * \param[in] pContext Upper layer context to be returned in the 523 * callback. 524 * 525 * \retval NFCSTATUS_INVALID_PARAMETER Wrong Parameter values. 526 * 527 * \retval NFCSTATUS_NOT_INITIALISED Hal is not initialized. 528 * 529 * \retval NFCSTATUS_BUSY Cannot Configure Hal in 530 * Current state. 531 * 532 * \retval NFCSTATUS_INSUFFICIENT_RESOURCES System Resources insufficient. 533 * 534 * \retval NFCSTATUS_PENDING Configuration request accepted 535 * and Configuration is in progress. 536 * 537 * \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied 538 * parameters could not be properly 539 * interpreted. 540 * \retval Others Errors related to the lower layers 541 */ 542 543 extern NFCSTATUS phHal4Nfc_ConfigParameters( 544 phHal_sHwReference_t *psHwReference, 545 phHal_eConfigType_t eCfgType, 546 phHal_uConfig_t *uCfg, 547 pphHal4Nfc_GenCallback_t pConfigCallback, 548 void *pContext 549 ); 550 551 /** 552 * \if hal 553 * \ingroup grp_hal_nfci 554 * \else 555 * \ingroup grp_mw_external_hal_funcs 556 * \endif 557 * 558 * This function is called to connect to a one (out of many if multiple 559 * devices are discovered) already discovered Remote Device notified 560 * through register notification. The Remote Device Information structure is 561 * already pre-initialized with data (e.g. from Discovery Notificaiton 562 * Callback) A new session is started after the connect function returns 563 * successfully. The session ends with a successful disconnect 564 * (see \ref phHal4Nfc_Disconnect). 565 * 566 * \param[in] psHwReference Hardware Reference, pre-initialized by 567 * upper layer. \n 568 * 569 * \param[in,out] psRemoteDevInfo Points to the Remote Device Information 570 * structure. The members of it can be 571 * re-used from a previous session. 572 * 573 * \param[in] pNotifyConnectCb Upper layer callback to be called for 574 * notifying Connect Success/Failure 575 * 576 * \param[in] pContext Upper layer context to be returned in 577 * pNotifyConnectCb. 578 * 579 * \retval NFCSTATUS_PENDING Request initiated, result will 580 * be informed through the callback. 581 * \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied 582 * parameters could not be 583 * properly interpreted. 584 * \retval NFCSTATUS_FAILED More than one phHal4Nfc_Connect 585 * is not allowed during a session 586 * on the same remote device. The 587 * session has to be closed before 588 * (see\ref phHal4Nfc_Disconnect). 589 * \retval NFCSTATUS_NOT_INITIALIZED Hal is not initialized. 590 * \retval NFCSTATUS_FEATURE_NOT_SUPPORTED Reactivation is not supported for 591 * NfcIp target and Jewel/Topaz 592 * remote device types. 593 * \retval NFCSTATUS_INVALID_REMOTE_DEVICE The Remote Device Identifier is 594 * not valid. 595 * \retval Others Errors related to the lower layers. 596 * 597 * \if hal 598 * \sa \ref phHal4Nfc_Disconnect 599 * \endif 600 */ 601 extern NFCSTATUS phHal4Nfc_Connect( 602 phHal_sHwReference_t *psHwReference, 603 phHal_sRemoteDevInformation_t *psRemoteDevInfo, 604 pphHal4Nfc_ConnectCallback_t pNotifyConnectCb, 605 void *pContext 606 ); 607 608 609 /** 610 * \if hal 611 * \ingroup grp_hal_nfci 612 * \else 613 * \ingroup grp_mw_external_hal_funcs 614 * \endif 615 * 616 * The phHal4Nfc_Transceive function allows to send data to and receive data 617 * from the Remote Device selected by the caller.It is also used by the 618 * NFCIP1 Initiator while performing a transaction with the NFCIP1 target. 619 * The caller has to provide the Remote Device Information structure and the 620 * command in order to communicate with the selected remote device.For P2P 621 * transactions the command type will not be used. 622 * 623 * 624 * \note the RecvData should be valid until the pTrcvCallback has been called. 625 * 626 * 627 * \param[in] psHwReference Hardware Reference, pre-initialized by 628 * upper layer. \n 629 * 630 * \param[in,out] psTransceiveInfo Information required by transceive is 631 * concealed in this structure.It contains 632 * the send,receive buffers and their 633 * lengths. 634 * 635 * \param[in] psRemoteDevInfo Points to the Remote Device Information 636 * structure which identifies the selected 637 * Remote Device. 638 * 639 * \param[in] pTrcvCallback Callback function for returning the 640 * received response or error. 641 * 642 * \param[in] pContext Upper layer context to be returned in 643 * the callback. 644 * 645 * \retval NFCSTATUS_PENDING Transceive initiated.pTrcvCallback 646 * will return the response or error. 647 * \retval NFCSTATUS_NOT_INITIALIZED Hal is not initialized. 648 * \retval NFCSTATUS_SUCCESS This status is used when send data 649 * length is zero and HAL contains 650 * previously more bytes from previous 651 * receive. \n 652 * \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied 653 * parameters could not be properly 654 * interpreted or are invalid. 655 * \retval NFCSTATUS_INVALID_DEVICE The device has not been opened or 656 * has been disconnected meanwhile. 657 * \retval NFCSTATUS_FEATURE_NOT_SUPPORTED Transaction on this Device type is 658 * not supported. 659 * \retval NFCSTATUS_BUSY Previous transaction is not 660 * completed. 661 * \retval NFCSTATUS_INSUFFICIENT_RESOURCES System resources are insufficient 662 * to complete the request at that 663 * point in time. 664 * \retval NFCSTATUS_MORE_INFORMATION Received number of bytes is greater 665 * than receive buffer provided by the 666 * upper layer.Extra bytes will be 667 * retained by Hal and returned on next 668 * call to transceive. 669 * \retval Others Errors related to the lower layers. 670 * 671 */ 672 extern NFCSTATUS phHal4Nfc_Transceive( 673 phHal_sHwReference_t *psHwReference, 674 phHal_sTransceiveInfo_t *psTransceiveInfo, 675 phHal_sRemoteDevInformation_t *psRemoteDevInfo, 676 pphHal4Nfc_TransceiveCallback_t pTrcvCallback, 677 void *pContext 678 ); 679 680 681 682 683 /** 684 * \if hal 685 * \ingroup grp_hal_nfci 686 * \else 687 * \ingroup grp_mw_external_hal_funcs 688 * \endif 689 * 690 * The function allows to disconnect from a specific Remote Device. This 691 * function closes the session opened with \ref phHal4Nfc_Connect "Connect".It 692 * is also used to switch from wired to virtual mode in case the discovered 693 * device is SmartMX in wired mode. The status of discovery wheel after 694 * disconnection is determined by the ReleaseType parameter. 695 * 696 * 697 * 698 * \param[in] psHwReference Hardware Reference, pre-initialized by 699 * upper layer. \n 700 * \param[in,out] psRemoteDevInfo Points to the valid (connected) Remote 701 * Device Information structure. 702 * 703 * \param[in] ReleaseType Defines various modes of releasing an acquired 704 * target or tag 705 * 706 * \param[in] pDscntCallback Callback function to notify 707 * disconnect success/error. 708 * 709 * \param[in] pContext Upper layer context to be returned in 710 * the callback. 711 * 712 * 713 * \retval NFCSTATUS_PENDING Disconnect initiated.pDscntCallback 714 * will return the response or error. 715 * \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied 716 * parameters could not be properly 717 * interpreted. 718 * \retval NFCSTATUS_INVALID_REMOTE_DEVICE The device has not been opened 719 * before or has already been closed. 720 * \retval NFCSTATUS_NOT_INITIALIZED Hal is not initialized. 721 * \retval Others Errors related to the lower layers. 722 * 723 * \if hal 724 * \sa \ref phHal4Nfc_Connect 725 * \endif 726 */ 727 extern NFCSTATUS phHal4Nfc_Disconnect( 728 phHal_sHwReference_t *psHwReference, 729 phHal_sRemoteDevInformation_t *psRemoteDevInfo, 730 phHal_eReleaseType_t ReleaseType, 731 pphHal4Nfc_DiscntCallback_t pDscntCallback, 732 void *pContext 733 ); 734 735 /** 736 * \if hal 737 * \ingroup grp_hal_common 738 * \else 739 * \ingroup grp_mw_external_hal_funcs 740 * \endif 741 * 742 * The function allows to do a one time check on whether the connected target 743 * is still present in the field of the Reader. The call back returns the 744 * result of the presence check sequence indicating whether it is still present 745 * or moved out of the reader field. 746 * 747 * \param[in] psHwReference Hardware Reference, pre-initialized by 748 * upper layer. \n 749 * 750 * \param[in] pPresenceChkCb Callback function called on completion of the 751 * presence check sequence or in case an error 752 * has occurred.. 753 * 754 * \param[in] context Upper layer context to be returned in the 755 * callback. 756 * 757 * \retval NFCSTATUS_PENDING Call successfully issued to lower layer. 758 * Status will be returned in pPresenceChkCb. 759 * 760 * \retval NFCSTATUS_NOT_INITIALISED The device has not been opened or has 761 * been disconnected meanwhile. 762 * 763 * \retval NFCSTATUS_BUSY Previous presence check callback has not 764 * been received 765 * 766 * \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied parameters 767 * could not be properly interpreted. 768 * 769 * \retval NFCSTATUS_RELEASED P2P target has been released by Initiator. 770 * \retval Others Errors related to the lower layers 771 * 772 */ 773 extern NFCSTATUS phHal4Nfc_PresenceCheck( 774 phHal_sHwReference_t *psHwReference, 775 pphHal4Nfc_GenCallback_t pPresenceChkCb, 776 void *context 777 ); 778 779 780 /** 781 * \if hal 782 * \ingroup grp_hal_common 783 * \else 784 * \ingroup grp_mw_external_hal_funcs 785 * \endif 786 * 787 * The I/O Control function allows the caller to use (vendor-) specific 788 * functionality provided by the lower layer or by the hardware. Each feature 789 * is accessible via a specific IOCTL Code and has to be documented by the 790 * provider of the driver and the hardware. 791 * See "IOCTL Codes" for the definition of a standard command set.\n 792 * 793 * 794 * \param[in] psHwReference Hardware Reference, pre-initialized by 795 * upper layer. \n 796 * \param[in] IoctlCode Control code for the operation. 797 * This value identifies the specific 798 * operation to be performed and are defined 799 * in \ref phNfcIoctlCode.h 800 * 801 * \param[in] pInParam Pointer to any input data structure 802 * containing data which is interpreted 803 * based on Ioctl code and the length of 804 * the data. 805 * 806 * \param[in] pOutParam Pointer to output data structure 807 * containing data which is returned as a 808 * result of the Ioctl operation and the 809 * length of the data. 810 * 811 * \param[in] pIoctlCallback callback function called in case an 812 * error has occurred while performing 813 * requested operation,or on successful 814 * completion of the request 815 * 816 * \param[in] pContext Upper layer context to be returned in 817 * the callback. 818 * 819 * \retval NFCSTATUS_SUCCESS Success. 820 * \retval NFCSTATUS_PENDING Call issued to lower layer.Status will 821 * be notified in pIoctlCallback. 822 * \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied parameters 823 * could not be properly interpreted. 824 * \retval NFCSTATUS_NOT_INITIALIZED Hal is not initialized. 825 * \retval Others Errors related to the lower layers. 826 * 827 */ 828 extern NFCSTATUS phHal4Nfc_Ioctl( 829 phHal_sHwReference_t *psHwReference, 830 uint32_t IoctlCode, 831 phNfc_sData_t *pInParam, 832 phNfc_sData_t *pOutParam, 833 pphHal4Nfc_IoctlCallback_t pIoctlCallback, 834 void *pContext 835 ); 836 837 838 839 /** 840 * \if hal 841 * \ingroup grp_hal_common 842 * \else 843 * \ingroup grp_mw_external_hal_funcs 844 * \endif 845 * 846 * Closes the link to the NFC device. All configurations/setups 847 * done until now are invalidated.To restart communication, phHal4Nfc_Open 848 * needs to be called. The pClosecallback is called when all steps 849 * in the close sequence are completed. 850 * 851 * 852 * \param[in] psHwReference Hardware Reference, pre-initialized by 853 * upper layer. \n 854 * 855 * \param[in] pCloseCallback Callback function called on completion of 856 * the close sequence or in case an error 857 * has occurred.. 858 * 859 * \param[in] pContext Upper layer context to be returned 860 * in the callback. 861 * 862 * \retval NFCSTATUS_SUCCESS Closing successful. 863 * \retval NFCSTATUS_NOT_INITIALIZED The device has not been opened or has 864 * been disconnected meanwhile. 865 * \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied parameters 866 * could not be properly interpreted. 867 * \retval NFCSTATUS_BUSY Configuration is in progress.Shutdown 868 * is not allowed until configure complete. 869 * \retval Others Errors related to the lower layers. 870 * 871 * \if hal 872 * \sa \ref phHal4Nfc_Open 873 * \endif 874 */ 875 extern NFCSTATUS phHal4Nfc_Close( 876 phHal_sHwReference_t *psHwReference, 877 pphHal4Nfc_GenCallback_t pCloseCallback, 878 void *pContext 879 ); 880 881 882 /** 883 * \if hal 884 * \ingroup grp_hal_common 885 * \else 886 * \ingroup grp_mw_external_hal_funcs 887 * \endif 888 * 889 * Forcibly shutdown the HAl.This API makes a call to forcibly shutdown the 890 * lower layer and frees all resources in use by Hal before shutting down.The 891 * API always succeeds.It does not however reset the target. 892 * 893 * \param[in] psHwReference Hardware Reference, pre-initialized by 894 * upper layer. \n 895 * 896 * \param[in] pConfig Reserved for future use. 897 * 898 * 899 */ 900 extern void phHal4Nfc_Hal4Reset( 901 phHal_sHwReference_t *psHwReference, 902 void *pConfig 903 ); 904 905 906 /** 907 * \if hal 908 * \ingroup grp_hal_common 909 * \else 910 * \ingroup grp_mw_external_hal_funcs 911 * \endif 912 * 913 * The function is used by the NFCIP1 Target to respond to packect received 914 * from NFCIP1 initiator. pSendCallback() 915 * is called , when all steps in the send sequence are completed. 916 * 917 * \param[in] psHwReference Hardware Reference, pre-initialized by 918 * upper layer. \n 919 * 920 * \param[in] psTransactInfo information required for transferring 921 * the data 922 * 923 * \param[in] sTransferData Data and the length of the data to be 924 * transferred 925 * 926 * \param[in] pSendCallback Callback function called on completion 927 * of the NfcIP sequence or in case an 928 * error has occurred. 929 * 930 * \param[in] pContext Upper layer context to be returned in 931 * the callback. 932 * 933 * \retval NFCSTATUS_PENDING Send is in progress. 934 * \retval NFCSTATUS_INVALID_DEVICE The device has not been opened or has 935 * been disconnected meanwhile. 936 * \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied parameters 937 * could not be properly interpreted. 938 * \retval NFCSTATUS_NOT_INITIALIZED Hal is not initialized. 939 * \retval Others Errors related to the lower layers. 940 * 941 * 942 */ 943 extern 944 NFCSTATUS 945 phHal4Nfc_Send( 946 phHal_sHwReference_t *psHwReference, 947 phHal4Nfc_TransactInfo_t *psTransactInfo, 948 phNfc_sData_t sTransferData, 949 pphHal4Nfc_SendCallback_t pSendCallback, 950 void *pContext 951 ); 952 953 /** 954 * \if hal 955 * \ingroup grp_hal_common 956 * \else 957 * \ingroup grp_mw_external_hal_funcs 958 * \endif 959 * 960 * This function is called by the NfcIP Peer to wait for receiving data from 961 * the other peer.It is used only by the NfcIP Target. 962 * \note NOTE: After this function is called, its mandatory to wait for the 963 * pphHal4Nfc_ReceiveCallback_t callback, before calling any other function. 964 * Only functions allowed are phHal4Nfc_Close() and phHal4Nfc_Hal4Reset(). 965 * 966 * 967 * \param[in] psHwReference Hardware Reference, pre-initialized by 968 * upper layer. \n 969 * 970 * \param[in] psTransactInfo information required for transferring the 971 * data 972 * 973 * \param[in] pReceiveCallback Callback function called after receiving 974 * the data or in case an error has 975 * has occurred. 976 * 977 * \param[in] pContext Upper layer context to be returned 978 * in the callback. 979 * 980 * \retval NFCSTATUS_PENDING Receive is in progress. 981 * \retval NFCSTATUS_INVALID_DEVICE The device has not been opened or has 982 * been disconnected meanwhile. 983 * \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied parameters 984 * could not be properly interpreted. 985 * \retval NFCSTATUS_NOT_INITIALIZED Hal is not initialized. 986 * \retval Others Errors related to the lower layers 987 * 988 */ 989 extern 990 NFCSTATUS 991 phHal4Nfc_Receive( 992 phHal_sHwReference_t *psHwReference, 993 phHal4Nfc_TransactInfo_t *psTransactInfo, 994 pphHal4Nfc_ReceiveCallback_t pReceiveCallback, 995 void *pContext 996 ); 997 998 999 /** 1000 * \if hal 1001 * \ingroup grp_hal_common 1002 * \else 1003 * \ingroup grp_mw_external_hal_funcs 1004 * \endif 1005 * 1006 * This API is a synchronous call used to register a listener for either tag 1007 * discovery, Secure element notification or P2P Notification or a general 1008 * notification handler for all the three. 1009 * 1010 * 1011 * \param[in] psHwRef Hardware Reference, pre-initialized by 1012 * upper layer. \n 1013 * 1014 * \param[in] eRegisterType Type of Notification registered.Informs 1015 * whether upper layer is interested in Tag 1016 * Discovery,secure element or P2P notification. 1017 * 1018 * \param[in] pNotificationHandler Notification callback.If this parameter is 1019 * NULL,any notification from Hci will be 1020 * ignored and upper layer will not be notified 1021 * of the event. 1022 * 1023 * \param[in] Context Upper layer context. 1024 * 1025 * \retval NFCSTATUS_SUCCESS Notification unregister successful. 1026 * 1027 * \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied parameters 1028 * could not be properly interpreted. 1029 * \retval NFCSTATUS_NOT_INITIALIZED Hal is not initialized. 1030 * 1031 */ 1032 extern NFCSTATUS phHal4Nfc_RegisterNotification( 1033 phHal_sHwReference_t *psHwRef, 1034 phHal4Nfc_RegisterType_t eRegisterType, 1035 pphHal4Nfc_Notification_t pNotificationHandler, 1036 void *Context 1037 ); 1038 1039 /** 1040 * \if hal 1041 * \ingroup grp_hal_common 1042 * \else 1043 * \ingroup grp_mw_external_hal_funcs 1044 * \endif 1045 * 1046 * This API is a synchronous call used to unregister a listener for either tag 1047 * discovery, Secure element notification or P2P Notification, previously 1048 * registered using \ref phHal4Nfc_RegisterNotification. 1049 * 1050 * \param[in] psHwReference Hardware Reference, pre-initialized by 1051 * upper layer. \n 1052 * 1053 * \param[in] eRegisterType Type of registration ,tells whether upper 1054 * layer is interested in unregistering for 1055 * Tag Discovery,Secure element or P2P. \n 1056 * 1057 * \param[in] Context Upper layer context. 1058 * 1059 * \retval NFCSTATUS_SUCCESS Notification unregister successful. 1060 * 1061 * \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied parameters 1062 * could not be properly interpreted. 1063 * 1064 * \retval NFCSTATUS_NOT_INITIALIZED Hal is not initialized. 1065 * 1066 * 1067 */ 1068 extern NFCSTATUS phHal4Nfc_UnregisterNotification( 1069 phHal_sHwReference_t *psHwReference, 1070 phHal4Nfc_RegisterType_t eRegisterType, 1071 void *Context 1072 ); 1073 1074 1075 /** 1076 * \if hal 1077 * \ingroup grp_hal_common 1078 * \else 1079 * \ingroup grp_mw_external_hal_funcs 1080 * \endif 1081 * 1082 * This function is called to switch the SmartMX to Wired Mode. After switching 1083 * to Wired mode the SmartMX can be discovered through Tag Discovery like a normal 1084 * tag and used in the same manner as a tag. SmartMx returns to previous mode 1085 * (Virtual or Off) when the tag is relased by phHal4Nfc_Disconnect 1086 * 1087 * 1088 * \param[in] psHwReference Hardware Reference, pre-initialized by 1089 * upper layer. \n 1090 * 1091 * \param[in] smx_mode Mode to which the switch should be made. 1092 * 1093 * \param[in] pSwitchModecb Callback for Switch mode complete 1094 * with success/error notification. 1095 * 1096 * \param[in] pContext Upper layer context. 1097 * 1098 * \retval NFCSTATUS_PENDING Switch in progress.Status will be 1099 * returned in pSwitchModecb. 1100 * \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied 1101 * parameters could not be properly 1102 * interpreted. 1103 * \retval NFCSTATUS_NOT_INITIALIZED Hal is not initialized. 1104 * \retval NFCSTATUS_BUSY Configuration in Progress or 1105 * remote device is connected. 1106 * \retval NFCSTATUS_INSUFFICIENT_RESOURCES System resources are insufficient 1107 * to complete the request at that 1108 * point in time. 1109 * \retval NFCSTATUS_FAILED No listener has been registered 1110 * by the upper layer for Emulation 1111 * before making this call. 1112 * \retval Others Errors related to the lower 1113 * layers. 1114 */ 1115 extern NFCSTATUS phHal4Nfc_Switch_SMX_Mode( 1116 phHal_sHwReference_t *psHwReference, 1117 phHal_eSmartMX_Mode_t smx_mode, 1118 pphHal4Nfc_GenCallback_t pSwitchModecb, 1119 void *pContext 1120 ); 1121 1122 1123 /** 1124 * \if hal 1125 * \ingroup grp_hal_common 1126 * \else 1127 * \ingroup grp_mw_external_hal_funcs 1128 * \endif 1129 * 1130 * This function is called to switch the UICC on or Off. 1131 * 1132 * 1133 * \param[in] psHwReference Hardware Reference, pre-initialized by 1134 * upper layer. \n 1135 * 1136 * \param[in] smx_mode Mode to which the switch should be made. 1137 * 1138 * \param[in] pSwitchModecb Callback for Switch mode complete 1139 * with success/error notification. 1140 * 1141 * \param[in] pContext Upper layer context. 1142 * 1143 * \retval NFCSTATUS_PENDING Switch in progress.Status will be 1144 * returned in pSwitchModecb. 1145 * \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied 1146 * parameters could not be properly 1147 * interpreted. 1148 * \retval NFCSTATUS_NOT_INITIALIZED Hal is not initialized. 1149 * \retval NFCSTATUS_BUSY Configuration in Progress or 1150 * remote device is connected. 1151 * \retval NFCSTATUS_INSUFFICIENT_RESOURCES System resources are insufficient 1152 * to complete the request at that 1153 * point in time. 1154 * \retval NFCSTATUS_FAILED No listener has been registered 1155 * by the upper layer for Emulation 1156 * before making this call. 1157 * \retval Others Errors related to the lower 1158 * layers. 1159 */ 1160 extern NFCSTATUS phHal4Nfc_Switch_Swp_Mode( 1161 phHal_sHwReference_t *psHwReference, 1162 phHal_eSWP_Mode_t swp_mode, 1163 pphHal4Nfc_GenCallback_t pSwitchModecb, 1164 void *pContext 1165 ); 1166 1167 #endif /* end of PHHAL4NFC_H */ 1168 1169 1170
