merge with master
[adaptation/devices/nfc-plugin-nxp.git] / src / phFriNfc_SmtCrdFmt.h
1 /*\r
2  * Copyright (C) 2010 NXP Semiconductors\r
3  *\r
4  * Licensed under the Apache License, Version 2.0 (the "License");\r
5  * you may not use this file except in compliance with the License.\r
6  * You may obtain a copy of the License at\r
7  *\r
8  *      http://www.apache.org/licenses/LICENSE-2.0\r
9  *\r
10  * Unless required by applicable law or agreed to in writing, software\r
11  * distributed under the License is distributed on an "AS IS" BASIS,\r
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
13  * See the License for the specific language governing permissions and\r
14  * limitations under the License.\r
15  */\r
16 \r
17 /*!\r
18  * \file  phFriNfc_SmtCrdFmt.h\r
19  * \brief NFC-FRI Smart Card Formatting.\r
20  *\r
21  * Project: NFC-FRI\r
22  *\r
23  * $Date: Mon Dec 13 14:14:11 2010 $\r
24  * $Author: ing02260 $\r
25  * $Revision: 1.5 $\r
26  * $Aliases:  $\r
27  *\r
28  */\r
29 \r
30 #ifndef PHFRINFC_SMTCRDFMT_H\r
31 #define PHFRINFC_SMTCRDFMT_H\r
32 \r
33 /** \r
34  *  \name Smart Card Formatting\r
35  *\r
36  * File: \ref phFri_CardFormatFunctions.h\r
37  *\r
38  */\r
39 /*@{*/\r
40 #define PHFRINFC_SMTCRDFMT_FILEREVISION "$Revision: 1.5 $"\r
41 #define PHFRINFC_SMTCRDFMT_FILEALIASES  "$Aliases:  $"\r
42 /*@}*/\r
43 \r
44 /*! \defgroup grp_fri_smart_card_formatting NFC FRI Smart Card Formatting\r
45  *\r
46  *  Smart Card Formatting functionality enables automatic formatting of any type of smart cards.\r
47  *  This initializes the smart cards and makes them NDEF Compliant.\r
48  *  Single API is provided to handle format/recovery management of different types cards.\r
49  *  Following are different Types of cards supported by this module, currently.\r
50  *      - Type1 ( Topaz)\r
51  *      - Type2 ( Mifare UL)\r
52  *      - Type4 ( Desfire)\r
53  *      - Mifare Std.\r
54  */\r
55 /*@{*/\r
56 /**\r
57  *  \ingroup grp_fri_smart_card_formatting\r
58  *  \brief Macro definitions.\r
59  *  \note \r
60           On requirement basis, new constants will be defined\r
61           during the implementation phase.\r
62 */\r
63 \r
64 #define DESFIRE_FMT_EV1\r
65 \r
66 \r
67 #define PH_FRI_NFC_SMTCRDFMT_NFCSTATUS_FORMAT_ERROR                 9\r
68 #define  PH_FRINFC_SMTCRDFMT_MSTD_DEFAULT_KEYA_OR_KEYB           {0xFF, 0xFF,0xFF,0xFF,0xFF,0xFF}\r
69 #define  PH_FRINFC_SMTCRDFMT_MSTD_MADSECT_KEYA                   {0xA0, 0xA1,0xA2,0xA3,0xA4,0xA5}\r
70 #define  PH_FRINFC_SMTCRDFMT_NFCFORUMSECT_KEYA                   {0xD3, 0xF7,0xD3,0xF7,0xD3,0xF7}\r
71 #define  PH_FRINFC_SMTCRDFMT_MSTD_MADSECT_ACCESSBITS             {0x78,0x77,0x88}\r
72 #define  PH_FRINFC_SMTCRDFMT_MSTD_NFCFORUM_ACCESSBITS            {0x7F,0x07,0x88}\r
73 #define  PH_FRINFC_SMTCRDFMT_MAX_TLV_TYPE_SUPPORTED              1\r
74 \r
75 #define  PH_FRINFC_SMTCRDFMT_MAX_SEND_RECV_BUF_SIZE             252\r
76 \r
77 #define  PH_FRINFC_SMTCRDFMT_STATE_RESET_INIT                   1\r
78 \r
79 enum \r
80 {\r
81     PH_FRINFC_SMTCRDFMT_MIFARE_UL_CARD,\r
82     PH_FRINFC_SMTCRDFMT_ISO14443_4A_CARD,           \r
83     PH_FRINFC_SMTCRDFMT_MFSTD_1K_CRD,         \r
84     PH_FRINFC_SMTCRDFMT_MFSTD_4K_CRD,         \r
85     PH_FRINFC_SMTCRDFMT_TOPAZ_CARD                 \r
86 };\r
87 \r
88 /**\r
89  * \name Completion Routine Indices\r
90  *\r
91  * These are the indices of the completion routine pointers within the component context.\r
92  * Completion routines belong to upper components.\r
93  *\r
94  */\r
95 /*@{*/\r
96 /** \ingroup grp_fri_nfc_ndef_map\r
97 *  Completion Routine Index for \ref phFriNfc_SmtCrd_Format */\r
98 #define PH_FRINFC_SMTCRDFMT_CR_FORMAT     0  /* */ \r
99 /** \ingroup grp_fri_nfc_ndef_map Completion\r
100  *  Routine Index for Unknown States/Operations */\r
101 #define PH_FRINFC_SMTCRDFMT_CR_INVALID_OPE    1  /* */  \r
102 /** \ingroup grp_fri_nfc_ndef_map\r
103  *  Number of completion routines that have to be initialised */\r
104 #define  PH_FRINFC_SMTCRDFMT_CR               2\r
105 /*@}*/\r
106 \r
107 \r
108 /*@}*/\r
109 \r
110 /*\r
111  *  \ingroup grp_fri_smart_card_formatting\r
112  *\r
113  *  \brief NFC Smart Card Formatting Component Type1 Additional Information Structure\r
114  *\r
115  *  This structure is used to specify additional information required to format the Type1 card.\r
116  *  \note \r
117  *           On requirement basis,structure will be filled/modified with other parameters\r
118  *         during the implementation phase.\r
119  *\r
120  */\r
121 typedef struct phFriNfc_Type1_AddInfo\r
122 {\r
123   /* Stores the CC byte values. For Ex: 0xE1, 0x10 , 0x0C, 0x00*/\r
124   uint8_t CCBytes[5];\r
125   uint8_t UID[4];\r
126   uint8_t CCByteIndex;\r
127             \r
128 } phFriNfc_Type1_AddInfo_t;\r
129 \r
130 /*\r
131  *\r
132  *  \ingroup grp_fri_smart_card_formatting\r
133  *  \brief NFC Smart Card Formatting Component Type2 Additional Information Structure\r
134  *\r
135  *  This structure is used to specify additional information required to format the Type2 card.\r
136  *  \note \r
137  *           On requirement basis,structure will be filled/modified with other parametes\r
138  *         during the implementation phase.\r
139  *\r
140  */\r
141 typedef struct phFriNfc_Type2_AddInfo\r
142 {\r
143     /* Stores the CC byte values. For Ex: 0xE1, 0x10 , 0x10, 0x00*/\r
144    uint8_t OTPBytes[4];\r
145 #ifdef FRINFC_READONLY_NDEF\r
146    uint8_t  LockBytes[4];\r
147 \r
148 #ifdef PH_NDEF_MIFARE_ULC\r
149    uint8_t  ReadData[16];\r
150    uint8_t  ReadDataIndex;\r
151    uint8_t  DynLockBytes[4];\r
152    uint8_t  BytesLockedPerLockBit;\r
153    uint8_t  LockBytesPerPage;\r
154    uint8_t  LockByteNumber;\r
155    uint8_t  LockBlockNumber;\r
156    uint8_t  NoOfLockBits;\r
157    uint8_t  DefaultLockBytesFlag;\r
158    uint8_t  LockBitsWritten;\r
159 #endif /* #ifdef PH_NDEF_MIFARE_ULC */\r
160 \r
161 #endif /* #ifdef FRINFC_READONLY_NDEF */\r
162    /* Current Block Address*/\r
163    uint8_t CurrentBlock;\r
164 } phFriNfc_Type2_AddInfo_t;\r
165 \r
166 /*\r
167  *  \ingroup grp_fri_smart_card_formatting\r
168  *  \brief NFC Smart Card Formatting Component Type4 Additional Information Structure\r
169  *\r
170  *  This structure is used to specify additional information required to format the type4 card.\r
171  *  \note \r
172  *          On requirement basis,structure will be filled/modified with other parametes\r
173  *         during the implementation phase.\r
174  *\r
175  */\r
176 \r
177 typedef struct phFriNfc_Type4_AddInfo\r
178 {              \r
179     /* Specifies Keys related to PICC/NFCForum Master Key settings*/\r
180     /* Stores the PICC Master Key/NFC Forum MasterKey*/    \r
181     uint8_t PICCMasterKey[16];\r
182     uint8_t NFCForumMasterkey[16];\r
183 \r
184     /* To create the files follwoiing attributes are required*/\r
185     uint8_t         PrevState;\r
186     uint16_t        FileAccessRights;\r
187     uint32_t        CardSize;\r
188     uint16_t        MajorVersion;\r
189     uint16_t        MinorVersion;\r
190 \r
191 } phFriNfc_Type4_AddInfo_t;\r
192 \r
193 /*\r
194  *  \ingroup grp_fri_smart_card_formatting\r
195  *  \brief NFC Smart Card Formatting Component Mifare Std Additional Information Structure\r
196  *\r
197  *  This structure is used to specify additional information required to format the Mifare Std card.\r
198  *  \note \r
199  *         On requirement basis,structure will be filled/modified with other parametes\r
200  *         during the implementation phase.\r
201  *\r
202  */\r
203  typedef struct phFriNfc_MfStd_AddInfo\r
204 {\r
205     /** Device input parameter for poll and connect after failed authentication */\r
206     phHal_sDevInputParam_t  *DevInputParam;\r
207 \r
208     /* Stores the Default KeyA and KeyB values*/\r
209     uint8_t     Default_KeyA_OR_B[6];\r
210 \r
211     /* Key A of MAD sector*/\r
212     uint8_t     MADSect_KeyA[6];\r
213 \r
214     /* Key A of NFC Forum Sector sector*/\r
215     uint8_t     NFCForumSect_KeyA[6];\r
216 \r
217     /* Access Bits of MAD sector*/\r
218     uint8_t     MADSect_AccessBits[3];\r
219 \r
220     /* Access Bits of NFC Forum sector*/\r
221     uint8_t     NFCForumSect_AccessBits[3];\r
222 \r
223     /* Secret key B to given by the application */\r
224     uint8_t     ScrtKeyB[6];\r
225 \r
226     /* Specifies the status of the different authentication handled in \r
227     formatting procedure*/\r
228     uint8_t     AuthState;\r
229 \r
230     /* Stores the current block */\r
231     uint16_t    CurrentBlock;\r
232 \r
233     /* Stores the current block */\r
234     uint8_t     NoOfDevices;\r
235 \r
236     /* Store the compliant sectors */\r
237     uint8_t     SectCompl[40];\r
238 \r
239     /* Flag to know that MAD sector */\r
240     uint8_t     WrMADBlkFlag;\r
241 \r
242     /* Fill the MAD sector blocks */\r
243     uint8_t     MADSectBlk[80];\r
244 \r
245     /* Fill the MAD sector blocks */\r
246     uint8_t     UpdMADBlk;\r
247 } phFriNfc_MfStd_AddInfo_t;\r
248 \r
249 \r
250  /*\r
251  *  \ingroup grp_fri_smart_card_formatting\r
252  *  \brief NFC Smart Card Formatting Component ISO-15693 Additional Information Structure\r
253  *\r
254  *  This structure is used to specify additional information required to format the ISO-15693 card.\r
255  *  \note \r
256  *         On requirement basis,structure will be filled/modified with other parametes\r
257  *         during the implementation phase.\r
258  *\r
259  */\r
260  typedef struct phFriNfc_ISO15693_AddInfo\r
261  {\r
262     /* Stores the current block executed */\r
263     uint16_t        current_block;\r
264     /* Sequence executed */\r
265     uint8_t         format_seq;\r
266     /* Maximum data size in the card */\r
267     uint16_t        max_data_size;\r
268  }phFriNfc_ISO15693_AddInfo_t;\r
269 \r
270 /**\r
271  *  \ingroup grp_fri_smart_card_formatting\r
272  *\r
273  *  \brief NFC Smart Card Formatting Component Additional Information Structure\r
274  *\r
275  *  This structure is composed to have additional information of different type of tags \r
276  *   Ex: Type1/Type2/Type4/Mifare 1k/4k \r
277  *\r
278  *  \note \r
279  *          On requirement basis, structure will be filled/modified with other parameters\r
280  *         during the implementation phase.\r
281  */\r
282 typedef struct phFriNfc_sNdefSmtCrdFmt_AddInfo\r
283 {\r
284    phFriNfc_Type1_AddInfo_t         Type1Info;\r
285    phFriNfc_Type2_AddInfo_t         Type2Info;\r
286    phFriNfc_Type4_AddInfo_t         Type4Info;\r
287    phFriNfc_MfStd_AddInfo_t         MfStdInfo;\r
288    phFriNfc_ISO15693_AddInfo_t      s_iso15693_info;\r
289 \r
290 }phFriNfc_sNdefSmtCrdFmt_AddInfo_t;\r
291 \r
292 /**\r
293  *  \ingroup grp_fri_smart_card_formatting\r
294  *  \brief NFC Smart Card Formatting Component Context Structure\r
295  *\r
296  *  This structure is used to store the current context information of the instance.\r
297  *\r
298  *  \note  On requirement basis,structure will be filled/modified with other parameters\r
299  *            during the implementation phase \r
300  *\r
301  */\r
302 typedef struct phFriNfc_sNdefSmtCrdFmt\r
303 {\r
304      /** Pointer to the lower (HAL) instance.*/\r
305     void                                *LowerDevice;\r
306     \r
307     /** Holds the device additional informations*/\r
308     phHal_sDepAdditionalInfo_t          psDepAdditionalInfo;\r
309 \r
310     /** Pointer to the Remote Device Information */\r
311     phHal_sRemoteDevInformation_t       *psRemoteDevInfo;\r
312     \r
313     /** Stores the type of the smart card. */\r
314     uint8_t                             CardType;\r
315     \r
316     /** Stores operating mode type of the MifareStd. */\r
317     /* phHal_eOpModes_t                    OpModeType[2]; */\r
318 \r
319      /**< \internal The state of the operation. */\r
320     uint8_t                             State;        \r
321 \r
322     /**< \internal Stores the card state Ex: Blank/Formatted etc. */\r
323     uint8_t                             CardState;    \r
324 \r
325      /**< \internal Completion Routine Context. */\r
326     phFriNfc_CplRt_t                    CompletionRoutine[PH_FRINFC_SMTCRDFMT_CR]; \r
327 \r
328      /**<\internal Holds the completion routine informations of the Smart Card Formatting Layer*/\r
329     phFriNfc_CplRt_t                    SmtCrdFmtCompletionInfo;\r
330 \r
331      /**<\internal Holds the Command Type(read/write)*/\r
332     phHal_uCmdList_t                    Cmd;\r
333 \r
334      /**< \internal Holds the length of the received data. */\r
335     uint16_t                            *SendRecvLength;\r
336 \r
337     /**<\internal Holds the ack of some intial commands*/\r
338     uint8_t                             *SendRecvBuf;\r
339 \r
340       /**< \internal Holds the length of the data to be sent. */\r
341     uint16_t                            SendLength; \r
342 \r
343     /**< \internal Stores the output/result of the format procedure. Ex: Formatted Successfully,\r
344              Format Error etc */\r
345     NFCSTATUS                           FmtProcStatus;    \r
346 \r
347     /** Stores Additional Information needed to format the different types of tags*/\r
348     phFriNfc_sNdefSmtCrdFmt_AddInfo_t   AddInfo;\r
349 \r
350     /*  Stores NDEF message TLV*/\r
351     /* This stores the different TLV messages for the different card types*/\r
352     uint8_t   TLVMsg[PH_FRINFC_SMTCRDFMT_MAX_TLV_TYPE_SUPPORTED][8];\r
353 \r
354            \r
355 } phFriNfc_sNdefSmtCrdFmt_t;\r
356 \r
357 /**\r
358  * \ingroup grp_fri_smart_card_formatting\r
359  * \brief Smart Card Formatting \b Reset function\r
360  *\r
361  * \copydoc page_reg Resets the component instance to the initial state and initializes the \r
362  *          internal variables.\r
363  *\r
364  * \param[in] NdefSmtCrdFmt is a Pointer to a valid and initialized or uninitialised instance\r
365  *            of \ref phFriNfc_sNdefSmtCrdFmt_t .\r
366  * \param[in] LowerDevice Overlapped HAL reference, pointing at a valid instance of this\r
367  *            underlying component.\r
368  * \param[in] psRemoteDevInfo Points to the Remote Device Information structure encapsulating\r
369  *                            the information about the device (Smart card, NFC device) to access.\r
370  * \param[in] psDevInputParam The Device input parameter, as used for the HAL POLL function.\r
371  *                            This parameter is needed by the component in special cases, when an internal call\r
372  *                            to POLL is required again, such as for FeliCa. The storage of the structure behind \r
373  *                            the pointer must be retained by the calling software. The component itself only\r
374  *                            keeps the reference. No change is applied to the structure's content.\r
375  * \param[in] ReceiveBuffer Pointer to a buffer that the component uses internally use to\r
376  *            store the data received from the lower component.\r
377  *            The size shall be at least \ref PH_FRINFC_SMTCRDFMT_MAX_SEND_RECV_BUF_SIZE .\r
378  * \param[in] ReceiveLength The size of ReceiveBuffer. This specifies the actual length \r
379  *            of the data received from the lower component.\r
380  *            The size shall be at least \ref PH_FRINFC_SMTCRDFMT_MAX_SEND_RECV_BUF_SIZE .\r
381  * \r
382  * \retval NFCSTATUS_SUCCESS                Operation successful.\r
383  * \retval NFCSTATUS_INVALID_PARAMETER      At least one parameter of the function is invalid.\r
384  *\r
385  * \note  This function has to be called at the beginning, after creating an instance of\r
386  *        \ref phFriNfc_sNdefSmtCrdFmt_t .  Use this function to reset the instance and/or to switch\r
387  *        to a different underlying card types.\r
388  */\r
389 NFCSTATUS phFriNfc_NdefSmtCrd_Reset(phFriNfc_sNdefSmtCrdFmt_t       *NdefSmtCrdFmt,\r
390                                     void                            *LowerDevice,\r
391                                     phHal_sRemoteDevInformation_t   *psRemoteDevInfo,\r
392                                     phHal_sDevInputParam_t          *psDevInputParam,\r
393                                     uint8_t                         *SendRecvBuffer,\r
394                                     uint16_t                        *SendRecvBuffLen);\r
395                                     \r
396 \r
397 \r
398 /*!\r
399  * \ingroup grp_fri_smart_card_formatting\r
400  *\r
401  * \brief Setting of the Completion Routine.\r
402  *\r
403  * \copydoc page_ovr This function allows the caller to set a Completion Routine (notifier).\r
404  *\r
405  * \param[in] NdefSmtCrdFmt Pointer to a valid instance of the \ref phFriNfc_sNdefSmtCrdFmt_t structure describing\r
406  *                    the component context.\r
407  *\r
408  * \param CompletionRoutine Pointer to a valid completion routine being called when the non-blocking\r
409  *        operation has finished.\r
410  *\r
411  * \param CompletionRoutineParam Pointer to a location with user-defined information that is submitted\r
412  *                               to the Completion Routine once it is called.\r
413 \r
414  * \retval NFCSTATUS_SUCCESS                Operation successful.\r
415  * \retval NFCSTATUS_INVALID_PARAMETER      At least one parameter of the function is invalid.\r
416  *\r
417  */\r
418 NFCSTATUS phFriNfc_NdefSmtCrd_SetCR(phFriNfc_sNdefSmtCrdFmt_t     *NdefSmtCrdFmt,\r
419                                     uint8_t                       FunctionID,\r
420                                     pphFriNfc_Cr_t                CompletionRoutine,\r
421                                     void                          *CompletionRoutineContext);\r
422 \r
423 \r
424 /*!\r
425  * \ingroup grp_fri_smart_card_formatting\r
426  *\r
427  * \brief Initiates the card formatting procedure for Remote Smart Card Type.\r
428  *\r
429  * \copydoc page_ovr  The function initiates and formats the Smart Card.After this formation, remote\r
430  * card would be properly initialized and Ndef Compliant.\r
431  * Depending upon the different card type, this function handles formatting procedure.\r
432  * This function also handles the different recovery procedures for different types of the cards. For both\r
433  * Format and Recovery Management same API is used.\r
434  * \r
435  * \param[in] phFriNfc_sNdefSmtCrdFmt_t Pointer to a valid instance of the \ref phFriNfc_sNdefSmartCardFmt_t\r
436  *                             structure describing the component context.\r
437  * \retval  NFCSTATUS_PENDING   The action has been successfully triggered.\r
438  * \retval  Other values        An error has occurred.\r
439  *\r
440  */\r
441 NFCSTATUS phFriNfc_NdefSmtCrd_Format(phFriNfc_sNdefSmtCrdFmt_t *NdefSmtCrdFmt, const uint8_t *ScrtKeyB);\r
442 \r
443 \r
444 #ifdef FRINFC_READONLY_NDEF\r
445 /*!\r
446  * \ingroup grp_fri_smart_card_formatting\r
447  *\r
448  * \brief Initiates the conversion of the already NDEF formatted tag to READ ONLY.\r
449  *\r
450  * \copydoc page_ovr  The function initiates the conversion of the already NDEF formatted\r
451  * tag to READ ONLY.After this formation, remote card would be properly Ndef Compliant and READ ONLY.\r
452  * Depending upon the different card type, this function handles formatting procedure.\r
453  * This function supports only for the DESFIRE, MIFARE UL and TOPAZ tags.\r
454  *\r
455  * \param[in] phFriNfc_sNdefSmtCrdFmt_t Pointer to a valid instance of the \ref phFriNfc_sNdefSmartCardFmt_t\r
456  *                             structure describing the component context.\r
457  * \retval  NFCSTATUS_PENDING   The action has been successfully triggered.\r
458  * \retval  Other values        An error has occurred.\r
459  *\r
460  */\r
461 NFCSTATUS\r
462 phFriNfc_NdefSmtCrd_ConvertToReadOnly (\r
463     phFriNfc_sNdefSmtCrdFmt_t *NdefSmtCrdFmt);\r
464 \r
465 #endif /* #ifdef FRINFC_READONLY_NDEF */\r
466 \r
467 \r
468 /**\r
469  *\ingroup grp_fri_smart_card_formatting\r
470  *\r
471  * \brief Smart card Formatting \b Completion \b Routine or \b Process function\r
472  *\r
473  * \copydoc page_ovr Completion Routine: This function is called by the lower layer (OVR HAL)\r
474  *                  when an I/O operation has finished. The internal state machine decides\r
475  *                  whether to call into the lower device again or to complete the process\r
476  *                  by calling into the upper layer's completion routine, stored within this\r
477  *                  component's context (\ref phFriNfc_sNdefSmtCrdFmt_t).\r
478  *\r
479  * The function call scheme is according to \ref grp_interact. No State reset is performed during\r
480  * operation.\r
481  *\r
482  * \param[in] Context The context of the current (not the lower/upper) instance, as set by the lower,\r
483  *            calling layer, upon its completion.\r
484  * \param[in] Status  The completion status of the lower layer (to be handled by the implementation of\r
485  *                    the state machine of this function like a regular return value of an internally\r
486  *                    called function).\r
487  *\r
488  * \note For general information about the completion routine interface please see \ref pphFriNfc_Cr_t . * The Different Status Values are as follows\r
489  *\r
490  */\r
491 void phFriNfc_NdefSmtCrd_Process(void        *Context,\r
492                                  NFCSTATUS    Status);\r
493 \r
494 void phFriNfc_SmtCrdFmt_HCrHandler(phFriNfc_sNdefSmtCrdFmt_t  *NdefSmtCrdFmt,\r
495                                    NFCSTATUS            Status);\r
496 \r
497 /*@}*/\r
498 \r
499 #endif /* PHFRINFC_SMTCRDFMT_H */\r
500 \r
501 \r