yuzu-emu/mbedtls
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Improve the documentation of MBEDTLS_PLATFORM_MEMORY

Browse source 
Introduce requests from review comments.
Signed-off-by: Andrzej Kurek <andrzej.kurek@arm.com>
This commit is contained in:
Andrzej Kurek 2023-07-14 06:15:15 -04:00
parent 548894fea1
commit f14a5c3fcb
1 changed files with 40 additions and 35 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

75
include/mbedtls/mbedtls_config.h
View file

@ -172,15 +172,47 @@
* This allows different allocators (self-implemented or provided) to be
* provided to the platform abstraction layer.
*
* Enabling MBEDTLS_PLATFORM_MEMORY without the
* Enabling #MBEDTLS_PLATFORM_MEMORY without the
* MBEDTLS_PLATFORM_{FREE,CALLOC}_MACROs will provide
* "mbedtls_platform_set_calloc_free()" allowing you to set an alternative calloc() and
* free() function pointer at runtime.
*
* Enabling MBEDTLS_PLATFORM_MEMORY and specifying
* Enabling #MBEDTLS_PLATFORM_MEMORY and specifying
* MBEDTLS_PLATFORM_{CALLOC,FREE}_MACROs will allow you to specify the
* alternate function at compile time.
*
* An overview of how the value of mbedtls_calloc is determined:
*
* - if !MBEDTLS_PLATFORM_MEMORY
* - mbedtls_calloc = calloc
* - if MBEDTLS_PLATFORM_MEMORY
* - if (MBEDTLS_PLATFORM_CALLOC_MACRO && MBEDTLS_PLATFORM_FREE_MACRO):
* - mbedtls_calloc = MBEDTLS_PLATFORM_CALLOC_MACRO
* - if !(MBEDTLS_PLATFORM_CALLOC_MACRO && MBEDTLS_PLATFORM_FREE_MACRO):
* - Dynamic setup via mbedtls_platform_set_calloc_free is now possible with a default value MBEDTLS_PLATFORM_STD_CALLOC.
* - How is MBEDTLS_PLATFORM_STD_CALLOC handled?
* - if MBEDTLS_PLATFORM_NO_STD_FUNCTIONS:
* - MBEDTLS_PLATFORM_STD_CALLOC is not set to anything;
* - MBEDTLS_PLATFORM_STD_MEM_HDR can be included if present;
* - if !MBEDTLS_PLATFORM_NO_STD_FUNCTIONS:
* - if MBEDTLS_PLATFORM_STD_CALLOC is present:
* - User-defined MBEDTLS_PLATFORM_STD_CALLOC is respected;
* - if !MBEDTLS_PLATFORM_STD_CALLOC:
* - MBEDTLS_PLATFORM_STD_CALLOC = calloc
*
* - At this point the presence of MBEDTLS_PLATFORM_STD_CALLOC is checked.
* - if !MBEDTLS_PLATFORM_STD_CALLOC
* - MBEDTLS_PLATFORM_STD_CALLOC = uninitialized_calloc
*
* - mbedtls_calloc = MBEDTLS_PLATFORM_STD_CALLOC.
*
* Defining MBEDTLS_PLATFORM_CALLOC_MACRO and #MBEDTLS_PLATFORM_STD_CALLOC at the same time is not possible.
* MBEDTLS_PLATFORM_CALLOC_MACRO and MBEDTLS_PLATFORM_FREE_MACRO must both be defined or undefined at the same time.
* #MBEDTLS_PLATFORM_STD_CALLOC and #MBEDTLS_PLATFORM_STD_FREE do not have to be defined at the same time, as, if they are used,
* dynamic setup of these functions is possible. See the tree above to see how are they handled in all cases.
* An uninitialized #MBEDTLS_PLATFORM_STD_CALLOC always fails, returning a null pointer.
* An uninitialized #MBEDTLS_PLATFORM_STD_FREE does not do anything.
*
* Requires: MBEDTLS_PLATFORM_C
*
* Enable this layer to allow use of alternative memory allocators.
@ -3681,53 +3713,26 @@
/* Platform options */
//#define MBEDTLS_PLATFORM_STD_MEM_HDR <stdlib.h> /**< Header to include if MBEDTLS_PLATFORM_NO_STD_FUNCTIONS is defined. Don't define if no header is needed. */
/* An overview of how the value of mbedtls_calloc is determined:
*
* if !MBEDTLS_PLATFORM_MEMORY
* mbedtls_calloc = calloc
* if MBEDTLS_PLATFORM_MEMORY
* if (MBEDTLS_PLATFORM_CALLOC_MACRO && MBEDTLS_PLATFORM_FREE_MACRO):
* mbedtls_calloc = MBEDTLS_PLATFORM_CALLOC_MACRO
* if !(MBEDTLS_PLATFORM_CALLOC_MACRO && MBEDTLS_PLATFORM_FREE_MACRO):
* Dynamic setup via mbedtls_platform_set_calloc_free is now possible with a default value MBEDTLS_PLATFORM_STD_CALLOC.
* How is MBEDTLS_PLATFORM_STD_CALLOC handled?
* if MBEDTLS_PLATFORM_NO_STD_FUNCTIONS:
* MBEDTLS_PLATFORM_STD_CALLOC is not set to anything;
* MBEDTLS_PLATFORM_STD_MEM_HDR can be included if present;
* if !MBEDTLS_PLATFORM_NO_STD_FUNCTIONS:
* if MBEDTLS_PLATFORM_STD_CALLOC is present:
* User-defined MBEDTLS_PLATFORM_STD_CALLOC is respected;
* if !MBEDTLS_PLATFORM_STD_CALLOC:
* MBEDTLS_PLATFORM_STD_CALLOC = calloc
*
* At this point the presence of MBEDTLS_PLATFORM_STD_CALLOC is checked.
* if !MBEDTLS_PLATFORM_STD_CALLOC
* MBEDTLS_PLATFORM_STD_CALLOC = uninitialized_calloc
*
* mbedtls_calloc = MBEDTLS_PLATFORM_STD_CALLOC.
*
* Defining MBEDTLS_PLATFORM_CALLOC_MACRO and MBEDTLS_PLATFORM_STD_CALLOC at the same time is not possible.
* MBEDTLS_PLATFORM_CALLOC_MACRO and MBEDTLS_PLATFORM_FREE_MACRO must both be defined or undefined at the same time.
* MBEDTLS_PLATFORM_STD_CALLOC and MBEDTLS_PLATFORM_STD_FREE do not have to be defined at the same time, as, if they are used,
* dynamic setup of these functions is possible. See the tree above to see how are they handled in all cases.
*/
/** \def MBEDTLS_PLATFORM_STD_CALLOC
*
* Default allocator to use, can be undefined. See the description above for details.
* Default allocator to use, can be undefined.
* It must initialize the allocated buffer memory to zeroes.
* The size of the buffer is the product of the two parameters.
* The calloc function returns either a null pointer or a pointer to the allocated space.
* If the product is 0, the function may either return NULL or a valid pointer to an array of size 0 which is a valid input to the deallocation function.
* An uninitialized #MBEDTLS_PLATFORM_STD_CALLOC always fails, returning a null pointer.
* See the description of #MBEDTLS_PLATFORM_MEMORY for more details.
* The corresponding deallocation function is #MBEDTLS_PLATFORM_STD_FREE.
*/
//#define MBEDTLS_PLATFORM_STD_CALLOC calloc
/** \def MBEDTLS_PLATFORM_STD_FREE
*
* Default free to use, can be undefined. See the description above for more details (same principles as for MBEDTLS_PLATFORM_STD_CALLOC apply).
* Default free to use, can be undefined.
* NULL is a valid parameter, and the function must do nothing.
* A non-null parameter will always be a pointer previously returned by #MBEDTLS_PLATFORM_STD_CALLOC and not yet freed.
* An uninitialized #MBEDTLS_PLATFORM_STD_FREE does not do anything.
* See the description of #MBEDTLS_PLATFORM_MEMORY for more details (same principles as for MBEDTLS_PLATFORM_STD_CALLOC apply).
*/
//#define MBEDTLS_PLATFORM_STD_FREE free
//#define MBEDTLS_PLATFORM_STD_SETBUF setbuf /**< Default setbuf to use, can be undefined */