1/*---------------------------------------------------------------------------*
2 *  pcputimer.h  *
3 *                                                                           *
4 *  Copyright 2007, 2008 Nuance Communciations, Inc.                               *
5 *                                                                           *
6 *  Licensed under the Apache License, Version 2.0 (the 'License');          *
7 *  you may not use this file except in compliance with the License.         *
8 *                                                                           *
9 *  You may obtain a copy of the License at                                  *
10 *      http://www.apache.org/licenses/LICENSE-2.0                           *
11 *                                                                           *
12 *  Unless required by applicable law or agreed to in writing, software      *
13 *  distributed under the License is distributed on an 'AS IS' BASIS,        *
14 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. *
15 *  See the License for the specific language governing permissions and      *
16 *  limitations under the License.                                           *
17 *                                                                           *
18 *---------------------------------------------------------------------------*/
19
20#ifndef PCPUTIMER_H
21#define PCPUTIMER_H
22
23
24
25#include "PortPrefix.h"
26#include "ptypes.h"
27
28/**
29 * @addtogroup PCPUTimerModule PCPUTimer API functions
30 *
31 * @{
32 */
33
34/** Typedef */
35typedef struct PCPUTimer_t PCPUTimer;
36
37/**
38 * Creates a new timer object.
39 *
40 * @param timer PCPUTimer handle
41 * @return ESR_INVALID_ARGUMENT if timer is value it points to is null
42 */
43PORTABLE_API ESR_ReturnCode PCPUTimerCreate(PCPUTimer **timer);
44
45
46/**
47 * Destroys timer object.
48 *
49 * @param timer PCPUTimer handle
50 * @return ESR_INVALID_ARGUMENT if timer is null
51 */
52PORTABLE_API ESR_ReturnCode PCPUTimerDestroy(PCPUTimer *timer);
53
54/**
55 * Starts the timer. This sets the reference time from which all new elapsed
56 * time are computed.  This does not reset the elapsed time to 0.  This is
57 * useful to pause the timer.
58 *
59 * @return ESR_INVALID_ARGUMENT if timer is null; ESR_FATAL_ERROR if OS timer is available
60 */
61PORTABLE_API ESR_ReturnCode PCPUTimerStart(PCPUTimer *timer);
62
63/**
64 * Stops the timer.
65 *
66 * @return ESR_INVALID_ARGUMENT if timer is null; ESR_FATAL_ERROR if OS timer is available
67 */
68PORTABLE_API ESR_ReturnCode PCPUTimerStop(PCPUTimer *timer);
69
70/**
71 * Returns the timer elapsed time.  If the Timer is in the stopped state,
72 * successive calls to getElapsed() will always return the same value.  If the
73 * Timer is in the started state, successive calls will return the elapsed
74 * time since the last time PCPUTimerStart() was called.
75 *
76 * @return ESR_INVALID_ARGUMENT if timer or elapsed to is null; ESR_FATAL_ERROR if OS timer is available
77 */
78PORTABLE_API ESR_ReturnCode PCPUTimerGetElapsed(PCPUTimer *timer,
79    asr_uint32_t* elapsed);
80
81/**
82 * Resets the elapsed time to 0 and resets the reference time of the Timer.
83 * This effectively reset the timer in the same state it was right after
84 * creation.
85 *
86 * @return ESR_INVALID_ARGUMENT if timer is null
87 */
88PORTABLE_API ESR_ReturnCode PCPUTimerReset(PCPUTimer *timer);
89
90/**
91 * @}
92 */
93
94
95#endif
96