2 * Copyright (C) 2010 NXP Semiconductors
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
18 * \file phFriNfc_OvrHal.h
19 * \brief Overlapped HAL
22 * Creator: Gerald Kersch
24 * $Date: Tue May 19 10:30:18 2009 $
25 * Changed by: $Author: ing07336 $
27 * $Aliases: NFC_FRI1.1_WK922_PREP1,NFC_FRI1.1_WK920_R25_1,NFC_FRI1.1_WK922_R26_1,NFC_FRI1.1_WK924_PREP1,NFC_FRI1.1_WK924_R27_1,NFC_FRI1.1_WK926_R28_1,NFC_FRI1.1_WK928_R29_1,NFC_FRI1.1_WK930_R30_1,NFC_FRI1.1_WK934_PREP_1,NFC_FRI1.1_WK934_R31_1,NFC_FRI1.1_WK941_PREP1,NFC_FRI1.1_WK941_PREP2,NFC_FRI1.1_WK941_1,NFC_FRI1.1_WK943_R32_1,NFC_FRI1.1_WK949_PREP1,NFC_FRI1.1_WK943_R32_10,NFC_FRI1.1_WK943_R32_13,NFC_FRI1.1_WK943_R32_14,NFC_FRI1.1_WK1007_R33_1,NFC_FRI1.1_WK1007_R33_4,NFC_FRI1.1_WK1017_PREP1,NFC_FRI1.1_WK1017_R34_1,NFC_FRI1.1_WK1017_R34_2,NFC_FRI1.1_WK1023_R35_1 $
31 #ifndef PHFRINFC_OVRHAL_H
32 #define PHFRINFC_OVRHAL_H
36 #include <phHal4Nfc.h>
40 #include <phNfcCompId.h>
41 #include <phNfcStatus.h>
45 * \name Overlapped HAL
47 * File: \ref phFriNfc_OvrHal.h
51 #define PH_FRINFC_OVRHAL_FILEREVISION "$Revision: 1.13 $" /** \ingroup grp_file_attributes */
52 #define PH_FRINFC_OVRHAL_FILEALIASES "$Aliases: NFC_FRI1.1_WK922_PREP1,NFC_FRI1.1_WK920_R25_1,NFC_FRI1.1_WK922_R26_1,NFC_FRI1.1_WK924_PREP1,NFC_FRI1.1_WK924_R27_1,NFC_FRI1.1_WK926_R28_1,NFC_FRI1.1_WK928_R29_1,NFC_FRI1.1_WK930_R30_1,NFC_FRI1.1_WK934_PREP_1,NFC_FRI1.1_WK934_R31_1,NFC_FRI1.1_WK941_PREP1,NFC_FRI1.1_WK941_PREP2,NFC_FRI1.1_WK941_1,NFC_FRI1.1_WK943_R32_1,NFC_FRI1.1_WK949_PREP1,NFC_FRI1.1_WK943_R32_10,NFC_FRI1.1_WK943_R32_13,NFC_FRI1.1_WK943_R32_14,NFC_FRI1.1_WK1007_R33_1,NFC_FRI1.1_WK1007_R33_4,NFC_FRI1.1_WK1017_PREP1,NFC_FRI1.1_WK1017_R34_1,NFC_FRI1.1_WK1017_R34_2,NFC_FRI1.1_WK1023_R35_1 $" /** \ingroup grp_file_attributes */
56 /** \defgroup grp_fri_nfc_ovr_hal Overlapped HAL
58 * This component encapsulates the HAL functions, suited for the NFC-FRI overlapped way of operation. The HAL itself
59 * is used as it is, wrapped by this component. The purpose of the wrapper is to de-couple a blocking I/O, as used by
60 * the HAL, from the overlapped I/O operation mode the FRI is using.
62 * \par Device Based Functions
63 * NFC Device Based Functions are used to address the NFC device (local device) directly.
64 * These are all functions that use no Remote Device Information.
66 * \par Connection Based Functions
67 * Connection Based Functions use the Remote Device Information to describe a connection
68 * to a certain Remote Device.
70 * \par Component Instance Sharing
71 * FRI components accessing one NFC device share one instance of the Overlapped HAL. Therefore
72 * each calling FRI component must specify - together with the call - where to deliver the
73 * response of the overlapped operation.
76 * The Overlapped HAL represents the NFC Device, the lowest layer of the FRI components.
78 * \par Completion Forced
79 * The \b HAL \b functions (and underlying functions) of this library must complete before a new call can
80 * be issued. No HAL operation must be pending.
86 * \name OVR HAL Constants
89 #define PH_FRINFC_OVRHAL_MAX_NUM_MOCKUP_PARAM 255 /**< Number of mockup indices that are are prepared. */
90 /* Harsha: changed from 48 to 128, to work with the Mifare 4k TCs */
91 #define PH_FRINFC_OVRHAL_MAX_NUM_MOCKUP_RDI 4 /**< Max. number of mockup RDIs. */
92 #define PH_FRINFC_OVRHAL_MAX_TEST_DELAY 1000 /**< Max. test delay in OVR HAL. */
93 #define PH_FRINFC_OVRHAL_POLL_PAYLOAD_LEN 5 /**< Length of the POLL payload. */ /* @GK/5.6.06 */
95 /*@}*/ /* defgroup... */
97 /** \defgroup grp_ovr_hal_cmd Overlapped HAL Command List
98 * \ingroup grp_fri_nfc_ovr_hal
99 * These are the command definitions for the Overlapped HAL. They are used internally by the
100 * implementation of the component.
103 #define PH_FRINFC_OVRHAL_NUL (0) /**< \brief We're in NO command */
105 #define PH_FRINFC_OVRHAL_ENU (1) /**< \brief Enumerate */
106 #define PH_FRINFC_OVRHAL_OPE (2) /**< \brief Open */
107 #define PH_FRINFC_OVRHAL_CLO (3) /**< \brief Close */
108 #define PH_FRINFC_OVRHAL_GDC (4) /**< \brief Get Dev Caps */
109 #define PH_FRINFC_OVRHAL_POL (5) /**< \brief Poll */
110 #define PH_FRINFC_OVRHAL_CON (6) /**< \brief Connect */
111 #define PH_FRINFC_OVRHAL_DIS (7) /**< \brief Disconnect */
112 #define PH_FRINFC_OVRHAL_TRX (8) /**< \brief Transceive */
113 #define PH_FRINFC_OVRHAL_STM (9) /**< \brief Start Target Mode */
114 #define PH_FRINFC_OVRHAL_SND (10) /**< \brief Send */
115 #define PH_FRINFC_OVRHAL_RCV (11) /**< \brief Receive */
116 #define PH_FRINFC_OVRHAL_IOC (12) /**< \brief IOCTL */
118 #define PH_FRINFC_OVRHAL_TST (255) /**< \brief OVR HAL test-related command */
120 /** \ingroup grp_fri_nfc_ovr_hal
121 * \brief Post Message Function for Overlapped HAL
125 * This is required by the Overlapped HAL in order to call the blocking (original HAL) in another
126 * thread. This function is required in addition to \ref pphFriNfc_OvrHalPresetParm to be
127 * implemented in the integrating software.
129 * \par First Parameter: Context of the Integration
130 * Set to the value, the Integration has provided when initialising this component.
132 typedef void (*pphFriNfc_OvrHalPostMsg_t)(void*);
134 /** \ingroup grp_fri_nfc_ovr_hal
135 * \brief Abort Function (to be defined/implemented by the Integration)
139 * This is required by the Overlapped HAL in order abort a pending Overlapped HAL operation. This funtion will be
140 * internally called by the \ref phFriNfc_OvrHal_Abort function.
142 * \par First Parameter: Context of the Integration
143 * Set to the value, the Integration has provided when initialising this component.
146 * As defined by the integration
148 typedef NFCSTATUS (*pphFriNfc_OvrHalAbort_t)(void*);
151 typedef void (*pphOvrHal_CB_t) (phHal_sRemoteDevInformation_t *RemoteDevHandle,
153 phNfc_sData_t *pRecvdata,
156 /** \ingroup grp_fri_nfc_ovr_hal
157 * \brief Preset Function to prepare the parameters in the HAL
161 * This function (pointer) is called by the Overlapped HAL to prepare the function call parameters
162 * in the HAL before posting the start message. As we have an asynchronously running FRI, but a
163 * synchronous HAL, the calls need to be "decoupled". This means, the HAL needs to run under
164 * a different time-base (or thread/task etc.). The consequence is that the data exchange between
165 * FRI and HAL must be done as required by the integration/system itself. The declaration
166 * of the function pointer allows for the integrating software to implement whatever functionality
167 * is required to convey the data.
170 * \par First Parameter
171 * Context of the Integration Set to the value, the Integration has provided when initialising
174 * \par Second Parameter:
175 * \b HAL \b Command, as defined in the module \ref grp_ovr_hal_cmd.
177 * \par Third Parameter:
178 * \b Pointers to a specific structure containing the parameters of the HAL functions to be
181 * \par Forth parameter:
182 * Immediate Operation result (not the result of the HAL operation). Usually this is
183 * \ref NFCSTATUS_PENDING (for a successfully triggered HAL I/O or an error value that is
184 * returned by the HAL immediately, such as \ref NFCSTATUS_INVALID_PARAMETER.
187 * A boolean (\ref grp_special_conventions) value. The integration implementation must ensure
188 * that, if the function \b succeeds, the return value is \b TRUE, otherwise false.
190 typedef uint8_t (*pphFriNfc_OvrHalPresetParm)(void*, uint16_t, void*, NFCSTATUS*);
192 /** \ingroup grp_fri_nfc_ovr_hal
193 * \brief Overlapped HAL Context
195 * The Overlapped HAL structure. This structure contains the HAL "context" that
196 * is required by the FRI on a connection basis. Please note that the Overlapped HAL is
197 * a shared component, requiring a special completion notification mechanism.
198 * Read more in the description of this component.
201 typedef struct phFriNfc_OvrHal
203 /** Currently active operation of the component. If no operation is pending, the content of this member is
204 * \ref PH_FRINFC_OVRHAL_NUL . The component refuses a new call if the contenet is different, namely one
205 * of the other values defined in \ref grp_ovr_hal_cmd .
209 /** The \b temporary pointer to the completion routine information. The HAL needs - for each call - to be told about the
210 * completion routine of the upper (calling) component. This major difference to other components is because
211 * some functions of the HAL are connection-based and some are not. Moreover it is because the HAL is shared
212 * among the FRI components. So, with a variety of potential callers it is required for each caller to instruct
213 * the HAL about the "delivery" address of the response for each individual call.
215 phFriNfc_CplRt_t TemporaryCompletionInfo;
216 phFriNfc_CplRt_t TemporaryRcvCompletionInfo;
217 phFriNfc_CplRt_t TemporarySndCompletionInfo;
219 /** Points to a function within the Integration that presets the parameters for the actual
222 pphFriNfc_OvrHalPresetParm Presetparameters;
224 /** Posts a message to the actual HAL integration, starting a NFC HAL I/O with the pre-set
227 pphFriNfc_OvrHalPostMsg_t PostMsg;
229 /** The context of the Integration (the SW around this component). This is needed to let
230 * the Overlapped HAL access the Integration's functionality to post a message to another
233 void *IntegrationContext;
235 /** Device reference returned during enumeration: This has to be filled in by the integrating software after
236 a call to the HAL Enumerate function (not contained in the overlapped HAl API). */
237 phHal_sHwReference_t *psHwReference;
239 /** This flag is set by the ABORT function. The OVR HAL then does no I/O to the real HAL
240 * or to the mockup any more but just completed with the ABORTED status.
242 uint8_t OperationAborted;
244 /** Abort function to be implemented by the integration. This parameter can be (optionally) initialized
245 * via the call of \ref phFriNfc_OvrHal_Reset_Abort function.
246 * If it is not NULL, the function pointed by \ref will be internally called by the \ref phFriNfc_OvrHal_Abort function.
248 pphFriNfc_OvrHalAbort_t AbortIntegrationFunction;
250 /** Integration-defined Context passed as a parameter of the \ref AbortIntegrationFunction.
252 void* AbortIntegrationContext;
256 phHal_sTransceiveInfo_t TranceiveInfo;
260 phNfc_sData_t sReceiveData;
264 phNfc_sData_t sSendData;
268 phHal4Nfc_TransactInfo_t TransactInfo;
270 uint16_t *pndef_recv_length;
274 * \ingroup grp_fri_nfc_ovr_hal
276 * \brief Transceive Data to/from a Remote Device
280 * \param[in] OvrHal Component Context.
281 * \param[in] CompletionInfo \copydoc phFriNfc_OvrHal_t::TemporaryCompletionInfo
282 * \param[in,out] RemoteDevInfo Remote Device Information.
283 * \param[in] Cmd Command to perform.
284 * \param[out] DepAdditionalInfo Protocol Information.
285 * \param[in] SendBuf Pointer to the data to send.
286 * \param[in] SendLength Length, in bytes, of the Send Buffer.
287 * \param[out] RecvBuf Pointer to the buffer that receives the data.
288 * \param[in,out] RecvLength Length, in bytes, of the received data.
290 * \retval NFCSTATUS_PENDING The operation is pending.
291 * \retval NFCSTATUS_INVALID_DEVICE_REQUEST \copydoc phFriNfc_OvrHal_t::Operation
292 * \retval NFCSTATUS_SUCCESS Success.
293 * \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied parameters could not be
294 * properly interpreted.
295 * \retval NFCSTATUS_INVALID_DEVICE The device has not been opened or has been disconnected
297 * \retval NFCSTATUS_CMD_ABORTED The caller/driver has aborted the request.
298 * \retval NFCSTATUS_BUFFER_TOO_SMALL The buffer provided by the caller is too small.
299 * \retval NFCSTATUS_RF_TIMEOUT No data has been received within the TIMEOUT period.
301 * \note Please refer to HAL Transceive for a detailed description of the
302 * underlying function and the propagated parameters.
306 NFCSTATUS phFriNfc_OvrHal_Transceive(phFriNfc_OvrHal_t *OvrHal,
307 phFriNfc_CplRt_t *CompletionInfo,
308 phHal_sRemoteDevInformation_t *RemoteDevInfo,
309 phHal_uCmdList_t Cmd,
310 phHal_sDepAdditionalInfo_t *DepAdditionalInfo,
314 uint16_t *RecvLength);
317 * \ingroup grp_fri_nfc_ovr_hal
322 NFCSTATUS phFriNfc_OvrHal_Receive(phFriNfc_OvrHal_t *OvrHal,
323 phFriNfc_CplRt_t *CompletionInfo,
324 phHal_sRemoteDevInformation_t *RemoteDevInfo,
326 uint16_t *RecvLength);
329 * \ingroup grp_fri_nfc_ovr_hal
334 NFCSTATUS phFriNfc_OvrHal_Send(phFriNfc_OvrHal_t *OvrHal,
335 phFriNfc_CplRt_t *CompletionInfo,
336 phHal_sRemoteDevInformation_t *RemoteDevInfo,
338 uint16_t SendLength);
341 NFCSTATUS phFriNfc_OvrHal_Reconnect(phFriNfc_OvrHal_t *OvrHal,
342 phFriNfc_CplRt_t *CompletionInfo,
343 phHal_sRemoteDevInformation_t *RemoteDevInfo);
346 NFCSTATUS phFriNfc_OvrHal_Connect(phFriNfc_OvrHal_t *OvrHal,
347 phFriNfc_CplRt_t *CompletionInfo,
348 phHal_sRemoteDevInformation_t *RemoteDevInfo,
349 phHal_sDevInputParam_t *DevInputParam);