1 /*

     2   gptimer_chipset_api.h

     3 

     4   Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies). 

     5   All rights reserved.

     6 

     7   This program and the accompanying materials are made available 

     8   under the terms of the Eclipse Public License v1.0 which accompanies 

     9   this distribution, and is available at 

    10   http://www.eclipse.org/legal/epl-v10.html

    11 

    12   Initial Contributors:

    13   Nokia Corporation - initial contribution.

    14 

    15   Contributors:

    16 */

    17 

    18 /** @file

    19 @brief General Purpose Timer Chipset API H

    20 

    21 @publishedDeviceAbstraction

    22 */

    23 

    24 #ifndef __GPTIMER_CHIPSET_API_H__

    25 #define __GPTIMER_CHIPSET_API_H__

    26 

    27 

    28 // Include files

    29 #include <kern_priv.h>

    30 

    31 

    32 /**

    33 Pointer to a callback function for the GPT client to use

    34 

    35 @note "Callback is executed in the DFC or ISR context"

    36 

    37 @param TAny* pointer to a parameter the call back function may use

    38 */

    39 typedef void (*GPTimerFn)(TAny*);

    40 

    41 

    42 

    43 // Class declaration

    44 

    45 /**

    46 @brief GP timer class

    47 

    48  General Purpose Timer functionality for clients

    49 */

    50 class GPTimer

    51     {

    52     public:

    53         /**

    54         constructor of a GPT object

    55         */

    56         IMPORT_C GPTimer();

    57           

    58           

    59         /**

    60         allocates a HW GPT

    61 

    62         @param aFunction A pointer to a callback function which is called 

    63                when the timer expires.

    64         @param aPtr A parameter of the callback function.

    65 

    66         @return returns KErrNone if there was no error or KErrInUse if no 

    67                 HW GPT is available.

    68 

    69         @pre Pre-condition: HW GPT must be available

    70         */

    71         IMPORT_C TInt Open(GPTimerFn aFunction, TAny* aPtr);

    72           

    73           

    74         /**

    75         Releases a HW GPT

    76 

    77         @return Returns KErrNone if there was no error or KErrNotFound if 

    78                 no HW GPT was allocated before.

    79 

    80         @pre Pre-condition: Open was called

    81         */

    82         IMPORT_C TInt Close();

    83           

    84           

    85         /**

    86         Starts a GPT in one-shot mode, the callback routine will be called in 

    87         interrupt context.

    88 

    89         @param aTime Timeout in microseconds.

    90 

    91         @return returns KErrNone if there was no error, KErrInUse if the timer is already active,

    92                         KErrNotFound if no HW GPT was allocated before.

    93         */

    94         IMPORT_C TInt OneShot(TUint aTime);

    95 

    96 

    97 

    98         /**

    99         Starts a GPT in one-shot mode, the callback routine will be called in client's DFC context.

   100 

   101         @param aTime Timeout in microseconds.

   102         @param aDfc client's DFC object.

   103 

   104         @return returns KErrNone if there was no error, KErrInUse if the timer is already active,

   105                         KErrArgument if aDfc is NULL, KErrNotFound if no HW GPT was allocated before.

   106         */

   107         IMPORT_C TInt OneShot(TUint aTime, TDfc& aDfc);

   108 

   109 

   110 

   111         /**

   112         Starts a GPT in periodic mode (the timer is restarted after it expired).

   113         The callback routine will be called in interrupt context.

   114 

   115         @param aTime Timeout in microseconds.

   116 

   117         @return returns KErrNone if there was no error, KErrInUse if the timer is already active,

   118                         KErrNotFound if no HW GPT was allocated before.

   119         */

   120         IMPORT_C TInt Periodic(TUint aTime);

   121 

   122 

   123         /**

   124         Starts a GPT in periodic mode (the timer is restarted after it expired).

   125         The callback routine will be called in client's DFC context.

   126 

   127         @param aTime Timeout in microseconds.

   128         @param aDfc client's DFC object.

   129 

   130         @return returns KErrNone if there was no error or KErrInUse if the timer is already active,

   131                         KErrArgument if aDfc is NULL, KErrNotFound if no HW GPT was allocated before.

   132         */

   133         IMPORT_C TInt Periodic(TUint aTime, TDfc& aDfc);

   134 

   135 

   136         /**

   137         Requests to cancel a GPT.

   138 

   139         @return Returns ETrue if the timer was actually cancelled or EFalse if the timer was not

   140                         cancelled because it was not running or the callback was already running.

   141         */

   142         IMPORT_C TBool Cancel();

   143 

   144         /**

   145         destructor of a GPT object

   146         */

   147         IMPORT_C ~GPTimer();

   148           

   149     private:

   150         /**

   151         stores aFunction parameter

   152         */

   153         GPTimerFn iFunction;

   154 

   155 

   156         /**

   157         stores aPtr parameter

   158         */

   159         TAny* iPtr;

   160         

   161         

   162         /**

   163         stores aTime parameter

   164         */

   165         TUint iTime;

   166 

   167 

   168         /**

   169         stores aDfc parameter

   170         */

   171         TDfc iDfc;

   172     };

   173 

   174 

   175 #endif // __GPTIMER_CHIPSET_API_H__