blob: cdfa7d69e5492bdceb66ee21932e03a7dc2a1add [file] [log] [blame]
Paul Bakker2466d932013-09-28 14:40:38 +02001/**
2 * \file threading.h
3 *
4 * \brief Threading abstraction layer
Darryl Greena40a1012018-01-05 15:33:17 +00005 */
6/*
Bence Szépkúti1e148272020-08-07 13:07:28 +02007 * Copyright The Mbed TLS Contributors
Dave Rodgman16799db2023-11-02 19:47:20 +00008 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
Paul Bakker2466d932013-09-28 14:40:38 +02009 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020010#ifndef MBEDTLS_THREADING_H
11#define MBEDTLS_THREADING_H
Mateusz Starzyk846f0212021-05-19 19:44:07 +020012#include "mbedtls/private_access.h"
Paul Bakker2466d932013-09-28 14:40:38 +020013
Bence Szépkútic662b362021-05-27 11:25:03 +020014#include "mbedtls/build_info.h"
Paul Bakker2466d932013-09-28 14:40:38 +020015
16#include <stdlib.h>
17
18#ifdef __cplusplus
19extern "C" {
20#endif
21
Gilles Peskined2971572021-07-26 18:48:10 +020022/** Bad input parameters to function. */
23#define MBEDTLS_ERR_THREADING_BAD_INPUT_DATA -0x001C
24/** Locking / unlocking / free failed with error code. */
25#define MBEDTLS_ERR_THREADING_MUTEX_ERROR -0x001E
Paul Bakker2466d932013-09-28 14:40:38 +020026
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020027#if defined(MBEDTLS_THREADING_PTHREAD)
Paul Bakker2466d932013-09-28 14:40:38 +020028#include <pthread.h>
Gilles Peskine449bd832023-01-11 14:50:10 +010029typedef struct mbedtls_threading_mutex_t {
Mateusz Starzyk846f0212021-05-19 19:44:07 +020030 pthread_mutex_t MBEDTLS_PRIVATE(mutex);
Paul Elliott5fa986c2023-11-10 14:05:09 +000031
Paul Elliott37746372023-11-12 19:05:57 +000032 /* WARNING - is_valid should only be accessed when holding the mutex lock in
33 * tests/src/threading_helpers.c, otherwise corruption can occur.
34 * is_valid will be 0 after a failed init or a free, and nonzero after a
35 * successful init. This field is for testing only and thus not considered
36 * part of the public API of Mbed TLS and may change without notice.*/
Mateusz Starzyk846f0212021-05-19 19:44:07 +020037 char MBEDTLS_PRIVATE(is_valid);
Paul Elliott5fa986c2023-11-10 14:05:09 +000038
Manuel Pégourié-Gonnard1e2eae02015-04-29 01:26:03 +020039} mbedtls_threading_mutex_t;
Paul Bakker2466d932013-09-28 14:40:38 +020040#endif
41
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020042#if defined(MBEDTLS_THREADING_ALT)
43/* You should define the mbedtls_threading_mutex_t type in your header */
Paul Bakker2466d932013-09-28 14:40:38 +020044#include "threading_alt.h"
45
46/**
47 * \brief Set your alternate threading implementation function
Manuel Pégourié-Gonnard944cfe82015-05-27 20:07:18 +020048 * pointers and initialize global mutexes. If used, this
49 * function must be called once in the main thread before any
Gilles Peskinee820c0a2023-08-03 17:45:20 +020050 * other Mbed TLS function is called, and
Manuel Pégourié-Gonnard944cfe82015-05-27 20:07:18 +020051 * mbedtls_threading_free_alt() must be called once in the main
Gilles Peskinee820c0a2023-08-03 17:45:20 +020052 * thread after all other Mbed TLS functions.
Paul Bakker2466d932013-09-28 14:40:38 +020053 *
Manuel Pégourié-Gonnard8f5fd312015-04-24 14:42:34 +020054 * \note mutex_init() and mutex_free() don't return a status code.
55 * If mutex_init() fails, it should leave its argument (the
56 * mutex) in a state such that mutex_lock() will fail when
57 * called with this argument.
58 *
Paul Bakker6838bd12013-09-30 13:56:38 +020059 * \param mutex_init the init function implementation
Paul Bakker2466d932013-09-28 14:40:38 +020060 * \param mutex_free the free function implementation
61 * \param mutex_lock the lock function implementation
62 * \param mutex_unlock the unlock function implementation
Paul Bakker2466d932013-09-28 14:40:38 +020063 */
Gilles Peskine449bd832023-01-11 14:50:10 +010064void mbedtls_threading_set_alt(void (*mutex_init)(mbedtls_threading_mutex_t *),
65 void (*mutex_free)(mbedtls_threading_mutex_t *),
66 int (*mutex_lock)(mbedtls_threading_mutex_t *),
67 int (*mutex_unlock)(mbedtls_threading_mutex_t *));
Manuel Pégourié-Gonnard944cfe82015-05-27 20:07:18 +020068
69/**
70 * \brief Free global mutexes.
71 */
Gilles Peskine449bd832023-01-11 14:50:10 +010072void mbedtls_threading_free_alt(void);
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020073#endif /* MBEDTLS_THREADING_ALT */
Paul Bakker2466d932013-09-28 14:40:38 +020074
Embedthis Software17ddff52015-09-10 11:45:13 -070075#if defined(MBEDTLS_THREADING_C)
Paul Bakker2466d932013-09-28 14:40:38 +020076/*
77 * The function pointers for mutex_init, mutex_free, mutex_ and mutex_unlock
Paul Bakker6838bd12013-09-30 13:56:38 +020078 *
79 * All these functions are expected to work or the result will be undefined.
Paul Bakker2466d932013-09-28 14:40:38 +020080 */
Gilles Peskine449bd832023-01-11 14:50:10 +010081extern void (*mbedtls_mutex_init)(mbedtls_threading_mutex_t *mutex);
82extern void (*mbedtls_mutex_free)(mbedtls_threading_mutex_t *mutex);
83extern int (*mbedtls_mutex_lock)(mbedtls_threading_mutex_t *mutex);
84extern int (*mbedtls_mutex_unlock)(mbedtls_threading_mutex_t *mutex);
Paul Bakker2466d932013-09-28 14:40:38 +020085
Manuel Pégourié-Gonnard944cfe82015-05-27 20:07:18 +020086/*
87 * Global mutexes
88 */
Gergely Budai13f7fb32017-08-23 14:23:58 +020089#if defined(MBEDTLS_FS_IO)
Manuel Pégourié-Gonnard944cfe82015-05-27 20:07:18 +020090extern mbedtls_threading_mutex_t mbedtls_threading_readdir_mutex;
Gergely Budai13f7fb32017-08-23 14:23:58 +020091#endif
Hanno Beckerd2ef2542018-09-06 14:53:25 +010092
Hanno Becker6a739782018-09-05 15:06:19 +010093#if defined(MBEDTLS_HAVE_TIME_DATE) && !defined(MBEDTLS_PLATFORM_GMTIME_R_ALT)
Hanno Beckerd2ef2542018-09-06 14:53:25 +010094/* This mutex may or may not be used in the default definition of
95 * mbedtls_platform_gmtime_r(), but in order to determine that,
96 * we need to check POSIX features, hence modify _POSIX_C_SOURCE.
97 * With the current approach, this declaration is orphaned, lacking
98 * an accompanying definition, in case mbedtls_platform_gmtime_r()
99 * doesn't need it, but that's not a problem. */
Andres Amaya Garciace6eebb2018-08-07 20:26:55 +0100100extern mbedtls_threading_mutex_t mbedtls_threading_gmtime_mutex;
Hanno Becker6a739782018-09-05 15:06:19 +0100101#endif /* MBEDTLS_HAVE_TIME_DATE && !MBEDTLS_PLATFORM_GMTIME_R_ALT */
Hanno Beckerd2ef2542018-09-06 14:53:25 +0100102
Paul Bakkere049ccd2016-05-10 16:17:27 +0100103#endif /* MBEDTLS_THREADING_C */
Manuel Pégourié-Gonnard944cfe82015-05-27 20:07:18 +0200104
Paul Bakker2466d932013-09-28 14:40:38 +0200105#ifdef __cplusplus
106}
107#endif
108
109#endif /* threading.h */