4 * \brief Portable interface to timeouts and to the CPU cycle counter
7 * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
8 * SPDX-License-Identifier: Apache-2.0
10 * Licensed under the Apache License, Version 2.0 (the "License"); you may
11 * not use this file except in compliance with the License.
12 * You may obtain a copy of the License at
14 * http://www.apache.org/licenses/LICENSE-2.0
16 * Unless required by applicable law or agreed to in writing, software
17 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
18 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 * See the License for the specific language governing permissions and
20 * limitations under the License.
22 * This file is part of mbed TLS (https://tls.mbed.org)
24 #ifndef MBEDTLS_TIMING_H
25 #define MBEDTLS_TIMING_H
27 #if !defined(MBEDTLS_CONFIG_FILE)
30 #include MBEDTLS_CONFIG_FILE
39 #if !defined(MBEDTLS_TIMING_ALT)
40 // Regular implementation
44 * \brief timer structure
46 struct mbedtls_timing_hr_time
48 unsigned char opaque[32];
52 * \brief Context for mbedtls_timing_set/get_delay()
54 typedef struct mbedtls_timing_delay_context
56 struct mbedtls_timing_hr_time timer;
59 } mbedtls_timing_delay_context;
61 #else /* MBEDTLS_TIMING_ALT */
62 #include "timing_alt.h"
63 #endif /* MBEDTLS_TIMING_ALT */
65 extern volatile int mbedtls_timing_alarmed;
68 * \brief Return the CPU cycle counter value
70 * \warning This is only a best effort! Do not rely on this!
71 * In particular, it is known to be unreliable on virtual
74 * \note This value starts at an unspecified origin and
77 unsigned long mbedtls_timing_hardclock( void );
80 * \brief Return the elapsed time in milliseconds
82 * \param val points to a timer structure
83 * \param reset If 0, query the elapsed time. Otherwise (re)start the timer.
85 * \return Elapsed time since the previous reset in ms. When
86 * restarting, this is always 0.
88 * \note To initialize a timer, call this function with reset=1.
90 * Determining the elapsed time and resetting the timer is not
91 * atomic on all platforms, so after the sequence
92 * `{ get_timer(1); ...; time1 = get_timer(1); ...; time2 =
93 * get_timer(0) }` the value time1+time2 is only approximately
94 * the delay since the first reset.
96 unsigned long mbedtls_timing_get_timer( struct mbedtls_timing_hr_time *val, int reset );
99 * \brief Setup an alarm clock
101 * \param seconds delay before the "mbedtls_timing_alarmed" flag is set
104 * \warning Only one alarm at a time is supported. In a threaded
105 * context, this means one for the whole process, not one per
108 void mbedtls_set_alarm( int seconds );
111 * \brief Set a pair of delays to watch
112 * (See \c mbedtls_timing_get_delay().)
114 * \param data Pointer to timing data.
115 * Must point to a valid \c mbedtls_timing_delay_context struct.
116 * \param int_ms First (intermediate) delay in milliseconds.
117 * The effect if int_ms > fin_ms is unspecified.
118 * \param fin_ms Second (final) delay in milliseconds.
119 * Pass 0 to cancel the current delay.
121 * \note To set a single delay, either use \c mbedtls_timing_set_timer
122 * directly or use this function with int_ms == fin_ms.
124 void mbedtls_timing_set_delay( void *data, uint32_t int_ms, uint32_t fin_ms );
127 * \brief Get the status of delays
128 * (Memory helper: number of delays passed.)
130 * \param data Pointer to timing data
131 * Must point to a valid \c mbedtls_timing_delay_context struct.
133 * \return -1 if cancelled (fin_ms = 0),
134 * 0 if none of the delays are passed,
135 * 1 if only the intermediate delay is passed,
136 * 2 if the final delay is passed.
138 int mbedtls_timing_get_delay( void *data );
140 #if defined(MBEDTLS_SELF_TEST)
142 * \brief Checkup routine
144 * \return 0 if successful, or 1 if a test failed
146 int mbedtls_timing_self_test( int verbose );
153 #endif /* timing.h */