From decb7d0b38f7467cf62c5def23a467a3936ea275 Mon Sep 17 00:00:00 2001 From: Joseph Hickey Date: Fri, 16 Jul 2021 12:34:57 -0400 Subject: [PATCH] Fix #1606, update documentation for CFE_ES_GetPoolBufInfo Corrects the return type documentation, on success this function returns the size of the buffer, it does not return CFE_SUCCESS. Additionally, this updates the general description of the pool implementation to reflect the variances in platform architectures (i.e. the buffer descriptor/overhead may be 12 bytes on a CPU with 32 bit size_t, but will be greater on a CPU with a 64 bit size_t). --- docs/cFE Application Developers Guide.md | 22 +++++++++++++++++++++- modules/core_api/fsw/inc/cfe_es.h | 3 +-- 2 files changed, 22 insertions(+), 3 deletions(-) diff --git a/docs/cFE Application Developers Guide.md b/docs/cFE Application Developers Guide.md index 302b9fd2e..cbbcd522a 100644 --- a/docs/cFE Application Developers Guide.md +++ b/docs/cFE Application Developers Guide.md @@ -971,11 +971,31 @@ ensure that sufficient memory is provided to store the mempool management structures in addition to the memory needed by the application. After initialization, mempool allocates fixed size blocks as requested from the application memory block. As each block is -requested mempool creates a 12 byte block descriptor with management +requested mempool creates a block descriptor with management structures as well as space for the user application data (see Figure 5.1). The space for user data will be fixed in size and greater than or equal to the requested block size. +The specific size of the management structure depends on the platform +architecture word size and alignment requirements, and padding may be +added as necessary to meet the system requirements. For illustrative +purposes, the examples below use sizes that are respresentative of a +32-bit CPU with 32-bit buffer alignment with no extra alignment padding +added. The pool overhead will increase on a 64-bit CPU with 64-bit +alignment, or if pool alignment configured greater than 32 bits. For +more information on pool buffer alignment, see the description of +the `CFE_PLATFORM_ES_MEMPOOL_ALIGN_SIZE_MIN` configuration parameter. + +It should also be noted that while 64-bit CPU architectures are fully +supported by the memory pool internal implementation in current CFE +versions, the API is carried over from older CFE versions in order to +be backward compatible. Some memory pool API functions (e.g. +`CFE_ES_GetPoolBufInfo`, `CFE_ES_PutPoolBuf`, etc) return a buffer size +on success, which is encoded into an `int32` return type. As a result, +individual memory pools should not exceed 2GB in size, even on 64-bit +platforms, to avoid exceeding the representable range of an `int32` data +type. + ![](.//media/cFE_Application_Developers_Guide_image13.png) Figure 5.1 Block Descriptor diff --git a/modules/core_api/fsw/inc/cfe_es.h b/modules/core_api/fsw/inc/cfe_es.h index 4145cbb01..53061b4a3 100644 --- a/modules/core_api/fsw/inc/cfe_es.h +++ b/modules/core_api/fsw/inc/cfe_es.h @@ -1343,8 +1343,7 @@ int32 CFE_ES_GetPoolBuf(CFE_ES_MemPoolBuf_t *BufPtr, CFE_ES_MemHandle_t Handle, ** ** \param[in] BufPtr A pointer to the memory buffer to provide status for. ** -** \return Execution status, see \ref CFEReturnCodes -** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \return Size of the buffer if successful, or status code if not successful, see \ref CFEReturnCodes ** \retval #CFE_ES_ERR_RESOURCEID_NOT_VALID \copybrief CFE_ES_ERR_RESOURCEID_NOT_VALID ** \retval #CFE_ES_BUFFER_NOT_IN_POOL \copybrief CFE_ES_BUFFER_NOT_IN_POOL ** \retval #CFE_ES_BAD_ARGUMENT \copybrief CFE_ES_BAD_ARGUMENT