From 4bca2b0ccd33a8c31b691d7514ee18e6e9d4acca Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Tue, 27 Mar 2018 13:12:52 +0100 Subject: [PATCH 1/2] Update platform.h Minor documentation improvements: *Standardized file brief description. *Reordered tags within documentation blocks so that params and returns are last in block. *Some minor rephrasing. --- include/mbedtls/platform.h | 55 ++++++++++++++++++++------------------ 1 file changed, 29 insertions(+), 26 deletions(-) diff --git a/include/mbedtls/platform.h b/include/mbedtls/platform.h index ed10775848..65ae85c190 100644 --- a/include/mbedtls/platform.h +++ b/include/mbedtls/platform.h @@ -1,7 +1,8 @@ /** * \file platform.h * - * \brief The Mbed TLS platform abstraction layer. + * \brief This file contains the definitions and functions of the + * Mbed TLS platform abstraction layer. */ /* * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved @@ -102,7 +103,7 @@ extern "C" { /* \} name SECTION: Module settings */ /* - * The function pointers for calloc and free + * The function pointers for calloc and free. */ #if defined(MBEDTLS_PLATFORM_MEMORY) #if defined(MBEDTLS_PLATFORM_FREE_MACRO) && \ @@ -116,7 +117,8 @@ extern void * (*mbedtls_calloc)( size_t n, size_t size ); extern void (*mbedtls_free)( void *ptr ); /** - * \brief This function allows configuring custom memory-management functions. + * \brief This function allows configuring custom + * memory-management functions. * * \param calloc_func The \c calloc function implementation. * \param free_func The \c free function implementation. @@ -140,7 +142,8 @@ int mbedtls_platform_set_calloc_free( void * (*calloc_func)( size_t, size_t ), extern int (*mbedtls_fprintf)( FILE *stream, const char *format, ... ); /** - * \brief This function allows configuring a custom \p fprintf function pointer. + * \brief This function allows configuring a custom + * \p fprintf function pointer. * * \param fprintf_func The \c fprintf function implementation. * @@ -163,8 +166,8 @@ int mbedtls_platform_set_fprintf( int (*fprintf_func)( FILE *stream, const char extern int (*mbedtls_printf)( const char *format, ... ); /** - * \brief This function allows configuring a custom \c printf function - * pointer. + * \brief This function allows configuring a custom \c printf + * function pointer. * * \param printf_func The \c printf function implementation. * @@ -197,12 +200,12 @@ int mbedtls_platform_win32_snprintf( char *s, size_t n, const char *fmt, ... ); extern int (*mbedtls_snprintf)( char * s, size_t n, const char * format, ... ); /** - * \brief This function allows configuring a custom \c snprintf function - * pointer. + * \brief This function allows configuring a custom + * \c snprintf function pointer. * * \param snprintf_func The \c snprintf function implementation. * - * \return \c 0 on success. + * \return \c 0 on success. */ int mbedtls_platform_set_snprintf( int (*snprintf_func)( char * s, size_t n, const char * format, ... ) ); @@ -221,12 +224,12 @@ int mbedtls_platform_set_snprintf( int (*snprintf_func)( char * s, size_t n, extern void (*mbedtls_exit)( int status ); /** - * \brief This function allows configuring a custom \c exit function - * pointer. + * \brief This function allows configuring a custom + * \c exit function pointer. * * \param exit_func The \c exit function implementation. * - * \return \c 0 on success. + * \return \c 0 on success. */ int mbedtls_platform_set_exit( void (*exit_func)( int status ) ); #else @@ -302,7 +305,7 @@ int mbedtls_platform_set_nv_seed( * setup or teardown operations. */ typedef struct { - char dummy; /**< Placeholder member, as empty structs are not portable. */ + char dummy; /**< A placeholder member, as empty structs are not portable. */ } mbedtls_platform_context; @@ -311,33 +314,33 @@ mbedtls_platform_context; #endif /* !MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT */ /** - * \brief This function performs any platform initialization operations. + * \brief This function performs any platform-specific initialization operations. + * + * \note This function should be called before any other library functions. + * + * Its implementation is platform-specific, and unless + * platform-specific code is provided, it does nothing. + * + * \note The usage and necessity of this function is dependent on the platform. * * \param ctx The Mbed TLS context. * * \return \c 0 on success. - * - * \note This function is intended to allow platform-specific initialization, - * and should be called before any other library functions. Its - * implementation is platform-specific, and unless - * platform-specific code is provided, it does nothing. - * - * Its use and whether it is necessary to call it is dependent on the - * platform. */ int mbedtls_platform_setup( mbedtls_platform_context *ctx ); /** * \brief This function performs any platform teardown operations. * - * \param ctx The Mbed TLS context. - * * \note This function should be called after every other Mbed TLS module * has been correctly freed using the appropriate free function. + * * Its implementation is platform-specific, and unless * platform-specific code is provided, it does nothing. * - * Its use and whether it is necessary to call it is dependent on the - * platform. + * \note The usage and necessity of this function is dependent on the platform. + * + * \param ctx The Mbed TLS context. + * */ void mbedtls_platform_teardown( mbedtls_platform_context *ctx ); From 9464d7b6e367407c96bbf1000ecc71d854d14ce1 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Mon, 16 Apr 2018 15:28:35 +0100 Subject: [PATCH 2/2] Update platform.h Implemented changes based on review comments --- include/mbedtls/platform.h | 34 +++++++++++++++++++++++----------- 1 file changed, 23 insertions(+), 11 deletions(-) diff --git a/include/mbedtls/platform.h b/include/mbedtls/platform.h index 65ae85c190..d50b266b71 100644 --- a/include/mbedtls/platform.h +++ b/include/mbedtls/platform.h @@ -3,6 +3,14 @@ * * \brief This file contains the definitions and functions of the * Mbed TLS platform abstraction layer. + * + * The platform abstraction layer removes the need for the library + * to directly link to standard C library functions or operating + * system services, making the library easier to port and embed. + * Application developers and users of the library can provide their own + * implementations of these functions, or implementations specific to + * their platform, which can be statically linked to the library or + * dynamically configured at runtime. */ /* * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved @@ -117,8 +125,8 @@ extern void * (*mbedtls_calloc)( size_t n, size_t size ); extern void (*mbedtls_free)( void *ptr ); /** - * \brief This function allows configuring custom - * memory-management functions. + * \brief This function dynamically sets the memory-management + * functions used by the library, during runtime. * * \param calloc_func The \c calloc function implementation. * \param free_func The \c free function implementation. @@ -142,8 +150,9 @@ int mbedtls_platform_set_calloc_free( void * (*calloc_func)( size_t, size_t ), extern int (*mbedtls_fprintf)( FILE *stream, const char *format, ... ); /** - * \brief This function allows configuring a custom - * \p fprintf function pointer. + * \brief This function dynamically configures the fprintf + * function that is called when the + * mbedtls_fprintf() function is invoked by the library. * * \param fprintf_func The \c fprintf function implementation. * @@ -166,8 +175,9 @@ int mbedtls_platform_set_fprintf( int (*fprintf_func)( FILE *stream, const char extern int (*mbedtls_printf)( const char *format, ... ); /** - * \brief This function allows configuring a custom \c printf - * function pointer. + * \brief This function dynamically configures the snprintf + * function that is called when the mbedtls_snprintf() + * function is invoked by the library. * * \param printf_func The \c printf function implementation. * @@ -224,8 +234,9 @@ int mbedtls_platform_set_snprintf( int (*snprintf_func)( char * s, size_t n, extern void (*mbedtls_exit)( int status ); /** - * \brief This function allows configuring a custom - * \c exit function pointer. + * \brief This function dynamically configures the exit + * function that is called when the mbedtls_exit() + * function is invoked by the library. * * \param exit_func The \c exit function implementation. * @@ -314,7 +325,8 @@ mbedtls_platform_context; #endif /* !MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT */ /** - * \brief This function performs any platform-specific initialization operations. + * \brief This function performs any platform-specific initialization + * operations. * * \note This function should be called before any other library functions. * @@ -323,7 +335,7 @@ mbedtls_platform_context; * * \note The usage and necessity of this function is dependent on the platform. * - * \param ctx The Mbed TLS context. + * \param ctx The platform context. * * \return \c 0 on success. */ @@ -339,7 +351,7 @@ int mbedtls_platform_setup( mbedtls_platform_context *ctx ); * * \note The usage and necessity of this function is dependent on the platform. * - * \param ctx The Mbed TLS context. + * \param ctx The platform context. * */ void mbedtls_platform_teardown( mbedtls_platform_context *ctx );