• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Copyright (C) 2010 NXP Semiconductors
3  *
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
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
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.
15  */
16 
17 /**
18  * \file  phFriNfc_OvrHal.h
19  * \brief Overlapped HAL
20  *
21  * Project: NFC-FRI
22  * Creator: Gerald Kersch
23  *
24  * $Date: Tue May 19 10:30:18 2009 $
25  * Changed by: $Author: ing07336 $
26  * $Revision: 1.13 $
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 $
28  *
29  */
30 
31 #ifndef PHFRINFC_OVRHAL_H
32 #define PHFRINFC_OVRHAL_H
33 
34 #include <phFriNfc.h>
35 #ifdef PH_HAL4_ENABLE
36 #include <phHal4Nfc.h>
37 #else
38 #include <phHalNfc.h>
39 #endif
40 #include <phNfcCompId.h>
41 #include <phNfcStatus.h>
42 
43 
44 /**
45  *  \name Overlapped HAL
46  *
47  * File: \ref phFriNfc_OvrHal.h
48  *
49  */
50 /*@{*/
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 */
53 /*@}*/
54 
55 
56 /** \defgroup grp_fri_nfc_ovr_hal Overlapped HAL
57  *
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.
61  *
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.
65  *
66  *  \par Connection Based Functions
67  *  Connection Based Functions use the Remote Device Information to describe a connection
68  *  to a certain Remote Device.
69  *
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.
74  *
75  *  \par Lowest Layer
76  *  The Overlapped HAL represents the NFC Device, the lowest layer of the FRI components.
77  *
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.
81  *
82  */
83 /*@{*/
84 
85 /**
86  *  \name OVR HAL Constants
87  */
88 /*@{*/
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 */
94 /*@}*/
95 /*@}*/ /* defgroup... */
96 
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.
101  */
102 /*@{*/
103 #define PH_FRINFC_OVRHAL_NUL             (0)     /**< \brief We're in NO command */
104 
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 */
117 
118 #define PH_FRINFC_OVRHAL_TST             (255)   /**< \brief OVR HAL test-related command */
119 
120 /** \ingroup grp_fri_nfc_ovr_hal
121  *  \brief Post Message Function for Overlapped HAL
122  *
123  *  \copydoc page_reg
124  *
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.
128  *
129  * \par First Parameter: Context of the Integration
130  *      Set to the value, the Integration has provided when initialising this component.
131  */
132 typedef void (*pphFriNfc_OvrHalPostMsg_t)(void*);
133 
134 /** \ingroup grp_fri_nfc_ovr_hal
135  *  \brief Abort Function (to be defined/implemented by the Integration)
136  *
137  *  \copydoc page_reg
138  *
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.
141  *
142  * \par First Parameter: Context of the Integration
143  *      Set to the value, the Integration has provided when initialising this component.
144  *
145  * \par Return value:
146  *      As defined by the integration
147  */
148 typedef NFCSTATUS (*pphFriNfc_OvrHalAbort_t)(void*);
149 
150 
151 typedef void (*pphOvrHal_CB_t) (phHal_sRemoteDevInformation_t *RemoteDevHandle,
152                                 NFCSTATUS status,
153                                 phNfc_sData_t  *pRecvdata,
154                                 void *context);
155 
156 /** \ingroup grp_fri_nfc_ovr_hal
157  *  \brief Preset Function to prepare the parameters in the HAL
158  *
159  *  \copydoc page_reg
160  *
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.
168  *
169  *
170  * \par First Parameter
171  *      Context of the Integration Set to the value, the Integration has provided when initialising
172  *      this component.
173  *
174  * \par Second Parameter:
175  *      \b HAL \b Command, as defined in the module \ref grp_ovr_hal_cmd.
176  *
177  * \par Third Parameter:
178  *      \b Pointers to a specific structure containing the parameters of the HAL functions to be
179  *      called.
180  *
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.
185  *
186  * \par Return value:
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.
189  */
190 typedef uint8_t (*pphFriNfc_OvrHalPresetParm)(void*, uint16_t, void*, NFCSTATUS*);
191 
192 /** \ingroup grp_fri_nfc_ovr_hal
193  *  \brief Overlapped HAL Context
194  *
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.
199  *
200  */
201 typedef struct phFriNfc_OvrHal
202 {
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 .
206      */
207     uint8_t                         Operation;
208 
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.
214      */
215     phFriNfc_CplRt_t                TemporaryCompletionInfo;
216     phFriNfc_CplRt_t                TemporaryRcvCompletionInfo;
217     phFriNfc_CplRt_t                TemporarySndCompletionInfo;
218 
219     /** Points to a function within the Integration that presets the parameters for the actual
220      *  HAL call.
221      */
222     pphFriNfc_OvrHalPresetParm      Presetparameters;
223 
224     /** Posts a message to the actual HAL integration, starting a  NFC HAL I/O with the pre-set
225      *  parameters.
226      */
227     pphFriNfc_OvrHalPostMsg_t       PostMsg;
228 
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
231      *  thread.
232      */
233     void                           *IntegrationContext;
234 
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;
238 
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.
241      */
242     uint8_t OperationAborted;
243 
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.
247      */
248     pphFriNfc_OvrHalAbort_t      AbortIntegrationFunction;
249 
250     /** Integration-defined Context passed as a parameter of the \ref AbortIntegrationFunction.
251      */
252     void*                        AbortIntegrationContext;
253 
254     void*                        OvrCompletion;
255 
256     phHal_sTransceiveInfo_t      TranceiveInfo;
257 
258     /** TODO
259      */
260     phNfc_sData_t                sReceiveData;
261 
262     /** TODO
263      */
264     phNfc_sData_t                sSendData;
265 
266     /** TODO
267      */
268     phHal4Nfc_TransactInfo_t     TransactInfo;
269 
270     uint16_t                     *pndef_recv_length;
271 } phFriNfc_OvrHal_t;
272 
273 /**
274  * \ingroup grp_fri_nfc_ovr_hal
275  *
276  * \brief Transceive Data to/from a Remote Device
277  *
278  * \copydoc page_ovr
279  *
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.
289  *
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
296  *                                          meanwhile.
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.
300  *
301  * \note Please refer to HAL Transceive for a detailed description of the
302  *       underlying function and the propagated parameters.
303  *
304  */
305 
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,
311                                      uint8_t                        *SendBuf,
312                                      uint16_t                        SendLength,
313                                      uint8_t                        *RecvBuf,
314                                      uint16_t                       *RecvLength);
315 
316 /**
317  * \ingroup grp_fri_nfc_ovr_hal
318  *
319  * \brief TODO
320  *
321  */
322 NFCSTATUS phFriNfc_OvrHal_Receive(phFriNfc_OvrHal_t              *OvrHal,
323                                   phFriNfc_CplRt_t               *CompletionInfo,
324                                   phHal_sRemoteDevInformation_t  *RemoteDevInfo,
325                                   uint8_t                        *RecvBuf,
326                                   uint16_t                       *RecvLength);
327 
328 /**
329  * \ingroup grp_fri_nfc_ovr_hal
330  *
331  * \brief TODO
332  *
333  */
334 NFCSTATUS phFriNfc_OvrHal_Send(phFriNfc_OvrHal_t              *OvrHal,
335                                phFriNfc_CplRt_t               *CompletionInfo,
336                                phHal_sRemoteDevInformation_t  *RemoteDevInfo,
337                                uint8_t                        *SendBuf,
338                                uint16_t                       SendLength);
339 
340 
341 NFCSTATUS phFriNfc_OvrHal_Reconnect(phFriNfc_OvrHal_t              *OvrHal,
342                                     phFriNfc_CplRt_t               *CompletionInfo,
343                                     phHal_sRemoteDevInformation_t  *RemoteDevInfo);
344 
345 
346 NFCSTATUS phFriNfc_OvrHal_Connect(phFriNfc_OvrHal_t              *OvrHal,
347                                   phFriNfc_CplRt_t               *CompletionInfo,
348                                   phHal_sRemoteDevInformation_t  *RemoteDevInfo,
349                                   phHal_sDevInputParam_t         *DevInputParam);
350 
351 #endif
352