include/mbedtls/timing.h

0001 /**
0002  * \file timing.h
0003  *
0004  * \brief Portable interface to timeouts and to the CPU cycle counter
0005  */
0006 /*
0007  *  Copyright The Mbed TLS Contributors
0008  *  SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
0009  */
0010 #ifndef MBEDTLS_TIMING_H
0011 #define MBEDTLS_TIMING_H
0012 #include "mbedtls/private_access.h"
0013
0014 #include "mbedtls/build_info.h"
0015
0016 #include <stdint.h>
0017
0018 #ifdef __cplusplus
0019 extern "C" {
0020 #endif
0021
0022 #if !defined(MBEDTLS_TIMING_ALT)
0023 // Regular implementation
0024 //
0025
0026 /**
0027  * \brief          timer structure
0028  */
0029 struct mbedtls_timing_hr_time {
0030     uint64_t MBEDTLS_PRIVATE(opaque)[4];
0031 };
0032
0033 /**
0034  * \brief          Context for mbedtls_timing_set/get_delay()
0035  */
0036 typedef struct mbedtls_timing_delay_context {
0037     struct mbedtls_timing_hr_time   MBEDTLS_PRIVATE(timer);
0038     uint32_t                        MBEDTLS_PRIVATE(int_ms);
0039     uint32_t                        MBEDTLS_PRIVATE(fin_ms);
0040 } mbedtls_timing_delay_context;
0041
0042 #else  /* MBEDTLS_TIMING_ALT */
0043 #include "timing_alt.h"
0044 #endif /* MBEDTLS_TIMING_ALT */
0045
0046 /* Internal use */
0047 unsigned long mbedtls_timing_get_timer(struct mbedtls_timing_hr_time *val, int reset);
0048
0049 /**
0050  * \brief          Set a pair of delays to watch
0051  *                 (See \c mbedtls_timing_get_delay().)
0052  *
0053  * \param data     Pointer to timing data.
0054  *                 Must point to a valid \c mbedtls_timing_delay_context struct.
0055  * \param int_ms   First (intermediate) delay in milliseconds.
0056  *                 The effect if int_ms > fin_ms is unspecified.
0057  * \param fin_ms   Second (final) delay in milliseconds.
0058  *                 Pass 0 to cancel the current delay.
0059  *
0060  * \note           To set a single delay, either use \c mbedtls_timing_set_timer
0061  *                 directly or use this function with int_ms == fin_ms.
0062  */
0063 void mbedtls_timing_set_delay(void *data, uint32_t int_ms, uint32_t fin_ms);
0064
0065 /**
0066  * \brief          Get the status of delays
0067  *                 (Memory helper: number of delays passed.)
0068  *
0069  * \param data     Pointer to timing data
0070  *                 Must point to a valid \c mbedtls_timing_delay_context struct.
0071  *
0072  * \return         -1 if cancelled (fin_ms = 0),
0073  *                  0 if none of the delays are passed,
0074  *                  1 if only the intermediate delay is passed,
0075  *                  2 if the final delay is passed.
0076  */
0077 int mbedtls_timing_get_delay(void *data);
0078
0079 /**
0080  * \brief          Get the final timing delay
0081  *
0082  * \param data     Pointer to timing data
0083  *                 Must point to a valid \c mbedtls_timing_delay_context struct.
0084  *
0085  * \return         Final timing delay in milliseconds.
0086  */
0087 uint32_t mbedtls_timing_get_final_delay(
0088     const mbedtls_timing_delay_context *data);
0089
0090 #ifdef __cplusplus
0091 }
0092 #endif
0093
0094 #endif /* timing.h */