2 * Copyright (C) 2010 NXP Semiconductors
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
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
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.
34 * Project: NFC-FRI-1.1 / HAL4.0
36 * $Date: Mon Jun 14 11:36:12 2010 $
39 * $Aliases: NFC_FRI1.1_WK1023_R35_2,NFC_FRI1.1_WK1023_R35_1 $
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.
57 * File: \ref phHal4Nfc.h
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 */
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>
78 /*************************** Includes *******************************/
79 /** \defgroup grp_mw_external_hal_funcs NFC HAL4.0
84 /* ---------------- Macros ----------------------------------------------*/
86 /** HAL Implementation Version Macros : Updated for every feature release of
88 #define PH_HAL4NFC_VERSION 8
89 #define PH_HAL4NFC_REVISION 21
90 #define PH_HAL4NFC_PATCH 1
91 #define PH_HAL4NFC_BUILD 0
93 /** HAL Interface Version Macros : Updated for every external release of
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
100 /**Maximum length of receive buffer maintained by HAL*/
101 #define PH_HAL4NFC_MAX_RECEIVE_BUFFER 4096U
103 /**Send length used for Transceive*/
104 #define PH_HAL4NFC_MAX_SEND_LEN PHHAL_MAX_DATASIZE
106 /* -----------------Structures and Enumerations -------------------------*/
109 * \ingroup grp_mw_external_hal_funcs
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
123 typedef struct phHal4Nfc_DiscoveryInfo
125 uint32_t NumberOfDevices;/**< Number of devices found */
126 phHal_sRemoteDevInformation_t **ppRemoteDevInfo;/**< Pointer to Remote
128 }phHal4Nfc_DiscoveryInfo_t;
131 * \ingroup grp_mw_external_hal_funcs
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.
140 phHal4Nfc_DiscoveryInfo_t *psDiscoveryInfo;
141 phHal_sEventInfo_t *psEventInfo;
142 }phHal4Nfc_NotificationInfo_t;
147 * \ingroup grp_mw_external_hal_funcs
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.
154 typedef void (*pphHal4Nfc_GenCallback_t)(
160 * \ingroup grp_mw_external_hal_funcs
162 * Disconnect callback type provided by upper layer to called on completion
163 * of disconnect call \ref phHal4Nfc_Disconnect.
166 typedef void (*pphHal4Nfc_DiscntCallback_t)(
168 phHal_sRemoteDevInformation_t *psDisconnectDevInfo,
173 * \ingroup grp_mw_external_hal_funcs
175 * Notification callback type used by HAL to provide a Discovery or
176 * Event notification to the upper layer.
179 typedef void (*pphHal4Nfc_Notification_t) (
181 phHal_eNotificationType_t type,
182 phHal4Nfc_NotificationInfo_t info,
188 * \ingroup grp_mw_external_hal_funcs
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.
195 typedef void (*pphHal4Nfc_ConnectCallback_t)(
197 phHal_sRemoteDevInformation_t *psRemoteDevInfo,
202 * \ingroup grp_mw_external_hal_funcs
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
211 typedef void (*pphHal4Nfc_TransceiveCallback_t) (
213 phHal_sRemoteDevInformation_t *ConnectedDevice,
214 phNfc_sData_t *pRecvdata,
219 * \ingroup grp_mw_external_hal_funcs
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.
227 typedef void (*pphHal4Nfc_ReceiveCallback_t) (
229 phNfc_sData_t *pDataInfo,
234 * \ingroup grp_mw_external_hal_funcs
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.
241 typedef void (*pphHal4Nfc_IoctlCallback_t) (void *context,
242 phNfc_sData_t *pOutData,
246 * \ingroup grp_mw_external_hal_funcs
248 * \sa \ref pphHal4Nfc_GenCallback_t
253 /** Same as general callback type, used to inform the completion of
254 * \ref phHal4Nfc_Send call done by when in NFCIP1 Target mode
256 typedef pphHal4Nfc_GenCallback_t pphHal4Nfc_SendCallback_t;
259 * \ingroup grp_mw_external_hal_funcs
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.
266 * \note Note: No functional features can be accessed when
267 * phHal4Nfc_Open is called with TestModeOn
268 * \ref phHal4Nfc_Open
272 eInitDefault = 0x00, /**<Complete initialization for normal
274 eInitTestModeOn, /**<Limited Initialization used for running self
276 eInitCustom /**<Reserved for Future Use */
277 } phHal4Nfc_InitType_t;
280 * \ingroup grp_mw_external_hal_funcs
282 * Type to select the type of notification registration
283 * for Tags, P2P and SecureElement and Host Card Emulation events
286 * \ref phHal4Nfc_RegisterNotification,phHal4Nfc_UnregisterNotification
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;
301 * \ingroup grp_mw_external_hal_funcs
303 * Specifies the Remote Reader type,either initiator or ISO A/B or Felica
306 typedef struct phHal4Nfc_TransactInfo{
307 phHal_eRFDevType_t remotePCDType;
308 }phHal4Nfc_TransactInfo_t;
310 /*preliminary definitions end*/
312 /* -----------------Exported Functions----------------------------------*/
315 * \ingroup grp_hal_common
317 * \ingroup grp_mw_external_hal_funcs
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.
329 * - The device is in initialized state after the command has completed
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
337 * \param[in] InitType Initialization type, used to differentiate between
338 * test mode limited initialization and normal init.
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
344 * \param[in] pContext Upper layer context which will be included in the
345 * call back when request is completed. \n
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
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.
359 * \sa \ref phHal4Nfc_Close,
362 extern NFCSTATUS phHal4Nfc_Open(
363 phHal_sHwReference_t *psHwReference,
364 phHal4Nfc_InitType_t InitType,
365 pphHal4Nfc_GenCallback_t pOpenCallback,
373 * \ingroup grp_hal_common
375 * \ingroup grp_mw_external_hal_funcs
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.
382 * \param[in] psHwReference Hardware Reference, pre-initialized
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
390 * \retval NFCSTATUS_SUCCESS Success and the psDevCapabilities is
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.
398 extern NFCSTATUS phHal4Nfc_GetDeviceCapabilities(
399 phHal_sHwReference_t *psHwReference,
400 phHal_sDeviceCapabilities_t *psDevCapabilities,
407 * \ingroup grp_hal_common
409 * \ingroup grp_mw_external_hal_funcs
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
420 * \param[in] psHwReference Hardware Reference, pre-initialized by
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.
433 * \param[in] discoveryCfg Discovery configuration parameters.
434 * Reader A/Reader B, Felica 212, Felica 424,
435 * NFCIP1 Speed, Emulation Enable and Duration.
438 * \param[in] pConfigCallback This callback has to be called once Hal
439 * completes the Configuration.
441 * \param[in] pContext Upper layer context to be returned in the
444 * \retval NFCSTATUS_INVALID_PARAMETER Wrong Parameter values.
446 * \retval NFCSTATUS_NOT_INITIALISED Hal is not initialized.
448 * \retval NFCSTATUS_BUSY Cannot Configure Hal in
451 * \retval NFCSTATUS_INSUFFICIENT_RESOURCES System Resources insufficient.
453 * \retval NFCSTATUS_PENDING Configuration request accepted
454 * and Configuration is in progress.
456 * \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied
457 * parameters could not be properly
459 * \retval Others Errors related to the lower layers
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
468 * \ref phHal4Nfc_Connect, phHal4Nfc_Disconnect
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,
480 * \ingroup grp_hal_common
482 * \ingroup grp_mw_external_hal_funcs
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.
505 * \param[in] psHwReference Hardware Reference, pre-initialized by
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.
514 * \param[in] uCfg Union containing configuration information,
515 * which will be interpreted based on eCfgType
519 * \param[in] pConfigCallback This callback has to be called once Hal
520 * completes the Configuration.
522 * \param[in] pContext Upper layer context to be returned in the
525 * \retval NFCSTATUS_INVALID_PARAMETER Wrong Parameter values.
527 * \retval NFCSTATUS_NOT_INITIALISED Hal is not initialized.
529 * \retval NFCSTATUS_BUSY Cannot Configure Hal in
532 * \retval NFCSTATUS_INSUFFICIENT_RESOURCES System Resources insufficient.
534 * \retval NFCSTATUS_PENDING Configuration request accepted
535 * and Configuration is in progress.
537 * \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied
538 * parameters could not be properly
540 * \retval Others Errors related to the lower layers
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,
553 * \ingroup grp_hal_nfci
555 * \ingroup grp_mw_external_hal_funcs
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).
566 * \param[in] psHwReference Hardware Reference, pre-initialized by
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.
573 * \param[in] pNotifyConnectCb Upper layer callback to be called for
574 * notifying Connect Success/Failure
576 * \param[in] pContext Upper layer context to be returned in
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
595 * \retval Others Errors related to the lower layers.
598 * \sa \ref phHal4Nfc_Disconnect
601 extern NFCSTATUS phHal4Nfc_Connect(
602 phHal_sHwReference_t *psHwReference,
603 phHal_sRemoteDevInformation_t *psRemoteDevInfo,
604 pphHal4Nfc_ConnectCallback_t pNotifyConnectCb,
611 * \ingroup grp_hal_nfci
613 * \ingroup grp_mw_external_hal_funcs
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.
624 * \note the RecvData should be valid until the pTrcvCallback has been called.
627 * \param[in] psHwReference Hardware Reference, pre-initialized by
630 * \param[in,out] psTransceiveInfo Information required by transceive is
631 * concealed in this structure.It contains
632 * the send,receive buffers and their
635 * \param[in] psRemoteDevInfo Points to the Remote Device Information
636 * structure which identifies the selected
639 * \param[in] pTrcvCallback Callback function for returning the
640 * received response or error.
642 * \param[in] pContext Upper layer context to be returned in
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
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
659 * \retval NFCSTATUS_BUSY Previous transaction is not
661 * \retval NFCSTATUS_INSUFFICIENT_RESOURCES System resources are insufficient
662 * to complete the request at that
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.
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,
685 * \ingroup grp_hal_nfci
687 * \ingroup grp_mw_external_hal_funcs
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.
698 * \param[in] psHwReference Hardware Reference, pre-initialized by
700 * \param[in,out] psRemoteDevInfo Points to the valid (connected) Remote
701 * Device Information structure.
703 * \param[in] ReleaseType Defines various modes of releasing an acquired
706 * \param[in] pDscntCallback Callback function to notify
707 * disconnect success/error.
709 * \param[in] pContext Upper layer context to be returned in
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
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.
724 * \sa \ref phHal4Nfc_Connect
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,
737 * \ingroup grp_hal_common
739 * \ingroup grp_mw_external_hal_funcs
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.
747 * \param[in] psHwReference Hardware Reference, pre-initialized by
750 * \param[in] pPresenceChkCb Callback function called on completion of the
751 * presence check sequence or in case an error
754 * \param[in] context Upper layer context to be returned in the
757 * \retval NFCSTATUS_PENDING Call successfully issued to lower layer.
758 * Status will be returned in pPresenceChkCb.
760 * \retval NFCSTATUS_NOT_INITIALISED The device has not been opened or has
761 * been disconnected meanwhile.
763 * \retval NFCSTATUS_BUSY Previous presence check callback has not
766 * \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied parameters
767 * could not be properly interpreted.
769 * \retval NFCSTATUS_RELEASED P2P target has been released by Initiator.
770 * \retval Others Errors related to the lower layers
773 extern NFCSTATUS phHal4Nfc_PresenceCheck(
774 phHal_sHwReference_t *psHwReference,
775 pphHal4Nfc_GenCallback_t pPresenceChkCb,
782 * \ingroup grp_hal_common
784 * \ingroup grp_mw_external_hal_funcs
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
794 * \param[in] psHwReference Hardware Reference, pre-initialized by
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
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
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.
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
816 * \param[in] pContext Upper layer context to be returned in
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.
828 extern NFCSTATUS phHal4Nfc_Ioctl(
829 phHal_sHwReference_t *psHwReference,
831 phNfc_sData_t *pInParam,
832 phNfc_sData_t *pOutParam,
833 pphHal4Nfc_IoctlCallback_t pIoctlCallback,
841 * \ingroup grp_hal_common
843 * \ingroup grp_mw_external_hal_funcs
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.
852 * \param[in] psHwReference Hardware Reference, pre-initialized by
855 * \param[in] pCloseCallback Callback function called on completion of
856 * the close sequence or in case an error
859 * \param[in] pContext Upper layer context to be returned
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.
872 * \sa \ref phHal4Nfc_Open
875 extern NFCSTATUS phHal4Nfc_Close(
876 phHal_sHwReference_t *psHwReference,
877 pphHal4Nfc_GenCallback_t pCloseCallback,
884 * \ingroup grp_hal_common
886 * \ingroup grp_mw_external_hal_funcs
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.
893 * \param[in] psHwReference Hardware Reference, pre-initialized by
896 * \param[in] pConfig Reserved for future use.
900 extern void phHal4Nfc_Hal4Reset(
901 phHal_sHwReference_t *psHwReference,
908 * \ingroup grp_hal_common
910 * \ingroup grp_mw_external_hal_funcs
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.
917 * \param[in] psHwReference Hardware Reference, pre-initialized by
920 * \param[in] psTransactInfo information required for transferring
923 * \param[in] sTransferData Data and the length of the data to be
926 * \param[in] pSendCallback Callback function called on completion
927 * of the NfcIP sequence or in case an
928 * error has occurred.
930 * \param[in] pContext Upper layer context to be returned in
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.
946 phHal_sHwReference_t *psHwReference,
947 phHal4Nfc_TransactInfo_t *psTransactInfo,
948 phNfc_sData_t sTransferData,
949 pphHal4Nfc_SendCallback_t pSendCallback,
955 * \ingroup grp_hal_common
957 * \ingroup grp_mw_external_hal_funcs
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().
967 * \param[in] psHwReference Hardware Reference, pre-initialized by
970 * \param[in] psTransactInfo information required for transferring the
973 * \param[in] pReceiveCallback Callback function called after receiving
974 * the data or in case an error has
977 * \param[in] pContext Upper layer context to be returned
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
992 phHal_sHwReference_t *psHwReference,
993 phHal4Nfc_TransactInfo_t *psTransactInfo,
994 pphHal4Nfc_ReceiveCallback_t pReceiveCallback,
1001 * \ingroup grp_hal_common
1003 * \ingroup grp_mw_external_hal_funcs
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.
1011 * \param[in] psHwRef Hardware Reference, pre-initialized by
1014 * \param[in] eRegisterType Type of Notification registered.Informs
1015 * whether upper layer is interested in Tag
1016 * Discovery,secure element or P2P notification.
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
1023 * \param[in] Context Upper layer context.
1025 * \retval NFCSTATUS_SUCCESS Notification unregister successful.
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.
1032 extern NFCSTATUS phHal4Nfc_RegisterNotification(
1033 phHal_sHwReference_t *psHwRef,
1034 phHal4Nfc_RegisterType_t eRegisterType,
1035 pphHal4Nfc_Notification_t pNotificationHandler,
1041 * \ingroup grp_hal_common
1043 * \ingroup grp_mw_external_hal_funcs
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.
1050 * \param[in] psHwReference Hardware Reference, pre-initialized by
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
1057 * \param[in] Context Upper layer context.
1059 * \retval NFCSTATUS_SUCCESS Notification unregister successful.
1061 * \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied parameters
1062 * could not be properly interpreted.
1064 * \retval NFCSTATUS_NOT_INITIALIZED Hal is not initialized.
1068 extern NFCSTATUS phHal4Nfc_UnregisterNotification(
1069 phHal_sHwReference_t *psHwReference,
1070 phHal4Nfc_RegisterType_t eRegisterType,
1077 * \ingroup grp_hal_common
1079 * \ingroup grp_mw_external_hal_funcs
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
1088 * \param[in] psHwReference Hardware Reference, pre-initialized by
1091 * \param[in] smx_mode Mode to which the switch should be made.
1093 * \param[in] pSwitchModecb Callback for Switch mode complete
1094 * with success/error notification.
1096 * \param[in] pContext Upper layer context.
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
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
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
1115 extern NFCSTATUS phHal4Nfc_Switch_SMX_Mode(
1116 phHal_sHwReference_t *psHwReference,
1117 phHal_eSmartMX_Mode_t smx_mode,
1118 pphHal4Nfc_GenCallback_t pSwitchModecb,
1125 * \ingroup grp_hal_common
1127 * \ingroup grp_mw_external_hal_funcs
1130 * This function is called to switch the UICC on or Off.
1133 * \param[in] psHwReference Hardware Reference, pre-initialized by
1136 * \param[in] smx_mode Mode to which the switch should be made.
1138 * \param[in] pSwitchModecb Callback for Switch mode complete
1139 * with success/error notification.
1141 * \param[in] pContext Upper layer context.
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
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
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
1160 extern NFCSTATUS phHal4Nfc_Switch_Swp_Mode(
1161 phHal_sHwReference_t *psHwReference,
1162 phHal_eSWP_Mode_t swp_mode,
1163 pphHal4Nfc_GenCallback_t pSwitchModecb,
1167 #endif /* end of PHHAL4NFC_H */