summaryrefslogtreecommitdiffstats
path: root/src/phHal4Nfc.h
blob: 47e3136ca39c525190a887329e01c6462ec2ce8e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
/*
 * Copyright (C) 2010 NXP Semiconductors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */


/**
 * \file phHal4Nfc.h
 * \brief HAL Function Prototypes
 *  The HAL4.0 API provides the user to have a interface for PN544(PN54x)/PN65N
 *  NFC device.The API is a non-blocking API, asynchronous API. This means that
 *  when ever an API function call results in waiting for a response from the
 *  NFC device, the API function will return immediately with status 'PENDING'
 *  and the actual result will be returned through specific callback functions
 *  on receiving the response from the NFC device
 *
 * \note This is the representative header file of the HAL 4.0. The release
 *       TAG or label is representing the release TAG (alias) of the entire
 *       library.A mechanism (see documentation \ref hal_release_label near
 *       the include guards of this file) is used to propagate the alias to
 *       the main documentation page.
 *
 * Project: NFC-FRI-1.1 / HAL4.0
 *
 * $Date: Mon Jun 14 11:36:12 2010 $
 * $Author: ing07385 $
 * $Revision: 1.171 $
 * $Aliases: NFC_FRI1.1_WK1023_R35_2,NFC_FRI1.1_WK1023_R35_1 $
 *
 */

/** page hal_release_label HAL 4.0 Release Label
 *  SDK_HAL_4.0 v 0.1 Draft
 *  \note This is the TAG (label, alias) of the HAL. If the string is empty,the
 *        current documentation has not been generated from an official release.
 */
/*@{*/
#ifndef PHHAL4NFC_H
#define PHHAL4NFC_H
/*@}*/


/**
 *  \name HAL4
 *
 * File: \ref phHal4Nfc.h
 *\def  hal
 */

/*@{*/
#define PH_HAL4NFC_FILEREVISION "$Revision: 1.171 $" /**< \ingroup grp_file_attributes */
#define PH_HAL4NFC_FILEALIASES  "$Aliases: NFC_FRI1.1_WK1023_R35_2,NFC_FRI1.1_WK1023_R35_1 $"     /**< \ingroup grp_file_attributes */
/*@}*/

/* -----------------Include files ---------------------------------------*/
#include <phNfcStatus.h>
#include <phNfcCompId.h>
#include <phNfcHalTypes.h>
#include <phNfcInterface.h>
#include <phNfcIoctlCode.h>
#include <phNfcConfig.h>
#include <phDbgTrace.h>
#ifdef ANDROID
#include <string.h>
#endif

/*************************** Includes *******************************/
/** \defgroup grp_mw_external_hal_funcs NFC HAL4.0
*
*
*
*/
/* ---------------- Macros ----------------------------------------------*/

/** HAL Implementation Version Macros : Updated for every feature release of
    HAL functionality */
#define PH_HAL4NFC_VERSION                              8
#define PH_HAL4NFC_REVISION                            21
#define PH_HAL4NFC_PATCH                                1 
#define PH_HAL4NFC_BUILD                                0

/** HAL Interface Version Macros : Updated for every external release of
    HAL Interface */
#define PH_HAL4NFC_INTERFACE_VERSION                    0
#define PH_HAL4NFC_INTERFACE_REVISION                   6
#define PH_HAL4NFC_INTERFACE_PATCH                      0
#define PH_HAL4NFC_INTERAFECE_BUILD                     0

/**Maximum length of receive buffer maintained by HAL*/
#define PH_HAL4NFC_MAX_RECEIVE_BUFFER                4096U

/**Send length used for Transceive*/
#define PH_HAL4NFC_MAX_SEND_LEN                      PHHAL_MAX_DATASIZE

/* -----------------Structures and Enumerations -------------------------*/

/**
 * \ingroup grp_mw_external_hal_funcs
 *
 * Structure containing information about discovered remote device, like
 * the number of remote devices found, device specific information
 * like type of device (eg: ISO14443-4A/4B, NFCIP1 target etc) and
 * the type sepcific information (eg: UID, SAK etc). This structure is
 * returned as part of the disocvery notification. For more info refer
 * \ref phHal4Nfc_ConfigureDiscovery,
 * \ref phHal4Nfc_RegisterNotification,
 * \ref pphHal4Nfc_Notification_t,
 * phHal4Nfc_NotificationInfo_t
 *
 *
 */
typedef struct phHal4Nfc_DiscoveryInfo
{
    uint32_t NumberOfDevices;/**< Number of devices found */
    phHal_sRemoteDevInformation_t **ppRemoteDevInfo;/**< Pointer to Remote
                                                         device info list*/
}phHal4Nfc_DiscoveryInfo_t;

/**
 * \ingroup grp_mw_external_hal_funcs
 *
 *  This is a union returned as part of the \ref pphHal4Nfc_Notification_t
 *  callback. It contains either discovery information or other event
 *  information for which the client has registered using the
 *  \ref phHal4Nfc_RegisterNotification.
 */
typedef union
{
    phHal4Nfc_DiscoveryInfo_t *psDiscoveryInfo;
    phHal_sEventInfo_t        *psEventInfo;
}phHal4Nfc_NotificationInfo_t;



/**
* \ingroup grp_mw_external_hal_funcs
*
* Prototype for Generic callback type provided by upper layer. This is used
* to return the success or failure status an asynchronous API function which
* does not have any other additional information to be returned. Refer
* specific function for applicable status codes.
*/
typedef void (*pphHal4Nfc_GenCallback_t)(
                                        void  *context,
                                        NFCSTATUS status
                                        );

/**
* \ingroup grp_mw_external_hal_funcs
*
* Disconnect callback type provided by upper layer to called on completion
* of disconnect call \ref phHal4Nfc_Disconnect.
*
*/
typedef void (*pphHal4Nfc_DiscntCallback_t)(
                        void  *context,
                        phHal_sRemoteDevInformation_t *psDisconnectDevInfo,
                        NFCSTATUS status
                        );

/**
* \ingroup grp_mw_external_hal_funcs
*
* Notification callback type used by HAL to provide a Discovery or
* Event notification to the upper layer.
*
*/
typedef void (*pphHal4Nfc_Notification_t) (
                                        void                         *context,
                                        phHal_eNotificationType_t     type,
                                        phHal4Nfc_NotificationInfo_t  info,
                                        NFCSTATUS                    status
                                        );


/**
* \ingroup grp_mw_external_hal_funcs
*
* Callback type used to provide a Connect Success or Failure indication to
* the upper layer as a result of \ref phHal4Nfc_Connect call used to connect
* to discovered remote device.
*
*/
typedef void (*pphHal4Nfc_ConnectCallback_t)(
                        void  *context,
                        phHal_sRemoteDevInformation_t *psRemoteDevInfo,
                        NFCSTATUS status
                        );

/**
* \ingroup grp_mw_external_hal_funcs
*
* This callback type is used to provide received data and it's size to the
* upper layer in \ref phNfc_sData_t format ,when the upper layer has performed
* a Transceive operation on a tag or when the Device acts as an Initiator in a
* P2P transaction.
*
*
*/
typedef void (*pphHal4Nfc_TransceiveCallback_t) (
                                void *context,
                                phHal_sRemoteDevInformation_t *ConnectedDevice,
                                phNfc_sData_t  *pRecvdata,
                                NFCSTATUS status
                                );

/**
* \ingroup grp_mw_external_hal_funcs
*
* This callback type is used to provide received data and it's size to the
* upper layer in  \ref phNfc_sData_t structure, when the upper layer when the
* Device acts as a Target in a P2P transaction.
*
*
*/
typedef void (*pphHal4Nfc_ReceiveCallback_t) (
                                    void                *context,
                                    phNfc_sData_t       *pDataInfo,
                                    NFCSTATUS            status
                                    );

/**
* \ingroup grp_mw_external_hal_funcs
*
* Callback type to inform success or failure of the Ioctl calls
* made by upper layer. It may optionally contain response data
* depending on the Ioctl command issued.
*
*/
typedef void (*pphHal4Nfc_IoctlCallback_t) (void          *context,
                                            phNfc_sData_t *pOutData,
                                            NFCSTATUS      status );

/**
* \ingroup grp_mw_external_hal_funcs
*\if hal
*   \sa \ref pphHal4Nfc_GenCallback_t
* \endif
*
*/

/** Same as general callback type, used to inform the completion of
* \ref phHal4Nfc_Send call done by when in NFCIP1 Target mode
*/
typedef pphHal4Nfc_GenCallback_t pphHal4Nfc_SendCallback_t;

/**
* \ingroup grp_mw_external_hal_funcs
*
* Enum type to distinguish between normal init and test mode init
* to be done as part of phHal4Nfc_Open
* In test mode init only minimal initialization of the NFC Device
* sufficient to run the self test is performed.
*
* \note Note: No functional features can be accessed when
* phHal4Nfc_Open is called with TestModeOn
* \ref phHal4Nfc_Open
*
*/
typedef enum{
    eInitDefault = 0x00,     /**<Complete initialization for normal
                                 firmware operation*/
    eInitTestModeOn,         /**<Limited Initialization used for running self
                                tests */
    eInitCustom              /**<Reserved for Future Use */                  
} phHal4Nfc_InitType_t;

/**
* \ingroup grp_mw_external_hal_funcs
*
* Type to select the type of notification registration
* for Tags, P2P and SecureElement and Host Card Emulation events
*
* \if hal
* \ref phHal4Nfc_RegisterNotification,phHal4Nfc_UnregisterNotification
* \endif
*
*/
typedef enum{
    eRegisterDefault = 0x00,    /**<For All other generic notifications
                                     like Host Wakeup Notification */
    eRegisterTagDiscovery,      /**<For Tag Discovery notification*/
    eRegisterP2PDiscovery,      /**<For P2P Discovery notification*/
    eRegisterSecureElement,    /**<For Secure Element notification*/
    eRegisterHostCardEmulation /**<For notification related to Virtual
                                    Card Emulation from host */
} phHal4Nfc_RegisterType_t;

/**
* \ingroup grp_mw_external_hal_funcs
*
* Specifies the Remote Reader type,either initiator or ISO A/B or Felica
*
*/
typedef struct phHal4Nfc_TransactInfo{
    phHal_eRFDevType_t               remotePCDType;
}phHal4Nfc_TransactInfo_t;

/*preliminary definitions end*/

/* -----------------Exported Functions----------------------------------*/
/**
 *  \if hal
 *   \ingroup grp_hal_common
 *  \else
 *   \ingroup grp_mw_external_hal_funcs
 *  \endif
 *
 *  This function initializes and establishes a link to the NFC Device. This is
 *  a asynchronous call as it requires a series of setup calls with the NFC
 *  device. The open is complete when the status response callback <em>
 *   pOpenCallback </em> is called. It uses a Hardware Reference
 *  \ref phHal_sHwReference, allocated by the upper layer and the p_board_driver
 *  member initialized with the dal_instance (handle to the communication driver)
 *  and other members initialized to zero or NULL.
 *
 * \note
 *  - The device is in initialized state after the command has completed
 *    successfully.
 *
 *
 * \param[in,out] psHwReference Hardware Reference, pre-initialized by upper
 *                layer. Members of this structure are made valid if
 *                this function is successful. \n
 *
 * \param[in]     InitType Initialization type, used to differentiate between
 *                test mode limited initialization and normal init.
 *
 * \param[in]     pOpenCallback The open callback function called by the HAL
 *                when open (initialization) sequence is completed or if there
 *                is an error in initialization. \n
 *
 * \param[in]     pContext Upper layer context which will be included in the
 *                call back when request is completed. \n
 *
 * \retval NFCSTATUS_PENDING                 Open sequence has been successfully
 *                                           started and result will be conveyed
 *                                           via the pOpenCallback function.
 * \retval NFCSTATUS_ALREADY_INITIALISED     Device initialization already in
 *                                           progress.
 * \retval NFCSTATUS_INVALID_PARAMETER       The parameter could not be properly
 *                                           interpreted (structure uninitialized?).
 * \retval NFCSTATUS_INSUFFICIENT_RESOURCES  Insufficient resources for
 *                                           completing the request.
 * \retval Others                            Errors related to the lower layers.
 *
 * \if hal
 *  \sa \ref phHal4Nfc_Close,
 * \endif
 */
extern NFCSTATUS phHal4Nfc_Open(
                                phHal_sHwReference_t     *psHwReference,
                                phHal4Nfc_InitType_t      InitType,
                                pphHal4Nfc_GenCallback_t  pOpenCallback,
                                void                     *pContext
                                );



/**
 *  \if hal
 *   \ingroup grp_hal_common
 *  \else
 *   \ingroup grp_mw_external_hal_funcs
 *  \endif
 *
 *  Retrieves the capabilities of the device represented by the Hardware
 *  Reference parameter.The HW, FW versions,model-id and other capability
 *  information are located inside the pDevCapabilities parameter.
 *
 *  \param[in]  psHwReference     Hardware Reference, pre-initialized
 *                                by upper layer. \n
 *  \param[out] psDevCapabilities Pointer to the device capabilities structure
 *                                where all relevant capabilities of the
 *                                peripheral are stored. \n
 *  \param[in]  pContext          Upper layer context which will be included in
 *                                the call back when request is completed. \n
 *
 *  \retval NFCSTATUS_SUCCESS            Success and the psDevCapabilities is
 *                                       updated with info.
 *  \retval NFCSTATUS_INVALID_PARAMETER  One or more of the supplied parameters
 *                                       could not be properly interpreted.
 *  \retval NFCSTATUS_NOT_INITIALISED    Hal is not yet initialized.
 *  \retval Others                       Errors related to the lower layers.
 *
 */
extern NFCSTATUS phHal4Nfc_GetDeviceCapabilities(
                            phHal_sHwReference_t          *psHwReference,
                            phHal_sDeviceCapabilities_t   *psDevCapabilities,
                            void                          *pContext
                            );


/**
*  \if hal
*   \ingroup grp_hal_common
*  \else
*   \ingroup grp_mw_external_hal_funcs
*  \endif
*
*  This function is used to Configure discovery wheel (and start if
*  required) based on the discovery configuration passed.
*  This includes enabling/disabling of the Reader phases (A, B, F),
*  NFCIP1 Initiator Speed and duration of the Emulation phase.
*  Additional optional parameters for each of the features i.e. Reader,
*  Emulation and Peer2Peer can be set using the
* \ref phHal4Nfc_ConfigParameters function
*
*  \param[in] psHwReference         Hardware Reference, pre-initialized by
*                                   upper layer. \n
*
*  \param[in] discoveryMode         Discovery Mode allows to choose between:
*                                   discovery configuration and start, stop
*                                   discovery and start discovery (with last
*                                   set configuration).
*                                   \ref phHal_eDiscoveryConfigMode_t
*   \note Note: Presently only NFC_DISCOVERY_CONFIG is supported, other values
*               are for future use. When in Reader/Initiator mode it mandatory
*               to call phHal4Nfc_Connect before any transaction can be performed
*               with the discovered device.
*
*  \param[in] discoveryCfg          Discovery configuration parameters.
*                                   Reader A/Reader B, Felica 212, Felica 424,
*                                   NFCIP1 Speed, Emulation Enable and Duration.
*
*
*  \param[in] pConfigCallback       This callback has to be called once Hal
*                                   completes the Configuration.
*
*  \param[in] pContext              Upper layer context to be returned in the
*                                   callback.
*
*  \retval NFCSTATUS_INVALID_PARAMETER         Wrong Parameter values.
*
*  \retval NFCSTATUS_NOT_INITIALISED           Hal is not initialized.
*
*  \retval NFCSTATUS_BUSY                      Cannot Configure Hal in
*                                              Current state.
*
*  \retval NFCSTATUS_INSUFFICIENT_RESOURCES    System Resources insufficient.
*
*  \retval NFCSTATUS_PENDING                   Configuration request accepted
*                                              and Configuration is in progress.
*
*  \retval NFCSTATUS_INVALID_PARAMETER         One or more of the supplied
*                                              parameters could not be properly
*                                              interpreted.
*  \retval Others                              Errors related to the lower layers
*
*   \note Note: When in Reader/Initiator mode it mandatory
*               to call phHal4Nfc_Connect before any transaction can be performed
*               with the discovered device. Even if the HAL client is not
*               interested in using any of the discovered phHal4Nfc_Connect and
*               phHal4Nfc_Disconnect should be called to restart the Discovery
*               wheel
*
*  \ref phHal4Nfc_Connect, phHal4Nfc_Disconnect
*
*/
extern NFCSTATUS phHal4Nfc_ConfigureDiscovery(
                        phHal_sHwReference_t          *psHwReference,
                        phHal_eDiscoveryConfigMode_t   discoveryMode,
                        phHal_sADD_Cfg_t               *discoveryCfg,
                        pphHal4Nfc_GenCallback_t       pConfigCallback,
                        void                           *pContext
                        );
/**
*  \if hal
*   \ingroup grp_hal_common
*  \else
*   \ingroup grp_mw_external_hal_funcs
*  \endif
*
*  This function is used to set parameters of various features of the Hal,
*  based on the CfgType parameter. Presently following configuration
*  types are supported :-
*  \n 1. NFC_RF_READER_CONFIG (optional)-> Configure parameters for Reader A
*     or Reader B based on the configuration passed
*  \n 2. NFC_P2P_CONFIG (optional)-> Congfigure P2P parameters like
*     'General bytes', 'PSL Request' etc.
*  \n 3. NFC_EMULATION_CONFIG -> Enable and configure the emulation mode
*     parameters for either NFC Target, SmartMX, UICC and
*  \n   Card Emulation from Host (A, B, F)
*  All the configuration modes can be called independent of each other. The
*  setting will typically take effect for the next cycle of the relevant
*  phase of discovery. For optional configuration internal defaults will be
*  used in case the configuration is not set.
*  \note Card emulation from Host and Card Emulation from UICC are mutually
*  exclusive modes, i.e: only one can be enabled at a time. Using
*  this function to enable one of the emulation modes implicitly disables the
*  the other. eg. Setting Type A (or Type B) Emulation from Host disables
*  card emulation from UICC and vice versa.
*
*  \param[in] psHwReference         Hardware Reference, pre-initialized by
*                                   upper layer. \n
*
*  \param[in] eCfgType              Configuration type which can take one of the
*                                   enum values of \ref phHal_eConfigType_t. Each
*                                   config type is associated with its corresponding
*                                   information which is passed using the uCfg structure.
*
*
*  \param[in] uCfg                  Union containing configuration information,
*                                   which will be interpreted based on eCfgType
*                                   parameter.
*
*
*  \param[in] pConfigCallback       This callback has to be called once Hal
*                                   completes the Configuration.
*
*  \param[in] pContext              Upper layer context to be returned in the
*                                   callback.
*
*  \retval NFCSTATUS_INVALID_PARAMETER         Wrong Parameter values.
*
*  \retval NFCSTATUS_NOT_INITIALISED           Hal is not initialized.
*
*  \retval NFCSTATUS_BUSY                      Cannot Configure Hal in
*                                              Current state.
*
*  \retval NFCSTATUS_INSUFFICIENT_RESOURCES    System Resources insufficient.
*
*  \retval NFCSTATUS_PENDING                   Configuration request accepted
*                                              and Configuration is in progress.
*
*  \retval NFCSTATUS_INVALID_PARAMETER         One or more of the supplied
*                                              parameters could not be properly
*                                              interpreted.
*  \retval Others                              Errors related to the lower layers
*/

extern NFCSTATUS phHal4Nfc_ConfigParameters(
                        phHal_sHwReference_t     *psHwReference,
                        phHal_eConfigType_t       eCfgType,
                        phHal_uConfig_t          *uCfg,
                        pphHal4Nfc_GenCallback_t  pConfigCallback,
                        void                     *pContext
                        );

/**
 *  \if hal
 *   \ingroup grp_hal_nfci
 *  \else
 *   \ingroup grp_mw_external_hal_funcs
 *  \endif
 *
 *  This function is called to connect to a one (out of many if multiple
 *  devices are discovered) already discovered Remote Device notified
 *  through register notification. The  Remote Device Information structure is
 *  already pre-initialized with data (e.g. from Discovery Notificaiton
 *  Callback) A new session is started after the connect function returns
 *  successfully. The session ends with a successful disconnect
 *  (see  \ref phHal4Nfc_Disconnect).
 *
 *  \param[in]     psHwReference        Hardware Reference, pre-initialized by
 *                                      upper layer. \n
 *
 *  \param[in,out] psRemoteDevInfo      Points to the Remote Device Information
 *                                      structure. The members of it can be
 *                                      re-used from a previous session.
 *
 *  \param[in]     pNotifyConnectCb     Upper layer callback to be called for
 *                                      notifying Connect Success/Failure
 *
 *  \param[in]     pContext             Upper layer context to be returned in
 *                                      pNotifyConnectCb.
 *
 *  \retval NFCSTATUS_PENDING                  Request initiated, result will
 *                                             be informed through the callback.
 *  \retval NFCSTATUS_INVALID_PARAMETER        One or more of the supplied
 *                                             parameters could not be
 *                                             properly interpreted.
 *  \retval NFCSTATUS_FAILED                   More than one phHal4Nfc_Connect
 *                                             is not allowed during a session
 *                                             on the same remote device. The
 *                                             session has to be closed before
 *                                             (see\ref phHal4Nfc_Disconnect).
 *  \retval NFCSTATUS_NOT_INITIALIZED          Hal is not initialized.
 *  \retval NFCSTATUS_FEATURE_NOT_SUPPORTED    Reactivation is not supported for 
 *                                             NfcIp target and Jewel/Topaz 
 *                                             remote device types.
 *  \retval NFCSTATUS_INVALID_REMOTE_DEVICE    The Remote Device Identifier is
 *                                             not valid.
 *  \retval Others                             Errors related to the lower layers.
 *
 *  \if hal
 *   \sa \ref phHal4Nfc_Disconnect
 *  \endif
 */
extern NFCSTATUS phHal4Nfc_Connect(
                            phHal_sHwReference_t          *psHwReference,
                            phHal_sRemoteDevInformation_t *psRemoteDevInfo,
                            pphHal4Nfc_ConnectCallback_t   pNotifyConnectCb,
                            void                          *pContext
                            );


/**
 *  \if hal
 *   \ingroup grp_hal_nfci
 *  \else
 *   \ingroup grp_mw_external_hal_funcs
 *  \endif
 *
 *  The phHal4Nfc_Transceive function allows to send data to and receive data
 *  from the Remote Device selected by the caller.It is also used by the
 *  NFCIP1 Initiator while performing a transaction with the NFCIP1 target.
 *  The caller has to provide the Remote Device Information structure and the
 *  command in order to communicate with the selected remote device.For P2P
 *  transactions the command type will not be used.
 *
 *
 *  \note the RecvData should be valid until the pTrcvCallback has been called.
 *
 *
 *  \param[in]      psHwReference       Hardware Reference, pre-initialized by
 *                                      upper layer. \n
 *
 *  \param[in,out]  psTransceiveInfo    Information required by transceive is
 *                                      concealed in this structure.It contains
 *                                      the send,receive buffers and their
 *                                      lengths.
 *
 *  \param[in]      psRemoteDevInfo     Points to the Remote Device Information
 *                                      structure which identifies the selected
 *                                      Remote Device.
 *
 *  \param[in]      pTrcvCallback       Callback function for returning the
 *                                      received response or error.
 *
 *  \param[in]      pContext            Upper layer context to be returned in
 *                                      the callback.
 *
 *  \retval NFCSTATUS_PENDING                Transceive initiated.pTrcvCallback
 *                                           will return the response or error.
 *  \retval NFCSTATUS_NOT_INITIALIZED        Hal is not initialized.
 *  \retval NFCSTATUS_SUCCESS                This status is used when send data
 *                                           length is zero and HAL contains
 *                                           previously more bytes from previous
 *                                           receive. \n
 *  \retval NFCSTATUS_INVALID_PARAMETER      One or more of the supplied
 *                                           parameters could not be properly
 *                                           interpreted or are invalid.
 *  \retval NFCSTATUS_INVALID_DEVICE         The device has not been opened or
 *                                           has been disconnected meanwhile.
 *  \retval NFCSTATUS_FEATURE_NOT_SUPPORTED  Transaction on this Device type is
 *                                           not supported.
 *  \retval NFCSTATUS_BUSY                   Previous transaction is not
 *                                           completed.
 *  \retval NFCSTATUS_INSUFFICIENT_RESOURCES System resources are insufficient
 *                                           to complete the request at that
 *                                           point in time.
 *  \retval NFCSTATUS_MORE_INFORMATION       Received number of bytes is greater
 *                                           than receive buffer provided by the
 *                                           upper layer.Extra bytes will be
 *                                           retained by Hal and returned on next
 *                                           call to transceive.
 *  \retval Others                           Errors related to the lower layers.
 *
 */
extern NFCSTATUS phHal4Nfc_Transceive(
                            phHal_sHwReference_t            *psHwReference,
                            phHal_sTransceiveInfo_t         *psTransceiveInfo,
                            phHal_sRemoteDevInformation_t   *psRemoteDevInfo,
                            pphHal4Nfc_TransceiveCallback_t  pTrcvCallback,
                            void                            *pContext
                            );




/**
 *  \if hal
 *   \ingroup grp_hal_nfci
 *  \else
 *   \ingroup grp_mw_external_hal_funcs
 *  \endif
 *
 *  The function allows to disconnect from a specific Remote Device. This
 *  function closes the session opened with \ref phHal4Nfc_Connect "Connect".It
 *  is also used to switch from wired to virtual mode in case the discovered
 *  device is SmartMX in wired mode. The status of discovery wheel after
 *  disconnection is determined by the ReleaseType parameter.
 *
 *
 *
 *  \param[in]      psHwReference       Hardware Reference, pre-initialized by
 *                                      upper layer. \n
 *  \param[in,out]  psRemoteDevInfo     Points to the valid (connected) Remote
 *                                      Device Information structure.
 *
 *  \param[in]      ReleaseType         Defines various modes of releasing an acquired
 *                                      target or tag
 *
 *  \param[in]      pDscntCallback      Callback function to notify
 *                                      disconnect success/error.
 *
 *  \param[in]      pContext            Upper layer context to be returned in
 *                                      the callback.
 *
 *
 *  \retval NFCSTATUS_PENDING                Disconnect initiated.pDscntCallback
 *                                           will return the response or error.
 *  \retval NFCSTATUS_INVALID_PARAMETER      One or more of the supplied
 *                                           parameters could not be properly
 *                                           interpreted.
 *  \retval NFCSTATUS_INVALID_REMOTE_DEVICE  The device has not been opened
 *                                           before or has already been closed.
 *  \retval NFCSTATUS_NOT_INITIALIZED        Hal is not initialized.
 *  \retval Others                           Errors related to the lower layers.
 *
 *  \if hal
 *   \sa \ref phHal4Nfc_Connect
 *  \endif
 */
extern NFCSTATUS phHal4Nfc_Disconnect(
                            phHal_sHwReference_t          *psHwReference,
                            phHal_sRemoteDevInformation_t *psRemoteDevInfo,
                            phHal_eReleaseType_t           ReleaseType,
                            pphHal4Nfc_DiscntCallback_t    pDscntCallback,
                            void                          *pContext
                            );

/**
*  \if hal
*   \ingroup grp_hal_common
*  \else
*   \ingroup grp_mw_external_hal_funcs
*  \endif
*
*  The function allows to do a one time check on whether the connected target
*  is still present in the field of the Reader. The call back returns the
*  result of the presence check sequence indicating whether it is still present
*  or moved out of the reader field.
*
*  \param[in]     psHwReference     Hardware Reference, pre-initialized by
*                                   upper layer. \n
*
*  \param[in]     pPresenceChkCb    Callback function called on completion of the
*                                   presence check sequence or in case an error
*                                   has occurred..
*
*  \param[in]     context          Upper layer context to be returned in the
*                                   callback.
*
*  \retval NFCSTATUS_PENDING           Call successfully issued to lower layer.
*                                      Status will be returned in pPresenceChkCb.
*
*  \retval NFCSTATUS_NOT_INITIALISED   The device has not been opened or has
*                                      been disconnected meanwhile.
*
*  \retval NFCSTATUS_BUSY              Previous presence check callback has not
*                                      been received
*
*  \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied parameters
*                                      could not be properly interpreted.
*
*  \retval NFCSTATUS_RELEASED          P2P target has been released by Initiator.
*  \retval Others                      Errors related to the lower layers
*
*/
extern NFCSTATUS phHal4Nfc_PresenceCheck(
                                  phHal_sHwReference_t     *psHwReference,
                                  pphHal4Nfc_GenCallback_t  pPresenceChkCb,
                                  void                     *context
                                  );


/**
 *  \if hal
 *   \ingroup grp_hal_common
 *  \else
 *   \ingroup grp_mw_external_hal_funcs
 *  \endif
 *
 *  The I/O Control function allows the caller to use (vendor-) specific
 *  functionality provided by the lower layer or by the hardware. Each feature
 *  is accessible via a specific IOCTL Code and has to be documented by the
 *  provider of the driver and the hardware.
 *  See "IOCTL Codes" for the definition of a standard command set.\n
 *
 *
 *  \param[in]      psHwReference       Hardware Reference, pre-initialized by
 *                                      upper layer. \n
 *  \param[in]      IoctlCode           Control code for the operation.
 *                                      This value identifies the specific
 *                                      operation to be performed and are defined
 *                                      in  \ref phNfcIoctlCode.h
 *
 *  \param[in]      pInParam            Pointer to any input data structure
 *                                      containing data which is interpreted
 *                                      based on Ioctl code and the length of
 *                                      the data.
 *
 *  \param[in]      pOutParam           Pointer to output data structure
 *                                      containing data which is returned as a
 *                                      result of the Ioctl operation and the
 *                                      length of the data.
 *
 *  \param[in]      pIoctlCallback      callback function called in case an
 *                                      error has occurred while performing
 *                                      requested operation,or on successful
 *                                      completion of the request
 *
 *  \param[in]      pContext            Upper layer context to be returned in
 *                                      the callback.
 *
 *  \retval NFCSTATUS_SUCCESS           Success.
 *  \retval NFCSTATUS_PENDING           Call issued to lower layer.Status will
 *                                      be notified in pIoctlCallback.
 *  \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied parameters
 *                                      could not be properly interpreted.
 *  \retval NFCSTATUS_NOT_INITIALIZED   Hal is not initialized.
 *  \retval Others                      Errors related to the lower layers.
 *
 */
extern NFCSTATUS phHal4Nfc_Ioctl(
                                phHal_sHwReference_t       *psHwReference,
                                uint32_t                    IoctlCode,
                                phNfc_sData_t              *pInParam,
                                phNfc_sData_t              *pOutParam,
                                pphHal4Nfc_IoctlCallback_t  pIoctlCallback,
                                void                       *pContext
                                );



/**
 *  \if hal
 *   \ingroup grp_hal_common
 *  \else
 *   \ingroup grp_mw_external_hal_funcs
 *  \endif
 *
 *  Closes the link to the NFC device. All configurations/setups
 *  done until now are invalidated.To restart communication, phHal4Nfc_Open
 *  needs to be called. The pClosecallback is called when all steps
 *  in the close sequence are completed.
 *
 *
 *  \param[in]     psHwReference        Hardware Reference, pre-initialized by
 *                                      upper layer. \n
 *
 *  \param[in]     pCloseCallback       Callback function called on completion of
 *                                      the close sequence or in case an error
 *                                      has occurred..
 *
 *  \param[in]     pContext             Upper layer context to be returned
 *                                      in the callback.
 *
 *  \retval NFCSTATUS_SUCCESS           Closing successful.
 *  \retval NFCSTATUS_NOT_INITIALIZED   The device has not been opened or has
 *                                      been disconnected meanwhile.
 *  \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied parameters
 *                                      could not be properly interpreted.
 *  \retval NFCSTATUS_BUSY              Configuration is in progress.Shutdown
 *                                      is not allowed until configure complete.
 *  \retval Others                      Errors related to the lower layers.
 *
 *  \if hal
 *   \sa \ref phHal4Nfc_Open
 *  \endif
 */
extern NFCSTATUS phHal4Nfc_Close(
                                phHal_sHwReference_t     *psHwReference,
                                pphHal4Nfc_GenCallback_t  pCloseCallback,
                                void                     *pContext
                                );


/**
 *  \if hal
 *   \ingroup grp_hal_common
 *  \else
 *   \ingroup grp_mw_external_hal_funcs
 *  \endif
 *
 *  Forcibly shutdown the HAl.This API makes a call to forcibly shutdown the
 *  lower layer and frees all resources in use by Hal before shutting down.The
 *  API always succeeds.It does not however reset the target.
 *
 *  \param[in]     psHwReference        Hardware Reference, pre-initialized by
 *                                      upper layer. \n
 *
 *  \param[in]     pConfig              Reserved for future use.
 *
 *
 */
extern void phHal4Nfc_Hal4Reset(
                                phHal_sHwReference_t *psHwReference,
                                void                 *pConfig
                                );


/**
*  \if hal
*   \ingroup grp_hal_common
*  \else
*   \ingroup grp_mw_external_hal_funcs
*  \endif
*
*  The function is used by the NFCIP1 Target to respond to packect received
*  from NFCIP1 initiator. pSendCallback()
*  is called , when all steps in the send sequence are completed.
*
*  \param[in]     psHwReference         Hardware Reference, pre-initialized by
*                                       upper layer. \n
*
*  \param[in]     psTransactInfo        information required for transferring
*                                       the data
*
*  \param[in]     sTransferData         Data and the length of the data to be
*                                       transferred
*
*  \param[in]     pSendCallback         Callback function called on completion
*                                       of the NfcIP sequence or in case an
*                                       error has occurred.
*
*  \param[in]     pContext              Upper layer context to be returned in
*                                       the callback.
*
*  \retval NFCSTATUS_PENDING            Send is in progress.
*  \retval NFCSTATUS_INVALID_DEVICE     The device has not been opened or has
*                                       been disconnected meanwhile.
*  \retval NFCSTATUS_INVALID_PARAMETER  One or more of the supplied parameters
*                                       could not be properly interpreted.
*  \retval NFCSTATUS_NOT_INITIALIZED    Hal is not initialized.
*  \retval Others                       Errors related to the lower layers.
*
*
*/
extern
NFCSTATUS
phHal4Nfc_Send(
                phHal_sHwReference_t                    *psHwReference,
                phHal4Nfc_TransactInfo_t                *psTransactInfo,
                phNfc_sData_t                            sTransferData,
                pphHal4Nfc_SendCallback_t                pSendCallback,
                void                                    *pContext
                );

/**
*  \if hal
*   \ingroup grp_hal_common
*  \else
*   \ingroup grp_mw_external_hal_funcs
*  \endif
*
*  This function is called by the NfcIP Peer to wait for receiving data from
*  the other peer.It is used only by the NfcIP Target.
*  \note NOTE: After this function is called, its mandatory to wait for the
*  pphHal4Nfc_ReceiveCallback_t callback, before calling any other function.
*  Only functions allowed are phHal4Nfc_Close() and phHal4Nfc_Hal4Reset().
*
*
*  \param[in]     psHwReference         Hardware Reference, pre-initialized by
*                                       upper layer. \n
*
*  \param[in]     psTransactInfo            information required for transferring the
*                                       data
*
*  \param[in]     pReceiveCallback      Callback function called after receiving
*                                       the data or in case an error has
*                                       has occurred.
*
*  \param[in]     pContext              Upper layer context to be returned
*                                       in the callback.
*
*  \retval NFCSTATUS_PENDING            Receive is in progress.
*  \retval NFCSTATUS_INVALID_DEVICE     The device has not been opened or has
*                                       been disconnected meanwhile.
*  \retval NFCSTATUS_INVALID_PARAMETER  One or more of the supplied parameters
*                                       could not be properly interpreted.
*  \retval NFCSTATUS_NOT_INITIALIZED    Hal is not initialized.
*  \retval Others                       Errors related to the lower layers
*
*/
extern
NFCSTATUS
phHal4Nfc_Receive(
                  phHal_sHwReference_t                  *psHwReference,
                  phHal4Nfc_TransactInfo_t              *psTransactInfo,
                  pphHal4Nfc_ReceiveCallback_t           pReceiveCallback,
                  void                                  *pContext
                 );


/**
*  \if hal
*   \ingroup grp_hal_common
*  \else
*   \ingroup grp_mw_external_hal_funcs
*  \endif
*
*  This API is a synchronous call used to register a listener for either tag
*  discovery, Secure element notification or P2P Notification or a general
*  notification handler for all the three.
*
*
*  \param[in] psHwRef               Hardware Reference, pre-initialized by
*                                   upper layer. \n
*
*  \param[in] eRegisterType         Type of Notification registered.Informs
*                                   whether upper layer is interested in Tag
*                                   Discovery,secure element or P2P notification.
*
*  \param[in] pNotificationHandler  Notification callback.If this parameter is
*                                   NULL,any notification from Hci will be
*                                   ignored and upper layer will not be notified
*                                   of the event.
*
*  \param[in] Context              Upper layer context.
*
*  \retval NFCSTATUS_SUCCESS            Notification unregister successful.
*
*  \retval NFCSTATUS_INVALID_PARAMETER  One or more of the supplied parameters
*                                       could not be properly interpreted.
*  \retval NFCSTATUS_NOT_INITIALIZED    Hal is not initialized.
*
*/
extern NFCSTATUS phHal4Nfc_RegisterNotification(
                            phHal_sHwReference_t      *psHwRef,
                            phHal4Nfc_RegisterType_t   eRegisterType,
                            pphHal4Nfc_Notification_t  pNotificationHandler,
                            void                      *Context
                            );

/**
*  \if hal
*   \ingroup grp_hal_common
*  \else
*   \ingroup grp_mw_external_hal_funcs
*  \endif
*
*  This API is a synchronous call used to unregister a listener for either tag
*  discovery, Secure element notification or P2P Notification, previously
*  registered using \ref phHal4Nfc_RegisterNotification.
*
*  \param[in]   psHwReference           Hardware Reference, pre-initialized by
*                                       upper layer. \n
*
*  \param[in]   eRegisterType           Type of registration ,tells whether upper
*                                       layer is interested in unregistering for
*                                       Tag Discovery,Secure element or P2P. \n
*
*  \param[in]   Context                Upper layer context.
*
*  \retval NFCSTATUS_SUCCESS            Notification unregister successful.
*
*  \retval NFCSTATUS_INVALID_PARAMETER  One or more of the supplied parameters
*                                       could not be properly interpreted.
*
*  \retval NFCSTATUS_NOT_INITIALIZED    Hal is not initialized.
*
*
*/
extern NFCSTATUS phHal4Nfc_UnregisterNotification(
                                    phHal_sHwReference_t     *psHwReference,
                                    phHal4Nfc_RegisterType_t  eRegisterType,
                                    void                     *Context
                                    );


/**
*  \if hal
*   \ingroup grp_hal_common
*  \else
*   \ingroup grp_mw_external_hal_funcs
*  \endif
*
*  This function is called to switch the SmartMX to Wired Mode. After switching
* to Wired mode the SmartMX can be discovered through Tag Discovery like a normal
* tag and used in the same manner as a tag. SmartMx returns to previous mode
* (Virtual or Off) when the tag is relased by phHal4Nfc_Disconnect
*
*
*  \param[in]  psHwReference            Hardware Reference, pre-initialized by
*                                       upper layer. \n
*
*  \param[in]  smx_mode                 Mode to which the switch should be made.
*
*  \param[in]  pSwitchModecb            Callback for Switch mode complete
*                                       with success/error notification.
*
*  \param[in]  pContext                 Upper layer context.
*
*  \retval NFCSTATUS_PENDING                    Switch in progress.Status will be
*                                               returned in pSwitchModecb.
*  \retval NFCSTATUS_INVALID_PARAMETER          One or more of the supplied
*                                               parameters could not be properly
*                                               interpreted.
*  \retval NFCSTATUS_NOT_INITIALIZED            Hal is not initialized.
*  \retval NFCSTATUS_BUSY                       Configuration in Progress or
*                                               remote device is connected.
*  \retval NFCSTATUS_INSUFFICIENT_RESOURCES     System resources are insufficient
*                                               to complete the request at that
*                                               point in time.
* \retval NFCSTATUS_FAILED                      No listener has been registered
*                                               by the upper layer for Emulation
*                                               before making this call.
*  \retval Others                               Errors related to the lower
*                                               layers.
*/
extern NFCSTATUS phHal4Nfc_Switch_SMX_Mode(
                                    phHal_sHwReference_t      *psHwReference,
                                    phHal_eSmartMX_Mode_t      smx_mode,
                                    pphHal4Nfc_GenCallback_t   pSwitchModecb,
                                    void                      *pContext
                                    );


/**
*  \if hal
*   \ingroup grp_hal_common
*  \else
*   \ingroup grp_mw_external_hal_funcs
*  \endif
*
*  This function is called to switch the UICC on or Off. 
*
*
*  \param[in]  psHwReference            Hardware Reference, pre-initialized by 
*                                       upper layer. \n
*
*  \param[in]  smx_mode                 Mode to which the switch should be made. 
*
*  \param[in]  pSwitchModecb            Callback for Switch mode complete
*                                       with success/error notification.
*
*  \param[in]  pContext                 Upper layer context.
*
*  \retval NFCSTATUS_PENDING                    Switch in progress.Status will be
*                                               returned in pSwitchModecb.
*  \retval NFCSTATUS_INVALID_PARAMETER          One or more of the supplied 
*                                               parameters could not be properly
*                                               interpreted.
*  \retval NFCSTATUS_NOT_INITIALIZED            Hal is not initialized.
*  \retval NFCSTATUS_BUSY                       Configuration in Progress or 
*                                               remote device is connected.
*  \retval NFCSTATUS_INSUFFICIENT_RESOURCES     System resources are insufficient
*                                               to complete the request at that
*                                               point in time.
* \retval NFCSTATUS_FAILED                      No listener has been registered 
*                                               by the upper layer for Emulation
*                                               before making this call.
*  \retval Others                               Errors related to the lower 
*                                               layers.
*/
extern NFCSTATUS phHal4Nfc_Switch_Swp_Mode(                                    
                                    phHal_sHwReference_t      *psHwReference,
                                    phHal_eSWP_Mode_t          swp_mode,
                                    pphHal4Nfc_GenCallback_t   pSwitchModecb,
                                    void                      *pContext
                                    );

#endif /* end of PHHAL4NFC_H */