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