1 /**
2  * \file timing.h
3  *
4  * \brief Portable interface to timeouts and to the CPU cycle counter
5  */
6 /*
7  *  Copyright The Mbed TLS Contributors
8  *  SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
9  */
10 #ifndef MBEDTLS_TIMING_H
11 #define MBEDTLS_TIMING_H
12 #include "mbedtls/private_access.h"
13 
14 #include "mbedtls/build_info.h"
15 
16 #include <stdint.h>
17 
18 #ifdef __cplusplus
19 extern "C" {
20 #endif
21 
22 #if !defined(MBEDTLS_TIMING_ALT)
23 // Regular implementation
24 //
25 
26 /**
27  * \brief          timer structure
28  */
29 struct mbedtls_timing_hr_time {
30     uint64_t MBEDTLS_PRIVATE(opaque)[4];
31 };
32 
33 /**
34  * \brief          Context for mbedtls_timing_set/get_delay()
35  */
36 typedef struct mbedtls_timing_delay_context {
37     struct mbedtls_timing_hr_time   MBEDTLS_PRIVATE(timer);
38     uint32_t                        MBEDTLS_PRIVATE(int_ms);
39     uint32_t                        MBEDTLS_PRIVATE(fin_ms);
40 } mbedtls_timing_delay_context;
41 
42 #else  /* MBEDTLS_TIMING_ALT */
43 #include "timing_alt.h"
44 #endif /* MBEDTLS_TIMING_ALT */
45 
46 /* Internal use */
47 unsigned long mbedtls_timing_get_timer(struct mbedtls_timing_hr_time *val, int reset);
48 
49 /**
50  * \brief          Set a pair of delays to watch
51  *                 (See \c mbedtls_timing_get_delay().)
52  *
53  * \param data     Pointer to timing data.
54  *                 Must point to a valid \c mbedtls_timing_delay_context struct.
55  * \param int_ms   First (intermediate) delay in milliseconds.
56  *                 The effect if int_ms > fin_ms is unspecified.
57  * \param fin_ms   Second (final) delay in milliseconds.
58  *                 Pass 0 to cancel the current delay.
59  *
60  * \note           To set a single delay, either use \c mbedtls_timing_set_timer
61  *                 directly or use this function with int_ms == fin_ms.
62  */
63 void mbedtls_timing_set_delay(void *data, uint32_t int_ms, uint32_t fin_ms);
64 
65 /**
66  * \brief          Get the status of delays
67  *                 (Memory helper: number of delays passed.)
68  *
69  * \param data     Pointer to timing data
70  *                 Must point to a valid \c mbedtls_timing_delay_context struct.
71  *
72  * \return         -1 if cancelled (fin_ms = 0),
73  *                  0 if none of the delays are passed,
74  *                  1 if only the intermediate delay is passed,
75  *                  2 if the final delay is passed.
76  */
77 int mbedtls_timing_get_delay(void *data);
78 
79 /**
80  * \brief          Get the final timing delay
81  *
82  * \param data     Pointer to timing data
83  *                 Must point to a valid \c mbedtls_timing_delay_context struct.
84  *
85  * \return         Final timing delay in milliseconds.
86  */
87 uint32_t mbedtls_timing_get_final_delay(
88     const mbedtls_timing_delay_context *data);
89 
90 #ifdef __cplusplus
91 }
92 #endif
93 
94 #endif /* timing.h */
95