1/**
2 * \file threading_helpers.h
3 *
4 * \brief This file contains the prototypes of helper functions for the purpose
5 *        of testing threading.
6 */
7
8/*
9 *  Copyright The Mbed TLS Contributors
10 *  SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
11 */
12
13#ifndef THREADING_HELPERS_H
14#define THREADING_HELPERS_H
15
16#if defined MBEDTLS_THREADING_C
17
18#include "mbedtls/private_access.h"
19#include "mbedtls/build_info.h"
20
21/* Most fields of publicly available structs are private and are wrapped with
22 * MBEDTLS_PRIVATE macro. This define allows tests to access the private fields
23 * directly (without using the MBEDTLS_PRIVATE wrapper). */
24#define MBEDTLS_ALLOW_PRIVATE_ACCESS
25
26#define MBEDTLS_ERR_THREADING_THREAD_ERROR                 -0x001F
27
28#if defined(MBEDTLS_THREADING_PTHREAD)
29#include <pthread.h>
30#endif /* MBEDTLS_THREADING_PTHREAD */
31
32#if defined(MBEDTLS_THREADING_ALT)
33/* You should define the mbedtls_test_thread_t type in your header */
34#include "threading_alt.h"
35
36/**
37 * \brief                   Set your alternate threading implementation
38 *                          function pointers for test threads. If used, this
39 *                          function must be called once in the main thread
40 *                          before any other MbedTLS function is called.
41 *
42 * \note                    These functions are part of the testing API only and
43 *                          thus not considered part of the public API of
44 *                          MbedTLS and thus may change without notice.
45 *
46 * \param thread_create     The thread create function implementation.
47 * \param thread_join       The thread join function implementation.
48
49 */
50void mbedtls_test_thread_set_alt(int (*thread_create)(mbedtls_test_thread_t *thread,
51                                                      void *(*thread_func)(
52                                                          void *),
53                                                      void *thread_data),
54                                 int (*thread_join)(mbedtls_test_thread_t *thread));
55
56#else /* MBEDTLS_THREADING_ALT*/
57
58typedef struct mbedtls_test_thread_t {
59
60#if defined(MBEDTLS_THREADING_PTHREAD)
61    pthread_t MBEDTLS_PRIVATE(thread);
62#else /* MBEDTLS_THREADING_PTHREAD */
63    /* Make sure this struct is always non-empty */
64    unsigned dummy;
65#endif
66
67} mbedtls_test_thread_t;
68
69#endif /* MBEDTLS_THREADING_ALT*/
70
71/**
72 * \brief                   The function pointers for thread create and thread
73 *                          join.
74 *
75 * \note                    These functions are part of the testing API only
76 *                          and thus not considered part of the public API of
77 *                          MbedTLS and thus may change without notice.
78 *
79 * \note                    All these functions are expected to work or
80 *                          the result will be undefined.
81 */
82extern int (*mbedtls_test_thread_create)(mbedtls_test_thread_t *thread,
83                                         void *(*thread_func)(void *), void *thread_data);
84extern int (*mbedtls_test_thread_join)(mbedtls_test_thread_t *thread);
85
86#if defined(MBEDTLS_THREADING_PTHREAD) && defined(MBEDTLS_TEST_HOOKS)
87#define MBEDTLS_TEST_MUTEX_USAGE
88#endif
89
90#if defined(MBEDTLS_TEST_MUTEX_USAGE)
91/**
92 *  Activate the mutex usage verification framework. See threading_helpers.c for
93 *  information.
94 */
95void mbedtls_test_mutex_usage_init(void);
96
97/**
98 *  Deactivate the mutex usage verification framework. See threading_helpers.c
99 *  for information.
100 */
101void mbedtls_test_mutex_usage_end(void);
102
103/**
104 *  Call this function after executing a test case to check for mutex usage
105 * errors.
106 */
107void mbedtls_test_mutex_usage_check(void);
108#endif /* MBEDTLS_TEST_MUTEX_USAGE */
109
110#endif /* MBEDTLS_THREADING_C */
111
112#endif /* THREADING_HELPERS_H */
113