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 */ 123typedef 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 */ 138typedef 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*/ 154typedef 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*/ 166typedef 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*/ 179typedef 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*/ 195typedef 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*/ 211typedef 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*/ 227typedef 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*/ 241typedef 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*/ 256typedef 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*/ 271typedef 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*/ 290typedef 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*/ 306typedef 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 */ 362extern 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 */ 398extern 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*/ 471extern 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 543extern 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 */ 601extern 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 */ 672extern 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 */ 727extern 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*/ 773extern 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 */ 828extern 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 */ 875extern 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 */ 900extern 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*/ 943extern 944NFCSTATUS 945phHal4Nfc_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*/ 989extern 990NFCSTATUS 991phHal4Nfc_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*/ 1032extern 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*/ 1068extern 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*/ 1115extern 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*/ 1160extern 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