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 * This file is provided under the Apache License 2.0, or the 11 * GNU General Public License v2.0 or later. 12 * 13 * ********** 14 * Apache License 2.0: 15 * 16 * Licensed under the Apache License, Version 2.0 (the "License"); you may 17 * not use this file except in compliance with the License. 18 * You may obtain a copy of the License at 19 * 20 * http://www.apache.org/licenses/LICENSE-2.0 21 * 22 * Unless required by applicable law or agreed to in writing, software 23 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 24 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 25 * See the License for the specific language governing permissions and 26 * limitations under the License. 27 * 28 * ********** 29 * 30 * ********** 31 * GNU General Public License v2.0 or later: 32 * 33 * This program is free software; you can redistribute it and/or modify 34 * it under the terms of the GNU General Public License as published by 35 * the Free Software Foundation; either version 2 of the License, or 36 * (at your option) any later version. 37 * 38 * This program is distributed in the hope that it will be useful, 39 * but WITHOUT ANY WARRANTY; without even the implied warranty of 40 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 41 * GNU General Public License for more details. 42 * 43 * You should have received a copy of the GNU General Public License along 44 * with this program; if not, write to the Free Software Foundation, Inc., 45 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 46 * 47 * ********** 48 */ 49 #ifndef MBEDTLS_TIMING_H 50 #define MBEDTLS_TIMING_H 51 52 #if !defined(MBEDTLS_CONFIG_FILE) 53 #include "config.h" 54 #else 55 #include MBEDTLS_CONFIG_FILE 56 #endif 57 58 #include <stdint.h> 59 60 #ifdef __cplusplus 61 extern "C" { 62 #endif 63 64 #if !defined(MBEDTLS_TIMING_ALT) 65 // Regular implementation 66 // 67 68 /** 69 * \brief timer structure 70 */ 71 struct mbedtls_timing_hr_time 72 { 73 unsigned char opaque[32]; 74 }; 75 76 /** 77 * \brief Context for mbedtls_timing_set/get_delay() 78 */ 79 typedef struct mbedtls_timing_delay_context 80 { 81 struct mbedtls_timing_hr_time timer; 82 uint32_t int_ms; 83 uint32_t fin_ms; 84 } mbedtls_timing_delay_context; 85 86 #else /* MBEDTLS_TIMING_ALT */ 87 #include "timing_alt.h" 88 #endif /* MBEDTLS_TIMING_ALT */ 89 90 extern volatile int mbedtls_timing_alarmed; 91 92 /** 93 * \brief Return the CPU cycle counter value 94 * 95 * \warning This is only a best effort! Do not rely on this! 96 * In particular, it is known to be unreliable on virtual 97 * machines. 98 * 99 * \note This value starts at an unspecified origin and 100 * may wrap around. 101 */ 102 unsigned long mbedtls_timing_hardclock( void ); 103 104 /** 105 * \brief Return the elapsed time in milliseconds 106 * 107 * \param val points to a timer structure 108 * \param reset If 0, query the elapsed time. Otherwise (re)start the timer. 109 * 110 * \return Elapsed time since the previous reset in ms. When 111 * restarting, this is always 0. 112 * 113 * \note To initialize a timer, call this function with reset=1. 114 * 115 * Determining the elapsed time and resetting the timer is not 116 * atomic on all platforms, so after the sequence 117 * `{ get_timer(1); ...; time1 = get_timer(1); ...; time2 = 118 * get_timer(0) }` the value time1+time2 is only approximately 119 * the delay since the first reset. 120 */ 121 unsigned long mbedtls_timing_get_timer( struct mbedtls_timing_hr_time *val, int reset ); 122 123 /** 124 * \brief Setup an alarm clock 125 * 126 * \param seconds delay before the "mbedtls_timing_alarmed" flag is set 127 * (must be >=0) 128 * 129 * \warning Only one alarm at a time is supported. In a threaded 130 * context, this means one for the whole process, not one per 131 * thread. 132 */ 133 void mbedtls_set_alarm( int seconds ); 134 135 /** 136 * \brief Set a pair of delays to watch 137 * (See \c mbedtls_timing_get_delay().) 138 * 139 * \param data Pointer to timing data. 140 * Must point to a valid \c mbedtls_timing_delay_context struct. 141 * \param int_ms First (intermediate) delay in milliseconds. 142 * The effect if int_ms > fin_ms is unspecified. 143 * \param fin_ms Second (final) delay in milliseconds. 144 * Pass 0 to cancel the current delay. 145 * 146 * \note To set a single delay, either use \c mbedtls_timing_set_timer 147 * directly or use this function with int_ms == fin_ms. 148 */ 149 void mbedtls_timing_set_delay( void *data, uint32_t int_ms, uint32_t fin_ms ); 150 151 /** 152 * \brief Get the status of delays 153 * (Memory helper: number of delays passed.) 154 * 155 * \param data Pointer to timing data 156 * Must point to a valid \c mbedtls_timing_delay_context struct. 157 * 158 * \return -1 if cancelled (fin_ms = 0), 159 * 0 if none of the delays are passed, 160 * 1 if only the intermediate delay is passed, 161 * 2 if the final delay is passed. 162 */ 163 int mbedtls_timing_get_delay( void *data ); 164 165 #if defined(MBEDTLS_SELF_TEST) 166 /** 167 * \brief Checkup routine 168 * 169 * \return 0 if successful, or 1 if a test failed 170 */ 171 int mbedtls_timing_self_test( int verbose ); 172 #endif 173 174 #ifdef __cplusplus 175 } 176 #endif 177 178 #endif /* timing.h */ 179