2 * Copyright (C) 2010 NXP Semiconductors
\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
8 * http://www.apache.org/licenses/LICENSE-2.0
\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
18 * \file phFriNfc_SmtCrdFmt.h
\r
19 * \brief NFC-FRI Smart Card Formatting.
\r
23 * $Date: Mon Dec 13 14:14:11 2010 $
\r
24 * $Author: ing02260 $
\r
30 #ifndef PHFRINFC_SMTCRDFMT_H
\r
31 #define PHFRINFC_SMTCRDFMT_H
\r
34 * \name Smart Card Formatting
\r
36 * File: \ref phFri_CardFormatFunctions.h
\r
40 #define PHFRINFC_SMTCRDFMT_FILEREVISION "$Revision: 1.5 $"
\r
41 #define PHFRINFC_SMTCRDFMT_FILEALIASES "$Aliases: $"
\r
44 /*! \defgroup grp_fri_smart_card_formatting NFC FRI Smart Card Formatting
\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
51 * - Type2 ( Mifare UL)
\r
52 * - Type4 ( Desfire)
\r
57 * \ingroup grp_fri_smart_card_formatting
\r
58 * \brief Macro definitions.
\r
60 On requirement basis, new constants will be defined
\r
61 during the implementation phase.
\r
64 #define DESFIRE_FMT_EV1
\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
75 #define PH_FRINFC_SMTCRDFMT_MAX_SEND_RECV_BUF_SIZE 252
\r
77 #define PH_FRINFC_SMTCRDFMT_STATE_RESET_INIT 1
\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
89 * \name Completion Routine Indices
\r
91 * These are the indices of the completion routine pointers within the component context.
\r
92 * Completion routines belong to upper components.
\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
111 * \ingroup grp_fri_smart_card_formatting
\r
113 * \brief NFC Smart Card Formatting Component Type1 Additional Information Structure
\r
115 * This structure is used to specify additional information required to format the Type1 card.
\r
117 * On requirement basis,structure will be filled/modified with other parameters
\r
118 * during the implementation phase.
\r
121 typedef struct phFriNfc_Type1_AddInfo
\r
123 /* Stores the CC byte values. For Ex: 0xE1, 0x10 , 0x0C, 0x00*/
\r
124 uint8_t CCBytes[5];
\r
126 uint8_t CCByteIndex;
\r
128 } phFriNfc_Type1_AddInfo_t;
\r
132 * \ingroup grp_fri_smart_card_formatting
\r
133 * \brief NFC Smart Card Formatting Component Type2 Additional Information Structure
\r
135 * This structure is used to specify additional information required to format the Type2 card.
\r
137 * On requirement basis,structure will be filled/modified with other parametes
\r
138 * during the implementation phase.
\r
141 typedef struct phFriNfc_Type2_AddInfo
\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
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
161 #endif /* #ifdef FRINFC_READONLY_NDEF */
\r
162 /* Current Block Address*/
\r
163 uint8_t CurrentBlock;
\r
164 } phFriNfc_Type2_AddInfo_t;
\r
167 * \ingroup grp_fri_smart_card_formatting
\r
168 * \brief NFC Smart Card Formatting Component Type4 Additional Information Structure
\r
170 * This structure is used to specify additional information required to format the type4 card.
\r
172 * On requirement basis,structure will be filled/modified with other parametes
\r
173 * during the implementation phase.
\r
177 typedef struct phFriNfc_Type4_AddInfo
\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
184 /* To create the files follwoiing attributes are required*/
\r
186 uint16_t FileAccessRights;
\r
188 uint16_t MajorVersion;
\r
189 uint16_t MinorVersion;
\r
191 } phFriNfc_Type4_AddInfo_t;
\r
194 * \ingroup grp_fri_smart_card_formatting
\r
195 * \brief NFC Smart Card Formatting Component Mifare Std Additional Information Structure
\r
197 * This structure is used to specify additional information required to format the Mifare Std card.
\r
199 * On requirement basis,structure will be filled/modified with other parametes
\r
200 * during the implementation phase.
\r
203 typedef struct phFriNfc_MfStd_AddInfo
\r
205 /** Device input parameter for poll and connect after failed authentication */
\r
206 phHal_sDevInputParam_t *DevInputParam;
\r
208 /* Stores the Default KeyA and KeyB values*/
\r
209 uint8_t Default_KeyA_OR_B[6];
\r
211 /* Key A of MAD sector*/
\r
212 uint8_t MADSect_KeyA[6];
\r
214 /* Key A of NFC Forum Sector sector*/
\r
215 uint8_t NFCForumSect_KeyA[6];
\r
217 /* Access Bits of MAD sector*/
\r
218 uint8_t MADSect_AccessBits[3];
\r
220 /* Access Bits of NFC Forum sector*/
\r
221 uint8_t NFCForumSect_AccessBits[3];
\r
223 /* Secret key B to given by the application */
\r
224 uint8_t ScrtKeyB[6];
\r
226 /* Specifies the status of the different authentication handled in
\r
227 formatting procedure*/
\r
230 /* Stores the current block */
\r
231 uint16_t CurrentBlock;
\r
233 /* Stores the current block */
\r
234 uint8_t NoOfDevices;
\r
236 /* Store the compliant sectors */
\r
237 uint8_t SectCompl[40];
\r
239 /* Flag to know that MAD sector */
\r
240 uint8_t WrMADBlkFlag;
\r
242 /* Fill the MAD sector blocks */
\r
243 uint8_t MADSectBlk[80];
\r
245 /* Fill the MAD sector blocks */
\r
247 } phFriNfc_MfStd_AddInfo_t;
\r
251 * \ingroup grp_fri_smart_card_formatting
\r
252 * \brief NFC Smart Card Formatting Component ISO-15693 Additional Information Structure
\r
254 * This structure is used to specify additional information required to format the ISO-15693 card.
\r
256 * On requirement basis,structure will be filled/modified with other parametes
\r
257 * during the implementation phase.
\r
260 typedef struct phFriNfc_ISO15693_AddInfo
\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
271 * \ingroup grp_fri_smart_card_formatting
\r
273 * \brief NFC Smart Card Formatting Component Additional Information Structure
\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
279 * On requirement basis, structure will be filled/modified with other parameters
\r
280 * during the implementation phase.
\r
282 typedef struct phFriNfc_sNdefSmtCrdFmt_AddInfo
\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
290 }phFriNfc_sNdefSmtCrdFmt_AddInfo_t;
\r
293 * \ingroup grp_fri_smart_card_formatting
\r
294 * \brief NFC Smart Card Formatting Component Context Structure
\r
296 * This structure is used to store the current context information of the instance.
\r
298 * \note On requirement basis,structure will be filled/modified with other parameters
\r
299 * during the implementation phase
\r
302 typedef struct phFriNfc_sNdefSmtCrdFmt
\r
304 /** Pointer to the lower (HAL) instance.*/
\r
307 /** Holds the device additional informations*/
\r
308 phHal_sDepAdditionalInfo_t psDepAdditionalInfo;
\r
310 /** Pointer to the Remote Device Information */
\r
311 phHal_sRemoteDevInformation_t *psRemoteDevInfo;
\r
313 /** Stores the type of the smart card. */
\r
316 /** Stores operating mode type of the MifareStd. */
\r
317 /* phHal_eOpModes_t OpModeType[2]; */
\r
319 /**< \internal The state of the operation. */
\r
322 /**< \internal Stores the card state Ex: Blank/Formatted etc. */
\r
323 uint8_t CardState;
\r
325 /**< \internal Completion Routine Context. */
\r
326 phFriNfc_CplRt_t CompletionRoutine[PH_FRINFC_SMTCRDFMT_CR];
\r
328 /**<\internal Holds the completion routine informations of the Smart Card Formatting Layer*/
\r
329 phFriNfc_CplRt_t SmtCrdFmtCompletionInfo;
\r
331 /**<\internal Holds the Command Type(read/write)*/
\r
332 phHal_uCmdList_t Cmd;
\r
334 /**< \internal Holds the length of the received data. */
\r
335 uint16_t *SendRecvLength;
\r
337 /**<\internal Holds the ack of some intial commands*/
\r
338 uint8_t *SendRecvBuf;
\r
340 /**< \internal Holds the length of the data to be sent. */
\r
341 uint16_t SendLength;
\r
343 /**< \internal Stores the output/result of the format procedure. Ex: Formatted Successfully,
\r
344 Format Error etc */
\r
345 NFCSTATUS FmtProcStatus;
\r
347 /** Stores Additional Information needed to format the different types of tags*/
\r
348 phFriNfc_sNdefSmtCrdFmt_AddInfo_t AddInfo;
\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
355 } phFriNfc_sNdefSmtCrdFmt_t;
\r
358 * \ingroup grp_fri_smart_card_formatting
\r
359 * \brief Smart Card Formatting \b Reset function
\r
361 * \copydoc page_reg Resets the component instance to the initial state and initializes the
\r
362 * internal variables.
\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
382 * \retval NFCSTATUS_SUCCESS Operation successful.
\r
383 * \retval NFCSTATUS_INVALID_PARAMETER At least one parameter of the function is invalid.
\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
389 NFCSTATUS phFriNfc_NdefSmtCrd_Reset(phFriNfc_sNdefSmtCrdFmt_t *NdefSmtCrdFmt,
\r
391 phHal_sRemoteDevInformation_t *psRemoteDevInfo,
\r
392 phHal_sDevInputParam_t *psDevInputParam,
\r
393 uint8_t *SendRecvBuffer,
\r
394 uint16_t *SendRecvBuffLen);
\r
399 * \ingroup grp_fri_smart_card_formatting
\r
401 * \brief Setting of the Completion Routine.
\r
403 * \copydoc page_ovr This function allows the caller to set a Completion Routine (notifier).
\r
405 * \param[in] NdefSmtCrdFmt Pointer to a valid instance of the \ref phFriNfc_sNdefSmtCrdFmt_t structure describing
\r
406 * the component context.
\r
408 * \param CompletionRoutine Pointer to a valid completion routine being called when the non-blocking
\r
409 * operation has finished.
\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
414 * \retval NFCSTATUS_SUCCESS Operation successful.
\r
415 * \retval NFCSTATUS_INVALID_PARAMETER At least one parameter of the function is invalid.
\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
425 * \ingroup grp_fri_smart_card_formatting
\r
427 * \brief Initiates the card formatting procedure for Remote Smart Card Type.
\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
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
441 NFCSTATUS phFriNfc_NdefSmtCrd_Format(phFriNfc_sNdefSmtCrdFmt_t *NdefSmtCrdFmt, const uint8_t *ScrtKeyB);
\r
444 #ifdef FRINFC_READONLY_NDEF
\r
446 * \ingroup grp_fri_smart_card_formatting
\r
448 * \brief Initiates the conversion of the already NDEF formatted tag to READ ONLY.
\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
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
462 phFriNfc_NdefSmtCrd_ConvertToReadOnly (
\r
463 phFriNfc_sNdefSmtCrdFmt_t *NdefSmtCrdFmt);
\r
465 #endif /* #ifdef FRINFC_READONLY_NDEF */
\r
469 *\ingroup grp_fri_smart_card_formatting
\r
471 * \brief Smart card Formatting \b Completion \b Routine or \b Process function
\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
479 * The function call scheme is according to \ref grp_interact. No State reset is performed during
\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
488 * \note For general information about the completion routine interface please see \ref pphFriNfc_Cr_t . * The Different Status Values are as follows
\r
491 void phFriNfc_NdefSmtCrd_Process(void *Context,
\r
494 void phFriNfc_SmtCrdFmt_HCrHandler(phFriNfc_sNdefSmtCrdFmt_t *NdefSmtCrdFmt,
\r
499 #endif /* PHFRINFC_SMTCRDFMT_H */
\r