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/threading_helpers.h>
10#include <test/macros.h>
11
12#include "mbedtls/threading.h"
13
14#if defined(MBEDTLS_THREADING_C)
15
16#if defined(MBEDTLS_THREADING_PTHREAD)
17
18static int threading_thread_create_pthread(mbedtls_test_thread_t *thread, void *(*thread_func)(
19                                               void *), void *thread_data)
20{
21    if (thread == NULL || thread_func == NULL) {
22        return MBEDTLS_ERR_THREADING_BAD_INPUT_DATA;
23    }
24
25    if (pthread_create(&thread->thread, NULL, thread_func, thread_data)) {
26        return MBEDTLS_ERR_THREADING_THREAD_ERROR;
27    }
28
29    return 0;
30}
31
32static int threading_thread_join_pthread(mbedtls_test_thread_t *thread)
33{
34    if (thread == NULL) {
35        return MBEDTLS_ERR_THREADING_BAD_INPUT_DATA;
36    }
37
38    if (pthread_join(thread->thread, NULL) != 0) {
39        return MBEDTLS_ERR_THREADING_THREAD_ERROR;
40    }
41
42    return 0;
43}
44
45int (*mbedtls_test_thread_create)(mbedtls_test_thread_t *thread, void *(*thread_func)(void *),
46                                  void *thread_data) = threading_thread_create_pthread;
47int (*mbedtls_test_thread_join)(mbedtls_test_thread_t *thread) = threading_thread_join_pthread;
48
49#endif /* MBEDTLS_THREADING_PTHREAD */
50
51#if defined(MBEDTLS_THREADING_ALT)
52
53static int threading_thread_create_fail(mbedtls_test_thread_t *thread,
54                                        void *(*thread_func)(void *),
55                                        void *thread_data)
56{
57    (void) thread;
58    (void) thread_func;
59    (void) thread_data;
60
61    return MBEDTLS_ERR_THREADING_BAD_INPUT_DATA;
62}
63
64static int threading_thread_join_fail(mbedtls_test_thread_t *thread)
65{
66    (void) thread;
67
68    return MBEDTLS_ERR_THREADING_BAD_INPUT_DATA;
69}
70
71int (*mbedtls_test_thread_create)(mbedtls_test_thread_t *thread, void *(*thread_func)(void *),
72                                  void *thread_data) = threading_thread_create_fail;
73int (*mbedtls_test_thread_join)(mbedtls_test_thread_t *thread) = threading_thread_join_fail;
74
75#endif /* MBEDTLS_THREADING_ALT */
76
77#if defined(MBEDTLS_TEST_MUTEX_USAGE)
78
79#include "mbedtls/threading.h"
80
81/** Mutex usage verification framework.
82 *
83 * The mutex usage verification code below aims to detect bad usage of
84 * Mbed TLS's mutex abstraction layer at runtime. Note that this is solely
85 * about the use of the mutex itself, not about checking whether the mutex
86 * correctly protects whatever it is supposed to protect.
87 *
88 * The normal usage of a mutex is:
89 * ```
90 * digraph mutex_states {
91 *   "UNINITIALIZED"; // the initial state
92 *   "IDLE";
93 *   "FREED";
94 *   "LOCKED";
95 *   "UNINITIALIZED" -> "IDLE" [label="init"];
96 *   "FREED" -> "IDLE" [label="init"];
97 *   "IDLE" -> "LOCKED" [label="lock"];
98 *   "LOCKED" -> "IDLE" [label="unlock"];
99 *   "IDLE" -> "FREED" [label="free"];
100 * }
101 * ```
102 *
103 * All bad transitions that can be unambiguously detected are reported.
104 * An attempt to use an uninitialized mutex cannot be detected in general
105 * since the memory content may happen to denote a valid state. For the same
106 * reason, a double init cannot be detected.
107 * All-bits-zero is the state of a freed mutex, which is distinct from an
108 * initialized mutex, so attempting to use zero-initialized memory as a mutex
109 * without calling the init function is detected.
110 *
111 * The framework attempts to detect missing calls to init and free by counting
112 * calls to init and free. If there are more calls to init than free, this
113 * means that a mutex is not being freed somewhere, which is a memory leak
114 * on platforms where a mutex consumes resources other than the
115 * mbedtls_threading_mutex_t object itself. If there are more calls to free
116 * than init, this indicates a missing init, which is likely to be detected
117 * by an attempt to lock the mutex as well. A limitation of this framework is
118 * that it cannot detect scenarios where there is exactly the same number of
119 * calls to init and free but the calls don't match. A bug like this is
120 * unlikely to happen uniformly throughout the whole test suite though.
121 *
122 * If an error is detected, this framework will report what happened and the
123 * test case will be marked as failed. Unfortunately, the error report cannot
124 * indicate the exact location of the problematic call. To locate the error,
125 * use a debugger and set a breakpoint on mbedtls_test_mutex_usage_error().
126 */
127enum value_of_mutex_state_field {
128    /* Potential values for the state field of mbedtls_threading_mutex_t.
129     * Note that MUTEX_FREED must be 0 and MUTEX_IDLE must be 1 for
130     * compatibility with threading_mutex_init_pthread() and
131     * threading_mutex_free_pthread(). MUTEX_LOCKED could be any nonzero
132     * value. */
133    MUTEX_FREED = 0, //! < Set by mbedtls_test_wrap_mutex_free
134    MUTEX_IDLE = 1, //! < Set by mbedtls_test_wrap_mutex_init and by mbedtls_test_wrap_mutex_unlock
135    MUTEX_LOCKED = 2, //! < Set by mbedtls_test_wrap_mutex_lock
136};
137
138typedef struct {
139    void (*init)(mbedtls_threading_mutex_t *);
140    void (*free)(mbedtls_threading_mutex_t *);
141    int (*lock)(mbedtls_threading_mutex_t *);
142    int (*unlock)(mbedtls_threading_mutex_t *);
143} mutex_functions_t;
144static mutex_functions_t mutex_functions;
145
146/**
147 *  The mutex used to guard live_mutexes below and access to the status variable
148 *  in every mbedtls_threading_mutex_t.
149 *  Note that we are not reporting any errors when locking and unlocking this
150 *  mutex. This is for a couple of reasons:
151 *
152 *  1. We have no real way of reporting any errors with this mutex - we cannot
153 *  report it back to the caller, as the failure was not that of the mutex
154 *  passed in. We could fail the test, but again this would indicate a problem
155 *  with the test code that did not exist.
156 *
157 *  2. Any failure to lock is unlikely to be intermittent, and will thus not
158 *  give false test results - the overall result would be to turn off the
159 *  testing. This is not a situation that is likely to happen with normal
160 *  testing and we still have TSan to fall back on should this happen.
161 */
162mbedtls_threading_mutex_t mbedtls_test_mutex_mutex;
163
164/**
165 *  The total number of calls to mbedtls_mutex_init(), minus the total number
166 *  of calls to mbedtls_mutex_free().
167 *
168 *  Do not read or write without holding mbedtls_test_mutex_mutex (above). Reset
169 *  to 0 after each test case.
170 */
171static int live_mutexes;
172
173static void mbedtls_test_mutex_usage_error(mbedtls_threading_mutex_t *mutex,
174                                           const char *msg)
175{
176    (void) mutex;
177
178    mbedtls_test_set_mutex_usage_error(msg);
179    mbedtls_fprintf(stdout, "[mutex: %s] ", msg);
180    /* Don't mark the test as failed yet. This way, if the test fails later
181     * for a functional reason, the test framework will report the message
182     * and location for this functional reason. If the test passes,
183     * mbedtls_test_mutex_usage_check() will mark it as failed. */
184}
185
186static int mbedtls_test_mutex_can_test(mbedtls_threading_mutex_t *mutex)
187{
188    /* If we attempt to run tests on this mutex then we are going to run into a
189     * couple of problems:
190     * 1. If any test on this mutex fails, we are going to deadlock when
191     * reporting that failure, as we already hold the mutex at that point.
192     * 2. Given the 'global' position of the initialization and free of this
193     * mutex, it will be shown as leaked on the first test run. */
194    if (mutex == mbedtls_test_get_info_mutex()) {
195        return 0;
196    }
197
198    return 1;
199}
200
201static void mbedtls_test_wrap_mutex_init(mbedtls_threading_mutex_t *mutex)
202{
203    mutex_functions.init(mutex);
204
205    if (mbedtls_test_mutex_can_test(mutex)) {
206        if (mutex_functions.lock(&mbedtls_test_mutex_mutex) == 0) {
207            mutex->state = MUTEX_IDLE;
208            ++live_mutexes;
209
210            mutex_functions.unlock(&mbedtls_test_mutex_mutex);
211        }
212    }
213}
214
215static void mbedtls_test_wrap_mutex_free(mbedtls_threading_mutex_t *mutex)
216{
217    if (mbedtls_test_mutex_can_test(mutex)) {
218        if (mutex_functions.lock(&mbedtls_test_mutex_mutex) == 0) {
219
220            switch (mutex->state) {
221                case MUTEX_FREED:
222                    mbedtls_test_mutex_usage_error(mutex, "free without init or double free");
223                    break;
224                case MUTEX_IDLE:
225                    mutex->state = MUTEX_FREED;
226                    --live_mutexes;
227                    break;
228                case MUTEX_LOCKED:
229                    mbedtls_test_mutex_usage_error(mutex, "free without unlock");
230                    break;
231                default:
232                    mbedtls_test_mutex_usage_error(mutex, "corrupted state");
233                    break;
234            }
235
236            mutex_functions.unlock(&mbedtls_test_mutex_mutex);
237        }
238    }
239
240    mutex_functions.free(mutex);
241}
242
243static int mbedtls_test_wrap_mutex_lock(mbedtls_threading_mutex_t *mutex)
244{
245    /* Lock the passed in mutex first, so that the only way to change the state
246     * is to hold the passed in and internal mutex - otherwise we create a race
247     * condition. */
248    int ret = mutex_functions.lock(mutex);
249
250    if (mbedtls_test_mutex_can_test(mutex)) {
251        if (mutex_functions.lock(&mbedtls_test_mutex_mutex) == 0) {
252            switch (mutex->state) {
253                case MUTEX_FREED:
254                    mbedtls_test_mutex_usage_error(mutex, "lock without init");
255                    break;
256                case MUTEX_IDLE:
257                    if (ret == 0) {
258                        mutex->state = MUTEX_LOCKED;
259                    }
260                    break;
261                case MUTEX_LOCKED:
262                    mbedtls_test_mutex_usage_error(mutex, "double lock");
263                    break;
264                default:
265                    mbedtls_test_mutex_usage_error(mutex, "corrupted state");
266                    break;
267            }
268
269            mutex_functions.unlock(&mbedtls_test_mutex_mutex);
270        }
271    }
272
273    return ret;
274}
275
276static int mbedtls_test_wrap_mutex_unlock(mbedtls_threading_mutex_t *mutex)
277{
278    /* Lock the internal mutex first and change state, so that the only way to
279     * change the state is to hold the passed in and internal mutex - otherwise
280     * we create a race condition. */
281    if (mbedtls_test_mutex_can_test(mutex)) {
282        if (mutex_functions.lock(&mbedtls_test_mutex_mutex) == 0) {
283            switch (mutex->state) {
284                case MUTEX_FREED:
285                    mbedtls_test_mutex_usage_error(mutex, "unlock without init");
286                    break;
287                case MUTEX_IDLE:
288                    mbedtls_test_mutex_usage_error(mutex, "unlock without lock");
289                    break;
290                case MUTEX_LOCKED:
291                    mutex->state = MUTEX_IDLE;
292                    break;
293                default:
294                    mbedtls_test_mutex_usage_error(mutex, "corrupted state");
295                    break;
296            }
297            mutex_functions.unlock(&mbedtls_test_mutex_mutex);
298        }
299    }
300
301    return mutex_functions.unlock(mutex);
302}
303
304void mbedtls_test_mutex_usage_init(void)
305{
306    mutex_functions.init = mbedtls_mutex_init;
307    mutex_functions.free = mbedtls_mutex_free;
308    mutex_functions.lock = mbedtls_mutex_lock;
309    mutex_functions.unlock = mbedtls_mutex_unlock;
310    mbedtls_mutex_init = &mbedtls_test_wrap_mutex_init;
311    mbedtls_mutex_free = &mbedtls_test_wrap_mutex_free;
312    mbedtls_mutex_lock = &mbedtls_test_wrap_mutex_lock;
313    mbedtls_mutex_unlock = &mbedtls_test_wrap_mutex_unlock;
314
315    mutex_functions.init(&mbedtls_test_mutex_mutex);
316}
317
318void mbedtls_test_mutex_usage_check(void)
319{
320    if (mutex_functions.lock(&mbedtls_test_mutex_mutex) == 0) {
321        if (live_mutexes != 0) {
322            /* A positive number (more init than free) means that a mutex resource
323             * is leaking (on platforms where a mutex consumes more than the
324             * mbedtls_threading_mutex_t object itself). The (hopefully) rare
325             * case of a negative number means a missing init somewhere. */
326            mbedtls_fprintf(stdout, "[mutex: %d leaked] ", live_mutexes);
327            live_mutexes = 0;
328            mbedtls_test_set_mutex_usage_error("missing free");
329        }
330        if (mbedtls_test_get_mutex_usage_error() != NULL &&
331            mbedtls_test_get_result() != MBEDTLS_TEST_RESULT_FAILED) {
332            /* Functionally, the test passed. But there was a mutex usage error,
333             * so mark the test as failed after all. */
334            mbedtls_test_fail("Mutex usage error", __LINE__, __FILE__);
335        }
336        mbedtls_test_set_mutex_usage_error(NULL);
337
338        mutex_functions.unlock(&mbedtls_test_mutex_mutex);
339    }
340}
341
342void mbedtls_test_mutex_usage_end(void)
343{
344    mbedtls_mutex_init = mutex_functions.init;
345    mbedtls_mutex_free = mutex_functions.free;
346    mbedtls_mutex_lock = mutex_functions.lock;
347    mbedtls_mutex_unlock = mutex_functions.unlock;
348
349    mutex_functions.free(&mbedtls_test_mutex_mutex);
350}
351
352#endif /* MBEDTLS_TEST_MUTEX_USAGE */
353
354#endif /* MBEDTLS_THREADING_C */
355