Explain the usage of is_valid in pthread mutexes

Document the usage inside the library, and relate it with how it's
additionally used in the test code.

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
This commit is contained in:
Gilles Peskine 2021-02-09 15:35:29 +01:00
parent 7252ec3947
commit 7ba73e5756
3 changed files with 15 additions and 1 deletions

View file

@ -73,6 +73,9 @@ extern "C" {
typedef struct mbedtls_threading_mutex_t
{
pthread_mutex_t mutex;
/* is_valid is 0 after a failed init or a free, and nonzero after a
* successful init. This field is not considered part of the public
* API of Mbed TLS and may change without notice. */
char is_valid;
} mbedtls_threading_mutex_t;
#endif

View file

@ -98,6 +98,12 @@ static void threading_mutex_init_pthread( mbedtls_threading_mutex_t *mutex )
if( mutex == NULL )
return;
/* A nonzero value of is_valid indicates a successfully initialized
* mutex. This is a workaround for not being able to return an error
* code for this function. The lock/unlock functions return an error
* if is_valid is nonzero. The Mbed TLS unit test code uses this field
* to distinguish more states of the mutex; see helpers.function for
* details. */
mutex->is_valid = pthread_mutex_init( &mutex->mutex, NULL ) == 0;
}

View file

@ -834,8 +834,13 @@ int mbedtls_test_hexcmp( uint8_t * a, uint8_t * b, uint32_t a_len, uint32_t b_le
* indicate the exact location of the problematic call. To locate the error,
* use a debugger and set a breakpoint on mbedtls_test_mutex_usage_error().
*/
enum value_of_mutex_is_valid
enum value_of_mutex_is_valid_field
{
/* Potential values for the is_valid field of mbedtls_threading_mutex_t.
* Note that MUTEX_FREED must be 0 and MUTEX_IDLE must be 1 for
* compatibility with threading_mutex_init_pthread() and
* threading_mutex_free_pthread(). MUTEX_LOCKED could be any nonzero
* value. */
MUTEX_FREED = 0, //!< Set by threading_mutex_free_pthread
MUTEX_IDLE = 1, //!< Set by threading_mutex_init_pthread and by our unlock
MUTEX_LOCKED = 2, //!< Set by our lock