threading.h File Reference

Threading abstraction layer. More...

#include "mbedtls/private_access.h"
#include "tf-psa-crypto/build_info.h"
#include "mbedtls/compat-3-crypto.h"
#include <stdlib.h>
#include <pthread.h>
#include "threading_alt.h"

Include dependency graph for threading.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	mbedtls_threading_mutex_t
struct	mbedtls_threading_condition_variable_t

Macros
#define	MBEDTLS_ERR_THREADING_USAGE_ERROR   -0x001E
#define	MBEDTLS_ERR_THREADING_MUTEX_ERROR   MBEDTLS_ERR_THREADING_USAGE_ERROR

Typedefs
typedef pthread_mutex_t	mbedtls_platform_mutex_t
typedef pthread_cond_t	mbedtls_platform_condition_variable_t
typedef struct mbedtls_threading_mutex_t	mbedtls_threading_mutex_t
typedef struct mbedtls_threading_condition_variable_t	mbedtls_threading_condition_variable_t

Functions
void	mbedtls_threading_set_alt (int(*mutex_init)(mbedtls_platform_mutex_t *), void(*mutex_destroy)(mbedtls_platform_mutex_t *), int(*mutex_lock)(mbedtls_platform_mutex_t *), int(*mutex_unlock)(mbedtls_platform_mutex_t *), int(*cond_init)(mbedtls_platform_condition_variable_t *), void(*cond_destroy)(mbedtls_platform_condition_variable_t *), int(*cond_signal)(mbedtls_platform_condition_variable_t *), int(*cond_broadcast)(mbedtls_platform_condition_variable_t *), int(*cond_wait)(mbedtls_platform_condition_variable_t *, mbedtls_platform_mutex_t *))
	Set your alternate threading implementation function pointers and initialize global mutexes. If used, this function must be called once in the main thread before any other Mbed TLS function is called, and mbedtls_threading_free_alt() must be called once in the main thread after all other Mbed TLS functions. More...
void	mbedtls_threading_free_alt (void)
	Free global mutexes. More...
void	mbedtls_mutex_init (mbedtls_threading_mutex_t *mutex)
void	mbedtls_mutex_free (mbedtls_threading_mutex_t *mutex)
int	mbedtls_mutex_lock (mbedtls_threading_mutex_t *mutex)
int	mbedtls_mutex_unlock (mbedtls_threading_mutex_t *mutex)
int	mbedtls_condition_variable_init (mbedtls_threading_condition_variable_t *cond)
void	mbedtls_condition_variable_free (mbedtls_threading_condition_variable_t *cond)
int	mbedtls_condition_variable_signal (mbedtls_threading_condition_variable_t *cond)
int	mbedtls_condition_variable_broadcast (mbedtls_threading_condition_variable_t *cond)
int	mbedtls_condition_variable_wait (mbedtls_threading_condition_variable_t *cond, mbedtls_threading_mutex_t *mutex)

Variables
mbedtls_threading_mutex_t	mbedtls_threading_readdir_mutex

Detailed Description

Threading abstraction layer.

Definition in file threading.h.

Macro Definition Documentation

#define MBEDTLS_ERR_THREADING_MUTEX_ERROR   MBEDTLS_ERR_THREADING_USAGE_ERROR

A historical alias for MBEDTLS_ERR_THREADING_USAGE_ERROR.

Definition at line 33 of file threading.h.

#define MBEDTLS_ERR_THREADING_USAGE_ERROR   -0x001E

Detected error in mutex or condition variable usage.

Note that depending on the platform, many usage errors of synchronization primitives have undefined behavior. But where it is practical to detect usage errors at runtime, mutex and condition primitives can return this error code.

Definition at line 30 of file threading.h.

Typedef Documentation

typedef pthread_cond_t mbedtls_platform_condition_variable_t

Definition at line 40 of file threading.h.

typedef pthread_mutex_t mbedtls_platform_mutex_t

Definition at line 39 of file threading.h.

typedef struct mbedtls_threading_condition_variable_t mbedtls_threading_condition_variable_t

typedef struct mbedtls_threading_mutex_t mbedtls_threading_mutex_t

Function Documentation

int mbedtls_condition_variable_broadcast

(

mbedtls_threading_condition_variable_t *

cond

)

Wake up all threads that are waiting on the given condition variable.

Note

The behavior is undefined if:

• cond has not been initialized with mbedtls_condition_variable_init(), or has already been freed with mbedtls_condition_variable_free().

Parameters

cond	The condition variable to signal.

Return values

0	Success.
MBEDTLS_ERR_THREADING_USAGE_ERROR	A usage error was detected. Note that depending on the platform, a condition variable usage error may result in a deadlock, a crash or other undesirable behavior instead of returning an error.
PSA_ERROR_BAD_STATE	The compilation option MBEDTLS_THREADING_ALT is enabled, and mbedtls_threading_set_alt() has not been called.

void mbedtls_condition_variable_free

(

mbedtls_threading_condition_variable_t *

cond

)

Destroy a condition variable.

After this function returns, you may call mbedtls_condition_variable_init() again on cond.

Note

The behavior is undefined if:

• cond has not been initialized with mbedtls_condition_variable_init();
• any function is called concurrently on the same object from another thread.

Parameters

cond	The condition variable to destroy.

int mbedtls_condition_variable_init

(

mbedtls_threading_condition_variable_t *

cond

)

Initialize a condition variable.

Note

The behavior is undefined if:

• cond is already initialized;
• this function is called concurrently on the same object from multiple threads.

Parameters

cond	The condition variable to initialize.

Return values

0	Success.
MBEDTLS_ERR_THREADING_USAGE_ERROR	The condition variable is already initialized (on platforms where this can be detected), or an unpecified error occurred.
PSA_ERROR_INSUFFICIENT_MEMORY	There were insufficient resources to initialize the object.
PSA_ERROR_BAD_STATE	The compilation option MBEDTLS_THREADING_ALT is enabled, and mbedtls_threading_set_alt() has not been called.

int mbedtls_condition_variable_signal

(

mbedtls_threading_condition_variable_t *

cond

)

Wake up one thread that is waiting on the given condition variable.

Do nothing, successfully, if no thread is waiting.

Note

The behavior is undefined if:

• cond has not been initialized with mbedtls_condition_variable_init(), or has already been freed with mbedtls_condition_variable_free().

Parameters

cond	The condition variable to signal.

Return values

0	Success.
MBEDTLS_ERR_THREADING_USAGE_ERROR	A usage error was detected. Note that depending on the platform, a condition variable usage error may result in a deadlock, a crash or other undesirable behavior instead of returning an error.
PSA_ERROR_BAD_STATE	The compilation option MBEDTLS_THREADING_ALT is enabled, and mbedtls_threading_set_alt() has not been called.

int mbedtls_condition_variable_wait	(	mbedtls_threading_condition_variable_t *	cond,
		mbedtls_threading_mutex_t *	mutex
	)

Wait for a wakeup signal on a condition variable.

On entry, this function atomically unlocks mutex and blocks until another thread calls mbedtls_condition_variable_signal() or mbedtls_condition_variable_broadcast() on cond.

Before returning, this function locks mutex.

Note

On some platforms, it is possible for this function to stop blocking even if no signal is raised on cond (spurious wakeup).

The behavior is undefined if:

• mutex has not been initialized with mbedtls_mutex_init(), or has already been freed with mbedtls_mutex_free();
• cond has not been initialized with mbedtls_condition_variable_init(), or has already been freed with mbedtls_condition_variable_free();
  • mutex is not currently locked by the calling thread.

Parameters

cond	The condition variable to wait on.
mutex	The mutex to unlock and re-lock. It must currently be locked by the calling thread.

Return values

0	Success.
MBEDTLS_ERR_THREADING_USAGE_ERROR	A usage error was detected. Note that depending on the platform, a condition variable usage error may result in a deadlock, a crash or other undesirable behavior instead of returning an error.
PSA_ERROR_BAD_STATE	The compilation option MBEDTLS_THREADING_ALT is enabled, and mbedtls_threading_set_alt() has not been called.

void mbedtls_mutex_free

(

mbedtls_threading_mutex_t *

mutex

)

Destroy a mutex.

After this function returns, you may call mbedtls_mutex_init() again on mutex.

Note

The behavior is undefined if:

• any function is called concurrently on the same object from another thread;
• mbedtls_mutex_init() has never been called on the object, and it is not all-bits-zero or {0};
• mutex is locked.

This function does nothing if:

• mutex is all-bits-zero or {0}.
• The last function called on mutex is mbedtls_mutex_free() (i.e. a double free is safe).

Parameters

mutex

The mutex to destroy.

void mbedtls_mutex_init

(

mbedtls_threading_mutex_t *

mutex

)

Initialize a mutex (mutual exclusion lock).

You must call this function on a mutex object before using it for any purpose.

Note

This function may fail internally, but for historical reasons, it does not return a value. If the mutex initialization fails internally, mbedtls_mutex_free() will still work normally, and all other mutex functions will fail safely with a nonzero return code.

The behavior is undefined if:

• mutex is already initialized;
• this function is called concurrently on the same object from multiple threads.

Parameters

mutex

The mutex to initialize.

int mbedtls_mutex_lock

(

mbedtls_threading_mutex_t *

mutex

)

Lock a mutex.

It must not be already locked by the calling thread (mutexes are not recursive).

Note

The behavior is undefined if:

• mutex has not been initialized with mbedtls_mutex_init(), or has already been freed with mbedtls_mutex_free();
• mutex is already locked by the same thread.

Parameters

mutex

The mutex to lock.

Return values

0	Success.
MBEDTLS_ERR_THREADING_USAGE_ERROR	mbedtls_mutex_init() failed, or a mutex usage error was detected. Note that depending on the platform, a mutex usage error may result in a deadlock, a crash or other undesirable behavior instead of returning an error.
PSA_ERROR_INSUFFICIENT_MEMORY	There were insufficient resources to initialize or lock the mutex.
PSA_ERROR_BAD_STATE	The compilation option MBEDTLS_THREADING_ALT is enabled, and mbedtls_threading_set_alt() has not been called.

int mbedtls_mutex_unlock

(

mbedtls_threading_mutex_t *

mutex

)

Unlock a mutex.

It must be currently locked by the calling thread.

Note

The behavior is undefined if:

• mutex has not been initialized with mbedtls_mutex_init(), or has already been freed with mbedtls_mutex_free();
• mutex is not locked;
• mutex was locked by a different thread.

Parameters

mutex

The mutex to unlock.

Return values

0	Success.
MBEDTLS_ERR_THREADING_USAGE_ERROR	mbedtls_mutex_init() failed, or a mutex usage error was detected. Note that depending on the platform, a mutex usage error may result in a deadlock, a crash or other undesirable behavior instead of returning an error.
PSA_ERROR_BAD_STATE	The compilation option MBEDTLS_THREADING_ALT is enabled, and mbedtls_threading_set_alt() has not been called.

void mbedtls_threading_free_alt

(

void

)

Free global mutexes.

void mbedtls_threading_set_alt	(	int(*)(mbedtls_platform_mutex_t *)	mutex_init,
		void(*)(mbedtls_platform_mutex_t *)	mutex_destroy,
		int(*)(mbedtls_platform_mutex_t *)	mutex_lock,
		int(*)(mbedtls_platform_mutex_t *)	mutex_unlock,
		int(*)(mbedtls_platform_condition_variable_t *)	cond_init,
		void(*)(mbedtls_platform_condition_variable_t *)	cond_destroy,
		int(*)(mbedtls_platform_condition_variable_t *)	cond_signal,
		int(*)(mbedtls_platform_condition_variable_t *)	cond_broadcast,
		int(*)(mbedtls_platform_condition_variable_t *, mbedtls_platform_mutex_t *)	cond_wait
	)

Set your alternate threading implementation function pointers and initialize global mutexes. If used, this function must be called once in the main thread before any other Mbed TLS function is called, and mbedtls_threading_free_alt() must be called once in the main thread after all other Mbed TLS functions.

Note

Functions should return MBEDTLS_ERR_THREADING_USAGE_ERROR if a mutex usage error is detected. However, it is acceptable for usage errors to result in undefined behavior (including deadlocks and crashes) if detecting usage errors is not practical on your platform.

The library will always unlock a mutex from the same thread that locked it, and will never lock a mutex in a thread that has already locked it.

Spurious wakeups on condition variables are permitted.

Parameters

mutex_init	The mutex init function implementation. The behavior is undefined if the mutex is already initialized and has not been destroyed, or if this function is called concurrently from multiple threads.
mutex_destroy	The mutex destroy function implementation. This function must free any resources associated with the mutex object. The behavior is undefined if the mutex was not initialized, if it has already been destroyed, if it is currently locked, or if this function is called concurrently from multiple threads.
mutex_lock	The mutex lock function implementation. The behavior is undefined if the mutex was not initialized, if it has already been destroyed, or if it is currently locked by the calling thread.
mutex_unlock	The mutex unlock function implementation. The behavior is undefined if the mutex is not currently locked by the calling thread.
cond_init	The condition variable initialization implementation. The behavior is undefined if the variable is already initialized, if it has been destroyed, or if this function is called concurrently from multiple threads.
cond_destroy	The condition variable destroy implementation. This function must free any resources associated with the condition variable object. The behavior is undefined if the condition variable was not initialized, if it has already been destroyed, if a thread is waiting on it, or if this function is called concurrently from multiple threads.
cond_signal	The condition variable signal implementation. The behavior is undefined if the condition variable was not initialized or if it has already been destroyed.
cond_broadcast	The condition variable broadcast implementation. The behavior is undefined if the condition variable was not initialized or if it has already been destroyed.
cond_wait	The condition variable wait implementation. The behavior is undefined if the mutex and the condition variable have not both been initialized, if one of them has already been destroyed, or if the mutex is not currently locked by the calling thread.

Variable Documentation

mbedtls_threading_mutex_t mbedtls_threading_readdir_mutex