src/phDal4Nfc.h

   1 /*\r
   2  * Copyright (C) 2010 NXP Semiconductors
   3  * Copyright (C) 2012 Samsung Elevtronics Co., Ltd\r
   4  *\r
   5  * Licensed under the Apache License, Version 2.0 (the "License");\r
   6  * you may not use this file except in compliance with the License.\r
   7  * You may obtain a copy of the License at\r
   8  *\r
   9  *      http://www.apache.org/licenses/LICENSE-2.0\r
  10  *\r
  11  * Unless required by applicable law or agreed to in writing, software\r
  12  * distributed under the License is distributed on an "AS IS" BASIS,\r
  13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
  14  * See the License for the specific language governing permissions and\r
  15  * limitations under the License.\r
  16  */\r
  17 \r
  18 \r
  19 /*!\r
  20 \r
  21 * \file  phDal4Nfc.h\r
  22 * \brief Common DAL for the upper layer.\r
  23 *\r
  24 * Project: NFC-FRI-1.1\r
  25 *\r
  26 * $Date: Tue Nov 10 13:56:45 2009 $\r
  27 * $Author: ing07299 $\r
  28 * $Revision: 1.38 $\r
  29 * $Aliases: 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 $\r
  30 *\r
  31 */\r
  32 \r
  33 #ifndef PHDAL4NFC_H\r
  34 #define PHDAL4NFC_H\r
  35 \r
  36 /**\r
  37 *  \name DAl4 NFC\r
  38 *\r
  39 * File: \ref phDal4Nfc.h\r
  40 *\r
  41 */\r
  42 /*@{*/\r
  43 #define PH_DAL4NFC_FILEREVISION "$Revision: 1.38 $" /**< \ingroup grp_file_attributes */\r
  44 #define PH_DAL4NFC_FILEALIASES    "$Aliases: 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 $"\r
  45  /**< \ingroup grp_file_attributes */\r
  46 /*@}*/\r
  47 /*************************** Includes *******************************/\r
  48 /** \defgroup grp_nfc_dal DAL Component\r
  49  *\r
  50  *\r
  51  *\r
  52  */\r
  53 \r
  54 /* Constant : samsung modify for TIZEN */\r
  55 //#include <hardware/nfc.h>\r
  56 /**< Basic type definitions */\r
  57 #include <phNfcTypes.h>\r
  58 /**< Generic Interface Layer Function Definitions */\r
  59 #include <phNfcInterface.h>\r
  60 /*********************** End of includes ****************************/\r
  61 \r
  62 /***************************** Macros *******************************/\r
  63  /**< Used for messaging by DAL as well as Upper Layers */\r
  64 #define PH_DAL4NFC_MESSAGE_BASE  PH_LIBNFC_DEFERREDCALL_MSG\r
  65 \r
  66 /************************ End of macros *****************************/\r
  67 \r
  68 \r
  69 /********************* Structures and enums *************************/\r
  70 \r
  71 /**\r
  72  * \ingroup grp_nfc_dal\r
  73  *\r
  74  * DAL context : This contains the information of the upper layer callback\r
  75  * and hardware reference.\r
  76  */\r
  77 typedef struct phDal4Nfc_SContext\r
  78 {\r
  79         phNfcIF_sCallBack_t             cb_if;          /**<Callback info registered by upper layer*/\r
  80         volatile uint8_t                hw_valid;       /**<Flag - shows Hardware present or not */\r
  81         void                                    *pHwRef;        /**<Hardware Reference*/\r
  82 }phDal4Nfc_SContext_t,*pphDal4Nfc_SContext_t;\r
  83 \r
  84 /**\r
  85  * \ingroup grp_nfc_dal\r
  86  *\r
  87  * DAL enum for Messages : This contains the enums used for\r
  88  * posting messages to the application.\r
  89  */\r
  90 typedef enum phDal4Nfc_Messages_en\r
  91 {\r
  92     /**<Read message type used to post Read DAL Message to dispatch routine.Dispatch routine\r
  93         calls read callback registered by upper layer */\r
  94     PHDAL4NFC_READ_MESSAGE = 0,\r
  95     /**<Readwait message type used to post Read wait DAL Message to dispatch routine.Dispatch routine\r
  96         calls read wait callback registered by upper layer */\r
  97         PHDAL4NFC_READWAIT_MESSAGE,\r
  98         /**<Write message type used to post write DAL Message to dispatch routine.Dispatch routine\r
  99         calls write wait callback registered by upper layer */\r
 100     PHDAL4NFC_WRITE_MESSAGE,\r
 101         /**<Notify message type used to post Notify DAL Message to dispatch routine.Dispatch routine\r
 102         calls notify callback registered by upper layer */\r
 103     PHDAL4NFC_NOTIFY_MESSAGE\r
 104 }phDal4Nfc_Messages_en_t;\r
 105 \r
 106 /**\r
 107  * \ingroup grp_nfc_dal\r
 108  *\r
 109  * \brief DAL Message structure definition.This structure contains\r
 110  *\r
 111  * This structure contains details like  message type,read ,read wait and write callbacks\r
 112  * reference details as registered by upper layer.\r
 113  */\r
 114 typedef struct phDal4Nfc_Message\r
 115 {\r
 116     /**<Refenrece to context.Context can be DAL context  */\r
 117         void                                *pContext;\r
 118     /**<Reference to hardware reference strucutre */\r
 119         void                                *pHwRef;\r
 120         /**<DAL message of type \ref phDal4Nfc_Messages_en_t*/\r
 121     phDal4Nfc_Messages_en_t             eMsgType;\r
 122         /**<Transaction specific information of type \ref phNfc_sTransactionInfo_t*/\r
 123     phNfc_sTransactionInfo_t            transactInfo;\r
 124         /**<Reference to read callback,registered by upper layer.This is of type \ref pphNfcIF_Transact_Completion_CB_t*/\r
 125     pphNfcIF_Transact_Completion_CB_t   readCbPtr;\r
 126         /**<Reference to write callback ,registered by upper layer.This is of type \ref pphNfcIF_Transact_Completion_CB_t*/\r
 127     pphNfcIF_Transact_Completion_CB_t   writeCbPtr;\r
 128 } phDal4Nfc_Message_t,*pphDal4Nfc_Message_t;\r
 129 \r
 130 typedef phLibNfc_sConfig_t phDal4Nfc_sConfig_t;\r
 131 typedef phLibNfc_sConfig_t *pphDal4Nfc_sConfig_t;\r
 132 \r
 133 /****************** End of structures and enums *********************/\r
 134 \r
 135 /******************** Function declarations *************************/\r
 136 \r
 137 /**\r
 138  * \ingroup grp_nfc_dal\r
 139  *\r
 140  *\brief Allows to register upper layer with DAL layer.\r
 141  * This API allows upper layer to register with DAL layer.As part of registration\r
 142  *<br>1.Exports DAL interfaces and DAL layer context to upper layer.\r
 143  *Exported DAL interfaces are :\r
 144  *<br><br>.phDal4Nfc_Shutdown\r
 145  *<br><br>.phDal4Nfc_Write\r
 146  *<br><br>.phDal4Nfc_Read\r
 147  *<br><br>.phDal4Nfc_ReadWait\r
 148  *<br><br>.phDal4Nfc_ReadWaitCancel\r
 149  *<br><br>phDal4Nfc_Unregister\r
 150  *<br><br>.Registeres upper layer callbacks and upper layer context with DAL layer.\r
 151  *For details refer to \ref phNfcIF_sReference_t.\r
 152  *Registration details are valid unless upper layer calls \ref phDal4Nfc_Unregister()\r
 153  or \ref phDal4Nfc_Shutdown called.\r
 154 \r
 155  * \param[in,out] psRefer   holds  DAL exported interface references once registration\r
 156  *                                                      sucessful.This also contains transmit and receive buffer\r
 157  *                                                      references.\r
 158  *\r
 159  * \param[in]     if_cb         Contains upper layer callback reference details, which are used\r
 160  *                                                      by DAL layer during callback notification.\r
 161  *                                                      These callbacks gets registered with DAL layer.\r
 162  *\r
 163 \r
 164  * \param[out]   psIFConf  Currently this parameter not used.This  parameter to be other than NULL.\r
 165  *\r
 166  *\r
 167  * \retval NFCSTATUS_SUCCESS             Operation is successful.\r
 168  * \retval NFCSTATUS_INVALID_PARAMETER   At least one parameter of the function is invalid.\r
 169  *\r
 170  *\msc\r
 171  *ClientApp,UpperLayer,phDal4Nfc;\r
 172  *ClientApp=>phDal4Nfc [label="phDal4Nfc_Config()",URL="\ref phDal4Nfc_Config"];\r
 173  *ClientApp<<phDal4Nfc [label="NFCSTATUS_SUCCESS"];\r
 174  *UpperLayer=>phDal4Nfc [label="phDal4Nfc_Register()",URL="\ref phDal4Nfc_Register"];\r
 175  *UpperLayer<<phDal4Nfc [label="NFCSTATUS_SUCCESS"];\r
 176  *\endmsc\r
 177  */\r
 178 \r
 179  extern\r
 180  NFCSTATUS\r
 181  phDal4Nfc_Register(\r
 182                  phNfcIF_sReference_t   *psRefer,\r
 183                  phNfcIF_sCallBack_t    if_cb,\r
 184                  void *psIFConf\r
 185                  );\r
 186 \r
 187 \r
 188 /**\r
 189  * \ingroup grp_nfc_dal\r
 190  *\r
 191  * \brief  Allows upper layer to unregister with DAL layer.\r
 192  * This interface allows to unregister upper layer callback interfaces with DAL layer.\r
 193  * \note: Once this this API is called DAL layer stops notifying upper layer callbacks in case\r
 194  * any events reported within DAL.\r
 195  *\r
 196  * \param[in]  pContext        DAL context is provided by the upper layer.\r
 197  *                             The DAL context earlier was given to the\r
 198  *                             upper layer through the \ref\r
 199  *                             \e phDal4Nfc_Register() function.\r
 200  * \param[in]  pHwRef              for future use .Currently this parameter is not used.\r
 201  *                             This needs to be other than NULL.\r
 202  *\r
 203  * \retval NFCSTATUS_SUCCESS             Unregistration successful.\r
 204  * \retval NFCSTATUS_INVALID_PARAMETER   At least one parameter of the function is invalid.\r
 205  *\r
 206  *\msc\r
 207  *ClientApp,UpperLayer,phDal4Nfc;\r
 208  *ClientApp=>phDal4Nfc [label="phDal4Nfc_Config()",URL="\ref phDal4Nfc_Config"];\r
 209  *ClientApp<<phDal4Nfc [label="NFCSTATUS_SUCCESS"];\r
 210  *UpperLayer=>phDal4Nfc [label="phDal4Nfc_Register()",URL="\ref phDal4Nfc_Register"];\r
 211  *UpperLayer<<phDal4Nfc [label="NFCSTATUS_SUCCESS"];\r
 212  *--- [label="Upper layer can issue Unregistration later"];\r
 213  *UpperLayer=>phDal4Nfc [label="phDal4Nfc_Unregister()",URL="\ref phDal4Nfc_Unregister"];\r
 214  *UpperLayer<<phDal4Nfc [label="NFCSTATUS_SUCCESS"];\r
 215  *\endmsc\r
 216  */\r
 217 \r
 218 \r
 219  extern\r
 220  NFCSTATUS\r
 221  phDal4Nfc_Unregister(\r
 222                    void   *pContext,\r
 223                    void   *pHwRef\r
 224                    );\r
 225 \r
 226 \r
 227 /**\r
 228 \r
 229  * \ingroup grp_nfc_dal\r
 230  *\r
 231  *\brief This interface allows to initialize DAL layer.\r
 232  * This API implements initialization of DAL layer. This includes :\r
 233  *\r
 234  * <br><br>. Initialize parameters for HW Interface.\r
 235  *<br><br>. Initializing read and writer threads.\r
 236  *<br><br>. Initializing read and write task specific events and event specific configurations.\r
 237  *<br><br>. Initializing DAL layer specific details.\r
 238  *\r
 239  * \param[in]  pContext        DAL context provided by the upper layer.\r
 240  *                             The DAL context will be exported to the\r
 241  *                                                         upper layer via upper layer registration interface.\r
 242  * \param[in]  pHwRef          information of the hardware\r
 243  *\r
 244  * \retval NFCSTATUS_SUCCESS            DAL initialization successful.\r
 245  * \retval NFCSTATUS_INVALID_DEVICE     The device is not enumerated or the\r
 246  *                                      Hardware Reference points to a device\r
 247  *                                                                              which does not exist. Alternatively,\r
 248  *                                      also already open devices produce this\r
 249  *                                      error.\r
 250  * \retval NFCSTATUS_INVALID_PARAMETER  At least one parameter of the function\r
 251  *                                      is invalid.\r
 252  *\r
 253  *\msc\r
 254  *ClientApp,UpperLayer,phDal4Nfc;\r
 255  *ClientApp=>phDal4Nfc [label="phDal4Nfc_Config()",URL="\ref phDal4Nfc_Config"];\r
 256  *ClientApp<<phDal4Nfc [label="NFCSTATUS_SUCCESS"];\r
 257  *UpperLayer=>phDal4Nfc [label="phDal4Nfc_Register()",URL="\ref phDal4Nfc_Register"];\r
 258  *UpperLayer<<phDal4Nfc [label="NFCSTATUS_SUCCESS"];\r
 259  *UpperLayer=>phDal4Nfc [label="phDal4Nfc_Init()",URL="\ref     phDal4Nfc_Init"];\r
 260  *UpperLayer<<phDal4Nfc [label="NFCSTATUS_SUCCESS"];\r
 261  *--- [label="DAL intialised ,read for read /write operations"];\r
 262  *\endmsc\r
 263  */\r
 264 \r
 265  extern\r
 266  NFCSTATUS\r
 267  phDal4Nfc_Init(\r
 268              void  *pContext,\r
 269              void  *pHwRef\r
 270              );\r
 271 \r
 272 \r
 273 /**\r
 274  * \ingroup grp_nfc_dal\r
 275  *\r
 276  * \brief This API implements Deintialisation of DAL layer.\r
 277  *\r
 278  *This API implements Deintialisation of DAL layer. It includes :\r
 279  *<br><br>.Releases all the resources.( context,memory resources,read/write buffers).\r
 280  *<br><br>.closes COMxx port which is used during DAL session.\r
 281  *<br><br>.Terminates Reader and writer tasks.\r
 282  *\r
 283  * \param[in]  pContext        DAL context is provided by the upper layer.\r
 284  *                             The DAL context earlier was given to the\r
 285  *                             upper layer through the\r
 286  *                             \ref \e phDal4Nfc_Register() function\r
 287  * \param[in]  pHwRef           hardware reference context.\r
 288  *\r
 289  * \retval NFCSTATUS_SUCCESS            DAL shutdown successful\r
 290  * \retval NFCSTATUS_FAILED             DAL shutdown failed(example.unable to\r
 291  *                                      suspend thread, close HW Interface etc.)\r
 292  * \retval NFCSTATUS_INVALID_PARAMETER  At least one parameter of the function\r
 293  *                                      is invalid.\r
 294  *\r
 295  *\msc\r
 296  *ClientApp,UpperLayer,phDal4Nfc;\r
 297  *ClientApp=>phDal4Nfc [label="phDal4Nfc_Config()",URL="\ref phDal4Nfc_Config"];\r
 298  *ClientApp<<phDal4Nfc [label="NFCSTATUS_SUCCESS"];\r
 299  *UpperLayer=>phDal4Nfc [label="phDal4Nfc_Register()",URL="\ref phDal4Nfc_Register"];\r
 300  *UpperLayer<<phDal4Nfc [label="NFCSTATUS_SUCCESS"];\r
 301  *UpperLayer=>phDal4Nfc [label="phDal4Nfc_Init()",URL="\ref     phDal4Nfc_Init"];\r
 302  *UpperLayer<<phDal4Nfc [label="NFCSTATUS_SUCCESS"];\r
 303  *--- [label="Perform read write operation"];\r
 304  *--- [label="DAL can be shutdown during upper layer deinit sequence"];\r
 305  *UpperLayer=>phDal4Nfc [label="phDal4Nfc_Shutdown()",URL="\ref phDal4Nfc_Shutdown"];\r
 306  *ClientApp<<phDal4Nfc [label="NFCSTATUS_SUCCESS"];\r
 307  *\endmsc\r
 308  */\r
 309 \r
 310  extern\r
 311  NFCSTATUS\r
 312  phDal4Nfc_Shutdown(\r
 313                  void *pContext,\r
 314                  void *pHwRef\r
 315                  );\r
 316 \r
 317 /**\r
 318  * \ingroup grp_nfc_dal\r
 319  *\r
 320  * \brief Allows to write data block to HW Interface.\r
 321  *\r
 322  * This asynchronous function writes the given block of data to the driver.\r
 323  * This interface enables writer thread in case their is no write requests pending and returns\r
 324  * sucessfully.Once writer thread completes write operation, it notifies upper layer using callback\r
 325  * mechanism .\r
 326  * \note writer thread notifies upper layer callback notified using  windows messaging  mechanism\r
 327  * under deferred call context.\r
 328  *\r
 329  *\r
 330  * \param[in]  pContext        DAL context is provided by the upper layer.\r
 331  *                             The DAL\r
 332  *                             context earlier was given to the upper layer\r
 333  *                             through the \ref \e phDal4Nfc_Register() function\r
 334  * \param[in]  pHwRef          information of the hardware.\r
 335  * \param[in]  pBuffer         The information given by the upper layer to\r
 336  *                             send it to the lower layer\r
 337  * \param[in]  length          The length of pLlc_Buf, that needs to be sent\r
 338  *                             to the lower layer is given by the upper layer\r
 339  *\r
 340  * \retval NFCSTATUS_PENDING                If the command is yet to be process.\r
 341  * \retval NFCSTATUS_BUSY                   BUSY with previous write operation\r
 342  * \retval NFCSTATUS_INVALID_DEVICE         The device has not been opened or has\r
 343  *                                          been disconnected meanwhile\r
 344  * \retval NFCSTATUS_INVALID_PARAMETER      At least one parameter of the function\r
 345  *                                          is invalid.\r
 346  *\r
 347  *\msc\r
 348  *ClientApp,UpperLayer,phDal4Nfc;\r
 349 *--- [label="Configure,intialise DAL layer and Register with DAL "];\r
 350  *UpperLayer=>phDal4Nfc [label="phDal4Nfc_Write()",URL="\ref  phDal4Nfc_Write()"];\r
 351  *UpperLayer<<phDal4Nfc [label="NFCSTATUS_PENDING"];\r
 352  *--- [label="DAL posts write message to main thread under deferred call context"];\r
 353  *phDal4Nfc=>phDal4Nfc [label="phDal4Nfc_DeferredCall()",URL="\ref      phDal4Nfc_DeferredCall()"];\r
 354  *ClientApp=>phDal4Nfc  [label="phDal4Nfc_DeferredCb()",URL="\ref  phDal4Nfc_DeferredCb()"];\r
 355  *phDal4Nfc=>UpperLayer [label="send_complete",URL="\ref phDal4Nfc_DeferredCb()"];\r
 356  *ClientApp<<phDal4Nfc  [label="NFCSTATUS_SUCCESS"];\r
 357  *\endmsc\r
 358  */\r
 359  extern\r
 360  NFCSTATUS\r
 361  phDal4Nfc_Write(\r
 362              void *pContext,\r
 363              void *pHwRef,\r
 364              uint8_t *pBuffer,\r
 365              uint16_t length\r
 366              );\r
 367 \r
 368 \r
 369 /**\r
 370  * \ingroup grp_nfc_dal\r
 371  *\r
 372  * \brief Allows to Read data block from HW Interface.\r
 373  *\r
 374  * This asynchronous function reads the data from the driver in which length\r
 375  * and the required buffer are sent by upper layer. This interface enables\r
 376  * reader thread in case there is no read requests pending and returns sucessfully.\r
 377  * Once read operation is complete, it notifies  to upper layer through callback \r
 378  * registered in the \b \e phDal4Nfc_Register() function.\r
 379  *\r
 380  *\r
 381  * \param[in]  pContext        DAL context is provided by the upper layer.\r
 382  *                             The DAL context earlier was given to the\r
 383  *                             upper layer through the\r
 384  *                             \b \e phDal4Nfc_Register() function\r
 385  * \param[in]  pHwRef          Information of the hardware\r
 386  * \param[in]  pBuffer         The information given by the upper layer to\r
 387  *                             receive data from the lower layer\r
 388  * \param[in]  length          The length of pBuffer given by the upper layer\r
 389  *\r
 390  * \retval NFCSTATUS_PENDING                If the command is yet to be processed.\r
 391  * \retval NFCSTATUS_INVALID_PARAMETER      At least one parameter of the function\r
 392  *                                          is invalid.\r
 393  * \retval NFCSTATUS_INVALID_DEVICE         The device has not been opened or has\r
 394  *                                          been disconnected meanwhile\r
 395  *\r
 396  *\msc\r
 397  *ClientApp,UpperLayer,phDal4Nfc;\r
 398  *--- [label="Configure,intialise DAL layer and Register with DAL "];\r
 399  *UpperLayer=>phDal4Nfc [label="phDal4Nfc_Write()",URL="\ref phDal4Nfc_Write()"];\r
 400  *UpperLayer<<phDal4Nfc [label="NFCSTATUS_PENDING"];\r
 401  *--- [label="DAL posts write message to main thread under deferred call context"];\r
 402  *phDal4Nfc=>phDal4Nfc [label="phDal4Nfc_DeferredCall()",URL="\ref      phDal4Nfc_DeferredCall()"];\r
 403  *ClientApp=>phDal4Nfc  [label="phDal4Nfc_DeferredCb()",URL="\ref  phDal4Nfc_DeferredCb()"];\r
 404  *phDal4Nfc=>UpperLayer [label="send_complete",URL="\ref phDal4Nfc_DeferredCb()"];\r
 405  *ClientApp<<phDal4Nfc  [label="NFCSTATUS_SUCCESS"];\r
 406  *--- [label="upper layer can issue read request"];\r
 407  *UpperLayer=>phDal4Nfc [label="phDal4Nfc_Read()",URL="\ref phDal4Nfc_Read()"];\r
 408  *UpperLayer<<phDal4Nfc [label="NFCSTATUS_PENDING"];\r
 409  *--- [label="DAL posts read message to main thread under deferred call context"];\r
 410  *phDal4Nfc=>phDal4Nfc [label="phDal4Nfc_DeferredCall()",URL="\ref      phDal4Nfc_DeferredCall()"];\r
 411  *ClientApp=>phDal4Nfc  [label="phDal4Nfc_DeferredCb()",URL="\ref  phDal4Nfc_DeferredCb()"];\r
 412  *phDal4Nfc=>UpperLayer [label="receive_complete",URL="\ref  phDal4Nfc_DeferredCb()"];\r
 413  *ClientApp<<phDal4Nfc  [label="NFCSTATUS_SUCCESS"];\r
 414 \r
 415  *\endmsc\r
 416  */\r
 417 \r
 418  extern\r
 419  NFCSTATUS\r
 420  phDal4Nfc_Read(\r
 421             void *pContext,\r
 422             void *pHwRef,\r
 423             uint8_t *pBuffer,\r
 424             uint16_t length\r
 425             );\r
 426 \r
 427 /**\r
 428  * \ingroup grp_nfc_dal\r
 429  *\r
 430  * \brief Allows to wait before reading data block from HW Interface.\r
 431  *\r
 432  * This asynchronous function waits before reading the data from the\r
 433  * driver in which length  and the required buffer are sent by upper layer.  \r
 434  * This interface  enables reader thread  to wait for predefined time period\r
 435  * (predefined time period is configurable by the DAL implementer) to complete  \r
 436  * read request.Once read operation is complete, it notifies to upper layer \r
 437  * through callback registered in the \b \e phDal4Nfc_Register()\r
 438  * function. Read request is expected to get complete within this time.\r
 439  *\r
 440  * \param[in]  pContext        DAL context is provided by the upper layer.\r
 441  *                             The DAL context earlier was given to the\r
 442  *                                                         upper layer through the\r
 443  *                             \b \e phDal4Nfc_Register() function\r
 444  * \param[in]  pHwRef          Information of the hardware\r
 445  * \param[in]  pBuffer         The information given by the upper layer to\r
 446  *                             receive data from the lower layer\r
 447  * \param[in]  length          The length of pBuffer given by the upper layer\r
 448  *\r
 449  * \retval NFCSTATUS_SUCCESS                DAL receive successful\r
 450  * \retval NFCSTATUS_BUSY                   BUSY with previous receive operation\r
 451  * \retval NFCSTATUS_INVALID_PARAMETER      At least one parameter of the\r
 452  *                                          function is invalid.\r
 453  * \retval NFCSTATUS_INVALID_DEVICE         The device has not been opened or has\r
 454  *                                          been disconnected meanwhile\r
 455  *\r
 456  *\r
 457  *\msc\r
 458  *ClientApp,UpperLayer,phDal4Nfc;\r
 459  *--- [label="Configure,intialise DAL layer and Register with DAL "];\r
 460  *UpperLayer=>phDal4Nfc [label="phDal4Nfc_Write()",URL="\ref  phDal4Nfc_Write()"];\r
 461  *UpperLayer<<phDal4Nfc [label="NFCSTATUS_PENDING"];\r
 462  *--- [label="DAL posts write message to main thread under deferred call context"];\r
 463  *phDal4Nfc=>phDal4Nfc [label="phDal4Nfc_DeferredCall()",URL="\ref      phDal4Nfc_DeferredCall()"];\r
 464  *ClientApp=>phDal4Nfc  [label="phDal4Nfc_DeferredCb()",URL="\ref  phDal4Nfc_DeferredCb()"];\r
 465  *phDal4Nfc=>UpperLayer [label="send_complete",URL="\ref phDal4Nfc_DeferredCb()"];\r
 466  *ClientApp<<phDal4Nfc  [label="NFCSTATUS_SUCCESS"];\r
 467  *--- [label="upper layer can issue read wait request "];\r
 468  *UpperLayer=>phDal4Nfc [label="phDal4Nfc_ReadWait()",URL="\ref phDal4Nfc_ReadWait()"];\r
 469  *UpperLayer<<phDal4Nfc [label="NFCSTATUS_PENDING"];\r
 470  *--- [label="DAL posts read wait message to main thread under deferred call context"];\r
 471  *phDal4Nfc=>phDal4Nfc [label="phDal4Nfc_DeferredCall()",URL="\ref      phDal4Nfc_DeferredCall()"];\r
 472  *ClientApp=>phDal4Nfc  [label="phDal4Nfc_DeferredCb()",URL="\ref  phDal4Nfc_DeferredCb()"];\r
 473  *phDal4Nfc=>UpperLayer [label="receive_complete",URL="\ref  phDal4Nfc_DeferredCb()"];\r
 474  *ClientApp<<phDal4Nfc  [label="NFCSTATUS_SUCCESS"];\r
 475  *\r
 476  *\endmsc\r
 477  */\r
 478 \r
 479 \r
 480  extern\r
 481  NFCSTATUS\r
 482  phDal4Nfc_ReadWait(\r
 483                 void *pContext,\r
 484                 void *pHwRef,\r
 485                 uint8_t *pBuffer,\r
 486                 uint16_t length\r
 487                 );\r
 488 \r
 489 \r
 490 /**\r
 491  * \ingroup grp_nfc_dal\r
 492  *\r
 493  *\brief  Aborts read wait opertaion.\r
 494  *\r
 495  * This asynchronous function issues cancellation of the outstanding \r
 496  * \b \e phDal4Nfc_ReadWait request.If upper layer wants to cancel the \r
 497  * ongoing read wait operation this function is used. e.g. to abort the\r
 498  * transactions.\r
 499  *\r
 500  * \param[in]  pContext        DAL context is provided by the upper layer.\r
 501  *                             The DAL context earlier was given to the\r
 502  *                             upper layer through the\r
 503  *                             \b \e phDal4Nfc_Register() function\r
 504  * \param[in]  pHwRef          Information of the hardware\r
 505  *\r
 506  * \retval NFCSTATUS_SUCCESS                    DAL receive successful\r
 507  * \retval NFCSTATUS_INVALID_PARAMETER          At least one parameter of the\r
 508  *                                              function is invalid.\r
 509  * \retval NFCSTATUS_INVALID_DEVICE             The device has not been opened\r
 510  *                                              or has been disconnected meanwhile\r
 511  * \retval NFCSTATUS_BOARD_COMMUNICATION_ERROR  A board communication error occurred\r
 512                                                 (e.g. configuration went wrong).\r
 513  *\r
 514  *\r
 515  *\msc\r
 516  *ClientApp,UpperLayer,phDal4Nfc;\r
 517  *--- [label="Configure,intialise DAL layer and Register with DAL "];\r
 518  *UpperLayer=>phDal4Nfc [label="phDal4Nfc_Write()",URL="\ref  phDal4Nfc_Write()"];\r
 519  *UpperLayer<<phDal4Nfc [label="NFCSTATUS_PENDING"];\r
 520  *--- [label="DAL posts write message to main thread under deferred call context"];\r
 521  *phDal4Nfc=>phDal4Nfc [label="phDal4Nfc_DeferredCall()",URL="\ref      phDal4Nfc_DeferredCall()"];\r
 522  *ClientApp=>phDal4Nfc  [label="phDal4Nfc_DeferredCb()",URL="\ref Call phDal4Nfc_DeferredCb()"];\r
 523  *phDal4Nfc=>UpperLayer [label="send_complete",URL="\ref phDal4Nfc_DeferredCb()"];\r
 524  *ClientApp<<phDal4Nfc  [label="NFCSTATUS_SUCCESS"];\r
 525  *--- [label="upper layer can issue read wait request "];\r
 526  *UpperLayer=>phDal4Nfc [label="phDal4Nfc_ReadWait()",URL="\ref phDal4Nfc_ReadWait()"];\r
 527  *UpperLayer<<phDal4Nfc [label="NFCSTATUS_PENDING"];\r
 528  *--- [label="Issue Read wait cancel request here"];\r
 529  *UpperLayer=>phDal4Nfc [label="phDal4Nfc_ReadWaitCancel()",URL="\ref phDal4Nfc_ReadWaitCancel()"];\r
 530  **UpperLayer<<phDal4Nfc        [label="NFCSTATUS_SUCCESS"];\r
 531  *\endmsc\r
 532  */\r
 533  extern\r
 534  NFCSTATUS\r
 535  phDal4Nfc_ReadWaitCancel(\r
 536                         void *pContext,\r
 537                         void *pHwRef\r
 538                         );\r
 539 \r
 540 /**\r
 541  * \ingroup grp_nfc_dal\r
 542  *\r
 543  * \brief DAL config function\r
 544  * This synchronous function configures the given HW Interface and\r
 545  * sends the HANDLE to the caller.\r
 546  *\r
 547  * \param[in]       config     DAL configuration details as provided\r
 548  *                             by the upper layer. \r
 549  * \param[in,out]   phwref     pointer to which valid Handle to DAL\r
 550  *                             interface is assigned.\r
 551  *\r
 552  * \retval NFCSTATUS_SUCCESS                    Configuration happened successfully.\r
 553  * \retval NFCSTATUS_INVALID_PARAMETER          At least one parameter of the function\r
 554  *                                              is invalid.\r
 555  * \retval NFCSTATUS_FAILED                     Configuration failed(example.unable to\r
 556  *                                              open HW Interface).\r
 557  * \retval NFCSTATUS_INVALID_DEVICE             The device has not been opened or\r
 558  *                                              has been disconnected meanwhile\r
 559  * \retval NFCSTATUS_BOARD_COMMUNICATION_ERROR  A board communication error occurred\r
 560                                                 (e.g. configuration went wrong).\r
 561  *\msc\r
 562  *ClientApp,UpperLayer,phDal4Nfc;\r
 563  *ClientApp=>phDal4Nfc [label="phDal4Nfc_Config()",URL="\ref phDal4Nfc_Config"];\r
 564  *ClientApp<<phDal4Nfc [label="NFCSTATUS_SUCCESS"];\r
 565  *\endmsc\r
 566  */\r
 567  extern\r
 568  NFCSTATUS\r
 569  phDal4Nfc_Config (\r
 570                 pphDal4Nfc_sConfig_t config,\r
 571                 void **phwref\r
 572                 );\r
 573 \r
 574  /**\r
 575  * \ingroup grp_nfc_dal\r
 576  *\r
 577  * \brief Release configuration for the given HW Interface.\r
 578  *\r
 579  * \copydoc page_reg Release all the variables of the DAL component, that has been \r
 580  *      initialised in \b phDal4Nfc_Config function (Synchronous function).\r
 581  *\r
 582  * \param[in] pHwRef            Link information of the hardware\r
 583  *\r
 584  * \retval NFCSTATUS_SUCCESS            DAL Configuration Released successfully.\r
 585  * \retval NFCSTATUS_FAILED             Configuration release failed(example: Unable to close Com port).\r
 586  *\r
 587  *\msc\r
 588  *ClientApp,UpperLayer,phDal4Nfc;\r
 589  *ClientApp=>phDal4Nfc [label="phDal4Nfc_Config()",URL="\ref phDal4Nfc_Config"];\r
 590  *ClientApp<<phDal4Nfc [label="NFCSTATUS_SUCCESS"];\r
 591  *UpperLayer=>phDal4Nfc [label="phDal4Nfc_Register()",URL="\ref phDal4Nfc_Register"];\r
 592  *UpperLayer<<phDal4Nfc [label="NFCSTATUS_SUCCESS"];\r
 593  *UpperLayer=>phDal4Nfc [label="phDal4Nfc_Init()",URL="\ref     phDal4Nfc_Init"];\r
 594  *UpperLayer<<phDal4Nfc [label="NFCSTATUS_SUCCESS"];\r
 595  *--- [label="Perform read write operation"];\r
 596  *--- [label="DAL resources can be released during upper layer deinit sequence"];\r
 597  *UpperLayer=>phDal4Nfc [label="phDal4Nfc_Shutdown()",URL="\ref phDal4Nfc_Shutdown"];\r
 598  *UpperLayer<<phDal4Nfc [label="NFCSTATUS_SUCCESS"];\r
 599  *ClientApp=>phDal4Nfc [label="phDal4Nfc_ConfigRelease()",URL="\ref phDal4Nfc_ConfigRelease"];\r
 600  *ClientApp<<phDal4Nfc [label="NFCSTATUS_SUCCESS"]; \r
 601  *\endmsc\r
 602  */\r
 603 extern \r
 604 NFCSTATUS \r
 605 phDal4Nfc_ConfigRelease(\r
 606     void        *pHwRef);\r
 607 \r
 608 extern \r
 609 NFCSTATUS \r
 610 phDal4Nfc_Reset(long level);\r
 611 \r
 612 extern \r
 613 NFCSTATUS \r
 614 phDal4Nfc_Download();\r
 615 \r
 616 /******************** Function declarations *************************/\r
 617 \r
 618 #endif /* PHDALNFC_H */\r
 619 \r
 620 /****************************************** END OF FILE ***************************************************/\r
 621 \r