src/phDal4Nfc.h

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