Skip to content

Commit

Permalink
Merge pull request #1671 from jphickey/fix-1606-mempool-doc
Browse files Browse the repository at this point in the history
Fix #1606, update documentation for CFE_ES_GetPoolBufInfo
  • Loading branch information
astrogeco authored Jul 20, 2021
2 parents 9084c29 + decb7d0 commit 162274b
Show file tree
Hide file tree
Showing 2 changed files with 22 additions and 3 deletions.
22 changes: 21 additions & 1 deletion docs/cFE Application Developers Guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 1 addition & 2 deletions modules/core_api/fsw/inc/cfe_es.h
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 162274b

Please sign in to comment.