1 /** Mutex usage verification framework. */
2
3 /*
4 * Copyright The Mbed TLS Contributors
5 * SPDX-License-Identifier: Apache-2.0
6 *
7 * Licensed under the Apache License, Version 2.0 (the "License"); you may
8 * not use this file except in compliance with the License.
9 * You may obtain a copy of the License at
10 *
11 * http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
15 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
18 */
19
20 #include <test/helpers.h>
21 #include <test/macros.h>
22
23 #if defined(MBEDTLS_TEST_MUTEX_USAGE)
24
25 #include "mbedtls/threading.h"
26
27 /** Mutex usage verification framework.
28 *
29 * The mutex usage verification code below aims to detect bad usage of
30 * Mbed TLS's mutex abstraction layer at runtime. Note that this is solely
31 * about the use of the mutex itself, not about checking whether the mutex
32 * correctly protects whatever it is supposed to protect.
33 *
34 * The normal usage of a mutex is:
35 * ```
36 * digraph mutex_states {
37 * "UNINITIALIZED"; // the initial state
38 * "IDLE";
39 * "FREED";
40 * "LOCKED";
41 * "UNINITIALIZED" -> "IDLE" [label="init"];
42 * "FREED" -> "IDLE" [label="init"];
43 * "IDLE" -> "LOCKED" [label="lock"];
44 * "LOCKED" -> "IDLE" [label="unlock"];
45 * "IDLE" -> "FREED" [label="free"];
46 * }
47 * ```
48 *
49 * All bad transitions that can be unambiguously detected are reported.
50 * An attempt to use an uninitialized mutex cannot be detected in general
51 * since the memory content may happen to denote a valid state. For the same
52 * reason, a double init cannot be detected.
53 * All-bits-zero is the state of a freed mutex, which is distinct from an
54 * initialized mutex, so attempting to use zero-initialized memory as a mutex
55 * without calling the init function is detected.
56 *
57 * The framework attempts to detect missing calls to init and free by counting
58 * calls to init and free. If there are more calls to init than free, this
59 * means that a mutex is not being freed somewhere, which is a memory leak
60 * on platforms where a mutex consumes resources other than the
61 * mbedtls_threading_mutex_t object itself. If there are more calls to free
62 * than init, this indicates a missing init, which is likely to be detected
63 * by an attempt to lock the mutex as well. A limitation of this framework is
64 * that it cannot detect scenarios where there is exactly the same number of
65 * calls to init and free but the calls don't match. A bug like this is
66 * unlikely to happen uniformly throughout the whole test suite though.
67 *
68 * If an error is detected, this framework will report what happened and the
69 * test case will be marked as failed. Unfortunately, the error report cannot
70 * indicate the exact location of the problematic call. To locate the error,
71 * use a debugger and set a breakpoint on mbedtls_test_mutex_usage_error().
72 */
73 enum value_of_mutex_is_valid_field
74 {
75 /* Potential values for the is_valid field of mbedtls_threading_mutex_t.
76 * Note that MUTEX_FREED must be 0 and MUTEX_IDLE must be 1 for
77 * compatibility with threading_mutex_init_pthread() and
78 * threading_mutex_free_pthread(). MUTEX_LOCKED could be any nonzero
79 * value. */
80 MUTEX_FREED = 0, //!< Set by threading_mutex_free_pthread
81 MUTEX_IDLE = 1, //!< Set by threading_mutex_init_pthread and by our unlock
82 MUTEX_LOCKED = 2, //!< Set by our lock
83 };
84
85 typedef struct
86 {
87 void (*init)( mbedtls_threading_mutex_t * );
88 void (*free)( mbedtls_threading_mutex_t * );
89 int (*lock)( mbedtls_threading_mutex_t * );
90 int (*unlock)( mbedtls_threading_mutex_t * );
91 } mutex_functions_t;
92 static mutex_functions_t mutex_functions;
93
94 /** The total number of calls to mbedtls_mutex_init(), minus the total number
95 * of calls to mbedtls_mutex_free().
96 *
97 * Reset to 0 after each test case.
98 */
99 static int live_mutexes;
100
mbedtls_test_mutex_usage_error(mbedtls_threading_mutex_t * mutex,const char * msg)101 static void mbedtls_test_mutex_usage_error( mbedtls_threading_mutex_t *mutex,
102 const char *msg )
103 {
104 (void) mutex;
105 if( mbedtls_test_info.mutex_usage_error == NULL )
106 mbedtls_test_info.mutex_usage_error = msg;
107 mbedtls_fprintf( stdout, "[mutex: %s] ", msg );
108 /* Don't mark the test as failed yet. This way, if the test fails later
109 * for a functional reason, the test framework will report the message
110 * and location for this functional reason. If the test passes,
111 * mbedtls_test_mutex_usage_check() will mark it as failed. */
112 }
113
mbedtls_test_wrap_mutex_init(mbedtls_threading_mutex_t * mutex)114 static void mbedtls_test_wrap_mutex_init( mbedtls_threading_mutex_t *mutex )
115 {
116 mutex_functions.init( mutex );
117 if( mutex->is_valid )
118 ++live_mutexes;
119 }
120
mbedtls_test_wrap_mutex_free(mbedtls_threading_mutex_t * mutex)121 static void mbedtls_test_wrap_mutex_free( mbedtls_threading_mutex_t *mutex )
122 {
123 switch( mutex->is_valid )
124 {
125 case MUTEX_FREED:
126 mbedtls_test_mutex_usage_error( mutex, "free without init or double free" );
127 break;
128 case MUTEX_IDLE:
129 /* Do nothing. The underlying free function will reset is_valid
130 * to 0. */
131 break;
132 case MUTEX_LOCKED:
133 mbedtls_test_mutex_usage_error( mutex, "free without unlock" );
134 break;
135 default:
136 mbedtls_test_mutex_usage_error( mutex, "corrupted state" );
137 break;
138 }
139 if( mutex->is_valid )
140 --live_mutexes;
141 mutex_functions.free( mutex );
142 }
143
mbedtls_test_wrap_mutex_lock(mbedtls_threading_mutex_t * mutex)144 static int mbedtls_test_wrap_mutex_lock( mbedtls_threading_mutex_t *mutex )
145 {
146 int ret = mutex_functions.lock( mutex );
147 switch( mutex->is_valid )
148 {
149 case MUTEX_FREED:
150 mbedtls_test_mutex_usage_error( mutex, "lock without init" );
151 break;
152 case MUTEX_IDLE:
153 if( ret == 0 )
154 mutex->is_valid = 2;
155 break;
156 case MUTEX_LOCKED:
157 mbedtls_test_mutex_usage_error( mutex, "double lock" );
158 break;
159 default:
160 mbedtls_test_mutex_usage_error( mutex, "corrupted state" );
161 break;
162 }
163 return( ret );
164 }
165
mbedtls_test_wrap_mutex_unlock(mbedtls_threading_mutex_t * mutex)166 static int mbedtls_test_wrap_mutex_unlock( mbedtls_threading_mutex_t *mutex )
167 {
168 int ret = mutex_functions.unlock( mutex );
169 switch( mutex->is_valid )
170 {
171 case MUTEX_FREED:
172 mbedtls_test_mutex_usage_error( mutex, "unlock without init" );
173 break;
174 case MUTEX_IDLE:
175 mbedtls_test_mutex_usage_error( mutex, "unlock without lock" );
176 break;
177 case MUTEX_LOCKED:
178 if( ret == 0 )
179 mutex->is_valid = MUTEX_IDLE;
180 break;
181 default:
182 mbedtls_test_mutex_usage_error( mutex, "corrupted state" );
183 break;
184 }
185 return( ret );
186 }
187
mbedtls_test_mutex_usage_init(void)188 void mbedtls_test_mutex_usage_init( void )
189 {
190 mutex_functions.init = mbedtls_mutex_init;
191 mutex_functions.free = mbedtls_mutex_free;
192 mutex_functions.lock = mbedtls_mutex_lock;
193 mutex_functions.unlock = mbedtls_mutex_unlock;
194 mbedtls_mutex_init = &mbedtls_test_wrap_mutex_init;
195 mbedtls_mutex_free = &mbedtls_test_wrap_mutex_free;
196 mbedtls_mutex_lock = &mbedtls_test_wrap_mutex_lock;
197 mbedtls_mutex_unlock = &mbedtls_test_wrap_mutex_unlock;
198 }
199
mbedtls_test_mutex_usage_check(void)200 void mbedtls_test_mutex_usage_check( void )
201 {
202 if( live_mutexes != 0 )
203 {
204 /* A positive number (more init than free) means that a mutex resource
205 * is leaking (on platforms where a mutex consumes more than the
206 * mbedtls_threading_mutex_t object itself). The rare case of a
207 * negative number means a missing init somewhere. */
208 mbedtls_fprintf( stdout, "[mutex: %d leaked] ", live_mutexes );
209 live_mutexes = 0;
210 if( mbedtls_test_info.mutex_usage_error == NULL )
211 mbedtls_test_info.mutex_usage_error = "missing free";
212 }
213 if( mbedtls_test_info.mutex_usage_error != NULL &&
214 mbedtls_test_info.result != MBEDTLS_TEST_RESULT_FAILED )
215 {
216 /* Functionally, the test passed. But there was a mutex usage error,
217 * so mark the test as failed after all. */
218 mbedtls_test_fail( "Mutex usage error", __LINE__, __FILE__ );
219 }
220 mbedtls_test_info.mutex_usage_error = NULL;
221 }
222
223 #endif /* MBEDTLS_TEST_MUTEX_USAGE */
224