You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by ad...@apache.org on 2016/02/25 18:11:26 UTC
incubator-mynewt-site git commit: os_mempool - pull request #8 by
wes3 - os_mempool
Repository: incubator-mynewt-site
Updated Branches:
refs/heads/asf-site 175a2c18b -> 0760c397a
os_mempool - pull request #8 by wes3 - os_mempool
Project: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/commit/0760c397
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/0760c397
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/0760c397
Branch: refs/heads/asf-site
Commit: 0760c397a7fc81dae35324558381091912d7ac4d
Parents: 175a2c1
Author: aditihilbert <ad...@runtime.io>
Authored: Thu Feb 25 09:10:59 2016 -0800
Committer: aditihilbert <ad...@runtime.io>
Committed: Thu Feb 25 09:10:59 2016 -0800
----------------------------------------------------------------------
mkdocs/search_index.json | 73 ++-
.../memory_pool/OS_MEMPOOL_BYTES/index.html | 20 +-
.../memory_pool/OS_MEMPOOL_SIZE/index.html | 598 +++++++++++++++++++
os/core_os/memory_pool/memory_pool/index.html | 50 +-
.../memory_pool/os_memblock_get/index.html | 8 +
.../memory_pool/os_memblock_put/index.html | 22 +-
.../memory_pool/os_mempool_init/index.html | 30 +-
sitemap.xml | 16 +-
8 files changed, 758 insertions(+), 59 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/0760c397/mkdocs/search_index.json
----------------------------------------------------------------------
diff --git a/mkdocs/search_index.json b/mkdocs/search_index.json
index ec44ed5..7ceef39 100644
--- a/mkdocs/search_index.json
+++ b/mkdocs/search_index.json
@@ -867,27 +867,27 @@
},
{
"location": "/os/core_os/memory_pool/memory_pool/",
- "text": "Memory Pools\n\n\nMemory can be pre-allocated to a pool of fixed size elements.\n\n\nDescription\n\n\nSometimes it's useful to have several memory blocks of same size preallocated for specific use. E.g. you want to limit the amount of memory used for it, or you want to make sure that there is memory available when you ask for it.\n\n\nThis can be done using a memory pool. You allocate memory either statically or from heap, and then designate that memory to be used as storage for fixed size elements.\n\n\nPool will be initialized by calling \nos_mempool_init()\n. Element can be allocated from it with \nos_mempool_get()\n, and released back with \nos_mempool_put()\n.\n\n\nData structures\n\n\nstruct os_mempool {\n int mp_block_size;\n int mp_num_blocks;\n int mp_num_free;\n SLIST_HEAD(,os_memblock);\n char *name;\n};\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nmp_block_size\n\n\nSize of the memory blocks, in bytes\n\n\n\n\n\n\
nmp_num_blocks\n\n\nNumber of memory blocks in the pool\n\n\n\n\n\n\nmp_num_free\n\n\nNumber of free blocks left\n\n\n\n\n\n\nname\n\n\nName for the memory block\n\n\n\n\n\n\n\n\nList of Functions\n\n\nThe functions available in mem_pool are:\n\n\n\n\nos_memblock_get\n\n\nos_mempool_init\n\n\nos_memblock_put\n\n\nOS_MEMPOOL_BYTES",
+ "text": "Memory Pools\n\n\nA memory pool is a collection of fixed sized elements called memory blocks. Generally, memory pools are used when the developer wants to allocate a certain amount of memory to a given feature. Unlike the heap, where a code module is at the mercy of other code modules to insure there is sufficient memory, memory pools can insure sufficient memory allocation.\n\n\nDescription\n\n\nIn order to create a memory pool the developer needs to do a few things. The first task is to define the memory pool itself. This is a data structure which contains information about the pool itself (i.e. number of blocks, size of the blocks, etc).\n\n\nstruct os_mempool my_pool;\n\n\n\n\n\nThe next order of business is to allocate the memory used by the memory pool. This memory can either be statically allocated (i.e. a global variable) or dynamically allocated (i.e. from the heap). When determining the amount of memory required for the memory pool, simply multiplying
the number of blocks by the size of each block is not sufficient as the OS may have alignment requirements. The alignment size definition is named \nOS_ALIGNMENT\n and can be found in os_arch.h as it is architecture specific. The memory block alignment is usually for efficiency but may be due to other reasons. Generally, blocks are aligned on 32-bit boundaries. Note that memory blocks must also be of sufficient size to hold a list pointer as this is needed to chain memory blocks on the free list.\n\n\nIn order to simplify this for the user two macros have been provided: \nOS_MEMPOOL_BYTES(n, blksize)\n and \nOS_MEMPOOL_SIZE(n, blksize)\n. The first macro returns the number of bytes needed for the memory pool while the second returns the number of \nos_membuf_t\n elements required by the memory pool. The \nos_membuf_t\n type is used to guarantee that the memory buffer used by the memory pool is aligned on the correct boundary. \n\n\nHere are some examples. Note that if a custom mallo
c implementation is used it must guarantee that the memory buffer used by the pool is allocated on the correct boundary (i.e. OS_ALIGNMENT).\n\n\nvoid *my_memory_buffer;\nmy_memory_buffer = malloc(OS_MEMPOOL_BYTES(NUM_BLOCKS, BLOCK_SIZE));\n\n\n\n\nos_membuf_t my_memory_buffer[OS_MEMPOOL_SIZE(NUM_BLOCKS, BLOCK_SIZE)];\n\n\n\n\n\nNow that the memory pool has been defined as well as the memory required for the memory blocks which make up the pool the user needs to initialize the memory pool by calling \nos_mempool_init\n.\n\n\nos_mempool_init(\nmy_pool, NUM_BLOCKS, BLOCK_SIZE, my_memory_buffer,\n \nMyPool\n);\n\n\n\n\n\nOnce the memory pool has been initialized the developer can allocate memory blocks from the pool by calling \nos_memblock_get\n. When the memory block is no longer needed the memory can be freed by calling \nos_memblock_put\n. \n\n\nData structures\n\n\nstruct os_mempool {\n int mp_block_size;\n int mp_num_blocks;\n int mp_num_free;\n
uint32_t mp_membuf_addr;\n STAILQ_ENTRY(os_mempool) mp_list; \n SLIST_HEAD(,os_memblock);\n char *name;\n};\n\n\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nmp_block_size\n\n\nSize of the memory blocks, in bytes. This is not the actual number of bytes used by each block; it is the requested size of each block. The actual memory block size will be aligned to OS_ALIGNMENT bytes\n\n\n\n\n\n\nmp_num_blocks\n\n\nNumber of memory blocks in the pool\n\n\n\n\n\n\nmp_num_free\n\n\nNumber of free blocks left\n\n\n\n\n\n\nmp_membuf_addr\n\n\nThe address of the memory block. This is used to check that a valid memory block is being freed.\n\n\n\n\n\n\nmp_list\n\n\nList pointer to chain memory pools so they can be displayed by newt tools\n\n\n\n\n\n\nSLIST_HEAD(,os_memblock)\n\n\nList pointer to chain free memory blocks\n\n\n\n\n\n\nname\n\n\nName for the memory block\n\n\n\n\n\n\n\n\nList of Functions\n\n\nThe functions available in mem_pool are:\n\n\n\n\nos_
memblock_get\n\n\nos_mempool_init\n\n\nos_memblock_put\n\n\nOS_MEMPOOL_BYTES\n\n\nOS_MEMPOOL_SIZE",
"title": "Overview"
},
{
"location": "/os/core_os/memory_pool/memory_pool/#memory-pools",
- "text": "Memory can be pre-allocated to a pool of fixed size elements.",
+ "text": "A memory pool is a collection of fixed sized elements called memory blocks. Generally, memory pools are used when the developer wants to allocate a certain amount of memory to a given feature. Unlike the heap, where a code module is at the mercy of other code modules to insure there is sufficient memory, memory pools can insure sufficient memory allocation.",
"title": "Memory Pools"
},
{
"location": "/os/core_os/memory_pool/memory_pool/#description",
- "text": "Sometimes it's useful to have several memory blocks of same size preallocated for specific use. E.g. you want to limit the amount of memory used for it, or you want to make sure that there is memory available when you ask for it. This can be done using a memory pool. You allocate memory either statically or from heap, and then designate that memory to be used as storage for fixed size elements. Pool will be initialized by calling os_mempool_init() . Element can be allocated from it with os_mempool_get() , and released back with os_mempool_put() .",
+ "text": "In order to create a memory pool the developer needs to do a few things. The first task is to define the memory pool itself. This is a data structure which contains information about the pool itself (i.e. number of blocks, size of the blocks, etc). struct os_mempool my_pool; \nThe next order of business is to allocate the memory used by the memory pool. This memory can either be statically allocated (i.e. a global variable) or dynamically allocated (i.e. from the heap). When determining the amount of memory required for the memory pool, simply multiplying the number of blocks by the size of each block is not sufficient as the OS may have alignment requirements. The alignment size definition is named OS_ALIGNMENT and can be found in os_arch.h as it is architecture specific. The memory block alignment is usually for efficiency but may be due to other reasons. Generally, blocks are aligned on 32-bit boundaries. Note that memory blocks must also be of sufficient
size to hold a list pointer as this is needed to chain memory blocks on the free list. In order to simplify this for the user two macros have been provided: OS_MEMPOOL_BYTES(n, blksize) and OS_MEMPOOL_SIZE(n, blksize) . The first macro returns the number of bytes needed for the memory pool while the second returns the number of os_membuf_t elements required by the memory pool. The os_membuf_t type is used to guarantee that the memory buffer used by the memory pool is aligned on the correct boundary. Here are some examples. Note that if a custom malloc implementation is used it must guarantee that the memory buffer used by the pool is allocated on the correct boundary (i.e. OS_ALIGNMENT). void *my_memory_buffer;\nmy_memory_buffer = malloc(OS_MEMPOOL_BYTES(NUM_BLOCKS, BLOCK_SIZE)); os_membuf_t my_memory_buffer[OS_MEMPOOL_SIZE(NUM_BLOCKS, BLOCK_SIZE)]; \nNow that the memory pool has been defined as well as the memory required for the memory blocks which make up the pool t
he user needs to initialize the memory pool by calling os_mempool_init . os_mempool_init( my_pool, NUM_BLOCKS, BLOCK_SIZE, my_memory_buffer,\n MyPool ); \nOnce the memory pool has been initialized the developer can allocate memory blocks from the pool by calling os_memblock_get . When the memory block is no longer needed the memory can be freed by calling os_memblock_put .",
"title": "Description"
},
{
"location": "/os/core_os/memory_pool/memory_pool/#data-structures",
- "text": "struct os_mempool {\n int mp_block_size;\n int mp_num_blocks;\n int mp_num_free;\n SLIST_HEAD(,os_memblock);\n char *name;\n}; Element Description mp_block_size Size of the memory blocks, in bytes mp_num_blocks Number of memory blocks in the pool mp_num_free Number of free blocks left name Name for the memory block",
+ "text": "struct os_mempool {\n int mp_block_size;\n int mp_num_blocks;\n int mp_num_free;\n uint32_t mp_membuf_addr;\n STAILQ_ENTRY(os_mempool) mp_list; \n SLIST_HEAD(,os_memblock);\n char *name;\n}; Element Description mp_block_size Size of the memory blocks, in bytes. This is not the actual number of bytes used by each block; it is the requested size of each block. The actual memory block size will be aligned to OS_ALIGNMENT bytes mp_num_blocks Number of memory blocks in the pool mp_num_free Number of free blocks left mp_membuf_addr The address of the memory block. This is used to check that a valid memory block is being freed. mp_list List pointer to chain memory pools so they can be displayed by newt tools SLIST_HEAD(,os_memblock) List pointer to chain free memory blocks name Name for the memory block",
"title": "Data structures"
},
{
"location": "/os/core_os/memory_pool/memory_pool/#list-of-functions",
- "text": "The functions available in mem_pool are: os_memblock_get os_mempool_init os_memblock_put OS_MEMPOOL_BYTES",
+ "text": "The functions available in mem_pool are: os_memblock_get os_mempool_init os_memblock_put OS_MEMPOOL_BYTES OS_MEMPOOL_SIZE",
"title": "List of Functions"
},
{
@@ -922,37 +922,37 @@
},
{
"location": "/os/core_os/memory_pool/os_mempool_init/",
- "text": "os_mempool_init\n\n\nos_error_t os_mempool_init(struct os_mempool *mp, int blocks, int block_size, void *membuf, char *name)\n\n\n\n\nInitializes the memory pool. Memory pointed by \nmembuf\n is taken and \nblocks\n number of elements of size \nblock_size\n are added to the pool. \nname\n is optional, and names the memory pool.\n\n\nIt is assumed that the amount of memory pointed by \nmembuf\n has at least \nOS_MEMPOOL_BYTES(blocks, block_size)\n number of bytes.\n\n\nname\n is not copied, so caller should make sure that the memory does not get reused.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nmp\n\n\nMemory pool being initialized\n\n\n\n\n\n\nblocks\n\n\nNumber of elements in the pool\n\n\n\n\n\n\nblock_size\n\n\nSize of an individual element in pool\n\n\n\n\n\n\nmembuf\n\n\nBacking store for the memory pool elements\n\n\n\n\n\n\nname\n\n\nName of the memory pool\n\n\n\n\n\n\n\n\nReturned values\n\n\nOS_OK: operation was su
ccessful.\nOS_INVALID_PARAM: invalid parameters. Block count or block size was negative, or membuf or mp was NULL.\nOS_MEM_NOT_ALIGNED: membuf has to be aligned to 4 byte boundary.\n\n\nNotes\n\n\nNote that os_mempool_init() does not allocate backing storage. \nmembuf\n has to be allocated by the caller.\n\n\nIt's recommended that you use \nOS_MEMPOOL_BYTES()\n to figure out how much memory to allocate for the pool.\n\n\nExample\n\n\n\n\n rc = os_mempool_init(\nnffs_file_pool, nffs_config.nc_num_files,\n sizeof (struct nffs_file), nffs_file_mem,\n \nnffs_file_pool\n);\n if (rc != 0) {\n return FS_EOS;\n }",
+ "text": "os_mempool_init\n\n\nos_error_t os_mempool_init(struct os_mempool *mp, int blocks, int block_size, void *membuf, char *name)\n\n\n\n\nInitializes the memory pool. Memory pointed to by \nmembuf\n is divided into \nblocks\n number of elements of size OS_ALIGN(\nblock_size\n). The \nname\n is optional, and names the memory pool.\n\n\nIt is assumed that the amount of memory pointed by \nmembuf\n has at least \nOS_MEMPOOL_BYTES(blocks, block_size)\n number of bytes.\n\n\nname\n is not copied, so caller should make sure that the memory does not get reused.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nmp\n\n\nMemory pool being initialized\n\n\n\n\n\n\nblocks\n\n\nNumber of elements in the pool\n\n\n\n\n\n\nblock_size\n\n\nMinimum size of an individual element in pool\n\n\n\n\n\n\nmembuf\n\n\nBacking store for the memory pool elements\n\n\n\n\n\n\nname\n\n\nName of the memory pool\n\n\n\n\n\n\n\n\nReturned values\n\n\nOS_OK: operation
was successful.\n\nOS_INVALID_PARAM: invalid parameters. Block count or block size was negative, or membuf or mp was NULL.\n\nOS_MEM_NOT_ALIGNED: membuf was not aligned on correct byte boundary.\n\n\nNotes\n\n\nNote that os_mempool_init() does not allocate backing storage; \nmembuf\n has to be allocated by the caller.\n\n\nIt's recommended that you use \nOS_MEMPOOL_BYTES()\n or \nOS_MEMPOOL_SIZE()\n to figure out how much memory to allocate for the pool.\n\n\nExample\n\n\n\n\n void *nffs_file_mem;\n\n nffs_file_mem = malloc(OS_MEMPOOL_BYTES(nffs_config.nc_num_files, sizeof (struct nffs_file)));\n\n rc = os_mempool_init(\nnffs_file_pool, nffs_config.nc_num_files,\n sizeof (struct nffs_file), nffs_file_mem,\n \nnffs_file_pool\n);\n if (rc != 0) {\n /* Memory pool initialization failure */\n }",
"title": "os_mempool_init"
},
{
"location": "/os/core_os/memory_pool/os_mempool_init/#os_mempool_init",
- "text": "os_error_t os_mempool_init(struct os_mempool *mp, int blocks, int block_size, void *membuf, char *name) Initializes the memory pool. Memory pointed by membuf is taken and blocks number of elements of size block_size are added to the pool. name is optional, and names the memory pool. It is assumed that the amount of memory pointed by membuf has at least OS_MEMPOOL_BYTES(blocks, block_size) number of bytes. name is not copied, so caller should make sure that the memory does not get reused.",
+ "text": "os_error_t os_mempool_init(struct os_mempool *mp, int blocks, int block_size, void *membuf, char *name) Initializes the memory pool. Memory pointed to by membuf is divided into blocks number of elements of size OS_ALIGN( block_size ). The name is optional, and names the memory pool. It is assumed that the amount of memory pointed by membuf has at least OS_MEMPOOL_BYTES(blocks, block_size) number of bytes. name is not copied, so caller should make sure that the memory does not get reused.",
"title": " os_mempool_init"
},
{
"location": "/os/core_os/memory_pool/os_mempool_init/#arguments",
- "text": "Arguments Description mp Memory pool being initialized blocks Number of elements in the pool block_size Size of an individual element in pool membuf Backing store for the memory pool elements name Name of the memory pool",
+ "text": "Arguments Description mp Memory pool being initialized blocks Number of elements in the pool block_size Minimum size of an individual element in pool membuf Backing store for the memory pool elements name Name of the memory pool",
"title": "Arguments"
},
{
"location": "/os/core_os/memory_pool/os_mempool_init/#returned-values",
- "text": "OS_OK: operation was successful.\nOS_INVALID_PARAM: invalid parameters. Block count or block size was negative, or membuf or mp was NULL.\nOS_MEM_NOT_ALIGNED: membuf has to be aligned to 4 byte boundary.",
+ "text": "OS_OK: operation was successful. \nOS_INVALID_PARAM: invalid parameters. Block count or block size was negative, or membuf or mp was NULL. \nOS_MEM_NOT_ALIGNED: membuf was not aligned on correct byte boundary.",
"title": "Returned values"
},
{
"location": "/os/core_os/memory_pool/os_mempool_init/#notes",
- "text": "Note that os_mempool_init() does not allocate backing storage. membuf has to be allocated by the caller. It's recommended that you use OS_MEMPOOL_BYTES() to figure out how much memory to allocate for the pool.",
+ "text": "Note that os_mempool_init() does not allocate backing storage; membuf has to be allocated by the caller. It's recommended that you use OS_MEMPOOL_BYTES() or OS_MEMPOOL_SIZE() to figure out how much memory to allocate for the pool.",
"title": "Notes"
},
{
"location": "/os/core_os/memory_pool/os_mempool_init/#example",
- "text": "rc = os_mempool_init( nffs_file_pool, nffs_config.nc_num_files,\n sizeof (struct nffs_file), nffs_file_mem,\n nffs_file_pool );\n if (rc != 0) {\n return FS_EOS;\n }",
+ "text": "void *nffs_file_mem;\n\n nffs_file_mem = malloc(OS_MEMPOOL_BYTES(nffs_config.nc_num_files, sizeof (struct nffs_file)));\n\n rc = os_mempool_init( nffs_file_pool, nffs_config.nc_num_files,\n sizeof (struct nffs_file), nffs_file_mem,\n nffs_file_pool );\n if (rc != 0) {\n /* Memory pool initialization failure */\n }",
"title": "Example"
},
{
"location": "/os/core_os/memory_pool/os_memblock_put/",
- "text": "os_memblock_put\n\n\nos_error_t os_memblock_put(struct os_mempool *mp, void *block_addr)\n\n\n\n\nReleases previously allocated element back to the pool.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nmp\n\n\nPointer to memory pool where element is put\n\n\n\n\n\n\nblock_addr\n\n\nPointer to element getting freed\n\n\n\n\n\n\n\n\nReturned values\n\n\nOS_OK: operation was a success:\nOS_INVALID_PARAM: If either mp or block_addr were NULL.\n\n\nNotes\n\n\nExample\n\n\n\n\n if (file != NULL) {\n rc = os_memblock_put(\nnffs_file_pool, file);\n if (rc != 0) {\n return FS_EOS;\n }\n }",
+ "text": "os_memblock_put\n\n\nos_error_t os_memblock_put(struct os_mempool *mp, void *block_addr)\n\n\n\n\nReleases previously allocated element back to the pool. \n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nmp\n\n\nPointer to memory pool from which block was allocated\n\n\n\n\n\n\nblock_addr\n\n\nPointer to element getting freed\n\n\n\n\n\n\n\n\n\n\nReturned values\n\n\nOS_OK: operation was a success:\n\nOS_INVALID_PARAM: If either mp or block_addr were NULL, or the block being freed was outside the range of the memory buffer or not on a true block size boundary.\n\n\n\n\nExample\n\n\n\n\n if (file != NULL) {\n rc = os_memblock_put(\nnffs_file_pool, file);\n if (rc != 0) {\n /* Error freeing memory block */\n }\n }",
"title": "os_memblock_put"
},
{
@@ -962,27 +962,22 @@
},
{
"location": "/os/core_os/memory_pool/os_memblock_put/#arguments",
- "text": "Arguments Description mp Pointer to memory pool where element is put block_addr Pointer to element getting freed",
+ "text": "Arguments Description mp Pointer to memory pool from which block was allocated block_addr Pointer to element getting freed",
"title": "Arguments"
},
{
"location": "/os/core_os/memory_pool/os_memblock_put/#returned-values",
- "text": "OS_OK: operation was a success:\nOS_INVALID_PARAM: If either mp or block_addr were NULL.",
+ "text": "OS_OK: operation was a success: \nOS_INVALID_PARAM: If either mp or block_addr were NULL, or the block being freed was outside the range of the memory buffer or not on a true block size boundary.",
"title": "Returned values"
},
{
- "location": "/os/core_os/memory_pool/os_memblock_put/#notes",
- "text": "",
- "title": "Notes"
- },
- {
"location": "/os/core_os/memory_pool/os_memblock_put/#example",
- "text": "if (file != NULL) {\n rc = os_memblock_put( nffs_file_pool, file);\n if (rc != 0) {\n return FS_EOS;\n }\n }",
+ "text": "if (file != NULL) {\n rc = os_memblock_put( nffs_file_pool, file);\n if (rc != 0) {\n /* Error freeing memory block */\n }\n }",
"title": "Example"
},
{
"location": "/os/core_os/memory_pool/OS_MEMPOOL_BYTES/",
- "text": "OS_MEMPOOL_BYTES\n\n\nOS_MEMPOOL_BYTES(n,blksize)\n\n\n\n\nCalculates how many bytes of memory is used by \nn\n number of elements, when individual element size is \nblksize\n bytes.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nn\n\n\nNumber of elements\n\n\n\n\n\n\nblksize\n\n\nSize of an element is number of bytes\n\n\n\n\n\n\n\n\nReturned values\n\n\nList any values returned.\nError codes?\n\n\nNotes\n\n\nExample\n\n\nHere we allocate memory to be used as a pool.\n\n\nvoid *nffs_file_mem;\n\nnffs_file_mem = malloc(\n OS_MEMPOOL_BYTES(nffs_config.nc_num_files, sizeof (struct nffs_file)));\n if (nffs_file_mem == NULL) {\n return FS_ENOMEM;\n }",
+ "text": "OS_MEMPOOL_BYTES\n\n\nOS_MEMPOOL_BYTES(n,blksize)\n\n\n\n\nCalculates how many bytes of memory is used by \nn\n number of elements, when individual element size is \nblksize\n bytes.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nn\n\n\nNumber of elements\n\n\n\n\n\n\nblksize\n\n\nSize of an element is number of bytes\n\n\n\n\n\n\n\n\nReturned values\n\n\nThe number of bytes used by the memory pool.\n\n\n\n\nNotes\n\n\nOS_MEMPOOL_BYTES is a macro and not a function.\n\n\n\n\nExample\n\n\nHere we allocate memory to be used as a pool.\n\n\n void *nffs_file_mem;\n\n nffs_file_mem = malloc(OS_MEMPOOL_BYTES(nffs_config.nc_num_files, sizeof (struct nffs_file)));\n if (nffs_file_mem == NULL) {\n return FS_ENOMEM;\n }",
"title": "OS_MEMPOOL_BYTES"
},
{
@@ -997,17 +992,47 @@
},
{
"location": "/os/core_os/memory_pool/OS_MEMPOOL_BYTES/#returned-values",
- "text": "List any values returned.\nError codes?",
+ "text": "The number of bytes used by the memory pool.",
"title": "Returned values"
},
{
"location": "/os/core_os/memory_pool/OS_MEMPOOL_BYTES/#notes",
- "text": "",
+ "text": "OS_MEMPOOL_BYTES is a macro and not a function.",
"title": "Notes"
},
{
"location": "/os/core_os/memory_pool/OS_MEMPOOL_BYTES/#example",
- "text": "Here we allocate memory to be used as a pool. void *nffs_file_mem;\n\nnffs_file_mem = malloc(\n OS_MEMPOOL_BYTES(nffs_config.nc_num_files, sizeof (struct nffs_file)));\n if (nffs_file_mem == NULL) {\n return FS_ENOMEM;\n }",
+ "text": "Here we allocate memory to be used as a pool. void *nffs_file_mem;\n\n nffs_file_mem = malloc(OS_MEMPOOL_BYTES(nffs_config.nc_num_files, sizeof (struct nffs_file)));\n if (nffs_file_mem == NULL) {\n return FS_ENOMEM;\n }",
+ "title": "Example"
+ },
+ {
+ "location": "/os/core_os/memory_pool/OS_MEMPOOL_SIZE/",
+ "text": "OS_MEMPOOL_SIZE\n\n\nOS_MEMPOOL_SIZE(n,blksize)\n\n\n\n\nCalculates the number of os_membuf_t elements used by \nn\n blocks of size \nblksize\n bytes.\n\n\nNote that os_membuf_t is used so that memory blocks are aligned on OS_ALIGNMENT boundaries.\n\n\nThe \nblksize\n variable is the minimum number of bytes required for each block; the actual block size is padded so that each block is aligned on OS_ALIGNMENT boundaries. \n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nn\n\n\nNumber of elements\n\n\n\n\n\n\nblksize\n\n\nSize of an element is number of bytes\n\n\n\n\n\n\n\n\nReturned values\n\n\nThe number of os_membuf_t elements used by the memory pool. Note that os_membuf_t is defined to be a unsigned, 32-bit integer when OS_ALIGNMENT is 4 and an unsigned, 64-bit integer when OS_ALIGNMENT is 8.\n\n\n\n\nNotes\n\n\nOS_MEMPOOL_SIZE is a macro and not a function.\n\n\n\n\nExample\n\n\nHere we define a memory buffer to be used by
a memory pool using OS_MEMPOOL_SIZE\n\n\n#define NUM_BLOCKS (16)\n#define BLOCK_SIZE (32)\n\nos_membuf_t my_pool_memory[OS_MEMPOOL_SIZE(NUM_BLOCKS, BLOCK_SIZE)]",
+ "title": "OS_MEMPOOL_SIZE"
+ },
+ {
+ "location": "/os/core_os/memory_pool/OS_MEMPOOL_SIZE/#os_mempool_size",
+ "text": "OS_MEMPOOL_SIZE(n,blksize) Calculates the number of os_membuf_t elements used by n blocks of size blksize bytes. Note that os_membuf_t is used so that memory blocks are aligned on OS_ALIGNMENT boundaries. The blksize variable is the minimum number of bytes required for each block; the actual block size is padded so that each block is aligned on OS_ALIGNMENT boundaries.",
+ "title": "OS_MEMPOOL_SIZE"
+ },
+ {
+ "location": "/os/core_os/memory_pool/OS_MEMPOOL_SIZE/#arguments",
+ "text": "Arguments Description n Number of elements blksize Size of an element is number of bytes",
+ "title": "Arguments"
+ },
+ {
+ "location": "/os/core_os/memory_pool/OS_MEMPOOL_SIZE/#returned-values",
+ "text": "The number of os_membuf_t elements used by the memory pool. Note that os_membuf_t is defined to be a unsigned, 32-bit integer when OS_ALIGNMENT is 4 and an unsigned, 64-bit integer when OS_ALIGNMENT is 8.",
+ "title": "Returned values"
+ },
+ {
+ "location": "/os/core_os/memory_pool/OS_MEMPOOL_SIZE/#notes",
+ "text": "OS_MEMPOOL_SIZE is a macro and not a function.",
+ "title": "Notes"
+ },
+ {
+ "location": "/os/core_os/memory_pool/OS_MEMPOOL_SIZE/#example",
+ "text": "Here we define a memory buffer to be used by a memory pool using OS_MEMPOOL_SIZE #define NUM_BLOCKS (16)\n#define BLOCK_SIZE (32)\n\nos_membuf_t my_pool_memory[OS_MEMPOOL_SIZE(NUM_BLOCKS, BLOCK_SIZE)]",
"title": "Example"
},
{
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/0760c397/os/core_os/memory_pool/OS_MEMPOOL_BYTES/index.html
----------------------------------------------------------------------
diff --git a/os/core_os/memory_pool/OS_MEMPOOL_BYTES/index.html b/os/core_os/memory_pool/OS_MEMPOOL_BYTES/index.html
index 0d2dd53..f9bd323 100644
--- a/os/core_os/memory_pool/OS_MEMPOOL_BYTES/index.html
+++ b/os/core_os/memory_pool/OS_MEMPOOL_BYTES/index.html
@@ -295,6 +295,14 @@
+
+
+ <li>
+ <a href="../OS_MEMPOOL_SIZE/">OS_MEMPOOL_SIZE</a>
+ </li>
+
+
+
</ul>
</li>
@@ -509,6 +517,7 @@
</code></pre>
<p>Calculates how many bytes of memory is used by <em>n</em> number of elements, when individual element size is <em>blksize</em> bytes.</p>
+<p><br></p>
<h4 id="arguments">Arguments<a class="headerlink" href="#arguments" title="Permanent link">¶</a></h4>
<table>
<thead>
@@ -529,15 +538,16 @@
</tbody>
</table>
<h4 id="returned-values">Returned values<a class="headerlink" href="#returned-values" title="Permanent link">¶</a></h4>
-<p>List any values returned.
-Error codes?</p>
+<p>The number of bytes used by the memory pool.</p>
+<p><br></p>
<h4 id="notes">Notes<a class="headerlink" href="#notes" title="Permanent link">¶</a></h4>
+<p>OS_MEMPOOL_BYTES is a macro and not a function.</p>
+<p><br></p>
<h4 id="example">Example<a class="headerlink" href="#example" title="Permanent link">¶</a></h4>
<p>Here we allocate memory to be used as a pool.</p>
-<pre><code class="no-highlight">void *nffs_file_mem;
+<pre><code class="no-highlight"> void *nffs_file_mem;
-nffs_file_mem = malloc(
- OS_MEMPOOL_BYTES(nffs_config.nc_num_files, sizeof (struct nffs_file)));
+ nffs_file_mem = malloc(OS_MEMPOOL_BYTES(nffs_config.nc_num_files, sizeof (struct nffs_file)));
if (nffs_file_mem == NULL) {
return FS_ENOMEM;
}
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/0760c397/os/core_os/memory_pool/OS_MEMPOOL_SIZE/index.html
----------------------------------------------------------------------
diff --git a/os/core_os/memory_pool/OS_MEMPOOL_SIZE/index.html b/os/core_os/memory_pool/OS_MEMPOOL_SIZE/index.html
new file mode 100644
index 0000000..2b53ac0
--- /dev/null
+++ b/os/core_os/memory_pool/OS_MEMPOOL_SIZE/index.html
@@ -0,0 +1,598 @@
+<!DOCTYPE html>
+<html lang="en">
+ <head>
+ <meta charset="utf-8">
+ <meta http-equiv="X-UA-Compatible" content="IE=edge">
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
+
+
+ <link rel="canonical" href="http://mynewt.incubator.apache.org/os/core_os/memory_pool/OS_MEMPOOL_SIZE/">
+ <link rel="shortcut icon" href="../../../../img/favicon.ico">
+
+ <title>OS_MEMPOOL_SIZE - Apache Mynewt</title>
+
+ <link href="../../../../css/bootstrap-3.0.3.min.css" rel="stylesheet">
+ <link href="../../../../css/font-awesome-4.0.3.css" rel="stylesheet">
+ <link rel="stylesheet" href="../../../../css/highlight.css">
+ <link href="../../../../css/base.css" rel="stylesheet">
+ <link href="../../../../css/custom.css" rel="stylesheet">
+ <link href='https://fonts.googleapis.com/css?family=Roboto:400,500,700,900,300,100' rel='stylesheet' type='text/css'>
+ <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css">
+ <link href="../../../../extra.css" rel="stylesheet">
+
+ <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
+ <!--[if lt IE 9]>
+ <script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
+ <script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
+ <![endif]-->
+
+
+ <script>
+ (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
+ m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+ })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
+
+ ga('create', 'UA-72162311-1', 'mynewt.incubator.apache.org');
+ ga('send', 'pageview');
+ </script>
+
+ </head>
+
+
+ <body class="OS_MEMPOOL_SIZE">
+
+
+ <div class="navbar navbar-default navbar-fixed-top" role="navigation">
+ <div class="logo-container">
+ <img src="/img/logo.svg">
+ </div>
+ <div class="container-fluid">
+ <!-- Collapsed navigation -->
+ <div class="navbar-header">
+ <!-- Expander button -->
+ <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
+ <span class="sr-only">Toggle navigation</span>
+ <span class="icon-bar"></span>
+ <span class="icon-bar"></span>
+ <span class="icon-bar"></span>
+ </button>
+
+ </div>
+
+ <!-- Expanded navigation -->
+ <div class="navbar-collapse collapse">
+ <!-- Main navigation -->
+ <ul class="nav navbar-nav navbar-right">
+ <li>
+ <a href="/">Home</a>
+ </li>
+ <li>
+ <a href="/documentation/">Docs</a>
+ </li>
+ <li>
+ <a href="/download/">Download</a>
+ </li>
+ <li>
+ <a href="/community/">Community</a>
+ </li>
+ <li>
+ <a href="/events/">Events</a>
+ </li>
+ </ul>
+
+ <!-- Search, Navigation and Repo links -->
+ <ul class="nav navbar-nav navbar-right">
+
+ </ul>
+ </div>
+ </div>
+</div>
+
+ <div class="container-fluid">
+
+ <div class="row sm-extra-padding">
+ <div class="col-md-3 bg-grey sidebar-container"><div class="bs-sidebar hidden-print" role="complementary">
+ <div class="sidebar-top">
+ <img class="hidden-xs hidden-sm logo-small" src="/img/logo.svg" alt="MyNewt" title="MyNewt">
+ <div class="small" role="search">
+ <form id ="rtd-search-form" class="wy-form" action="../../../../search.html" method="get">
+ <div class="form-group">
+ <input type="text" name="q" placeholder="Search documentation" />
+ <button class="search-button" type="submit"><i class="fa fa-search"></i></button>
+ </div>
+ </form>
+ </div>
+ </div>
+ <ul class="nav bs-sidenav">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <li><a href="
+ ../../../get_started/introduction/
+">Apache Mynewt Manual</a>
+
+ <ul class="current-toc">
+
+
+
+ <li>
+ <a href="../../../get_started/introduction/">Introduction</a>
+ </li>
+
+
+
+
+
+ <li><a href="
+ ../../../get_started/project1/
+">Get Started</a>
+
+ </li>
+
+
+
+
+ <li><a href="
+ ../../../get_acclimated/project2/
+">Tutorials</a>
+
+ </li>
+
+
+
+
+ <li><a href="
+
+
+
+
+ ../../mynewt_os/
+
+
+">Manual</a>
+
+ <ul class="current-toc">
+
+
+
+ <li><a href="
+
+
+ ../../mynewt_os/
+
+">OS Core</a>
+
+ <ul class="current-toc">
+
+
+
+ <li><a href="
+ ../../mynewt_os/
+">OS Fundamentals</a>
+
+ </li>
+
+
+
+
+ <li><a href="
+ ../../context_switch/context_switch/
+">Scheduler</a>
+
+ </li>
+
+
+
+
+ <li><a href="
+ ../../time/time/
+">Time</a>
+
+ </li>
+
+
+
+
+ <li><a href="
+ ../../task/task/
+">Tasks</a>
+
+ </li>
+
+
+
+
+ <li><a href="
+ ../../event_queue/event_queue/
+">Event Queues</a>
+
+ </li>
+
+
+
+
+ <li><a href="
+ ../../semaphore/semaphore/
+">Semaphores</a>
+
+ </li>
+
+
+
+
+ <li><a href="
+ ../../mutex/mutex/
+">Mutexes</a>
+
+ </li>
+
+
+
+
+ <li><a href="
+ ../memory_pool/
+">Memory Pools</a>
+
+ <ul class="current-toc">
+
+
+
+ <li>
+ <a href="../memory_pool/">Overview</a>
+ </li>
+
+
+
+
+
+ <li><a href="
+ ../os_memblock_get/
+">Functions</a>
+
+ <ul class="current-toc">
+
+
+
+ <li>
+ <a href="../os_memblock_get/">os_memblock_get</a>
+ </li>
+
+
+
+
+
+ <li>
+ <a href="../os_mempool_init/">os_mempool_init</a>
+ </li>
+
+
+
+
+
+ <li>
+ <a href="../os_memblock_put/">os_memblock_put</a>
+ </li>
+
+
+
+
+
+ <li>
+ <a href="../OS_MEMPOOL_BYTES/">OS_MEMPOOL_BYTES</a>
+ </li>
+
+
+
+
+
+ <li class="active">
+ OS_MEMPOOL_SIZE
+ </li>
+
+
+
+ </ul>
+
+ </li>
+
+
+ </ul>
+
+ </li>
+
+
+
+
+ <li><a href="
+ ../../heap/heap/
+">Heap</a>
+
+ </li>
+
+
+
+
+ <li><a href="
+ ../../mbuf/mbuf/
+">Mbufs</a>
+
+ </li>
+
+
+
+
+ <li><a href="
+ ../../sanity/sanity/
+">Sanity</a>
+
+ </li>
+
+
+
+
+ <li><a href="
+ ../../callout/callout/
+">Callouts</a>
+
+ </li>
+
+
+
+
+ <li>
+ <a href="../../port_os/">Porting to other Platforms</a>
+ </li>
+
+
+
+ </ul>
+
+ </li>
+
+
+
+
+ <li><a href="
+ ../../../modules/console/console/
+">Console</a>
+
+ </li>
+
+
+
+
+ <li><a href="
+ ../../../modules/shell/shell/
+">Shell</a>
+
+ </li>
+
+
+
+
+ <li><a href="
+ ../../../modules/bootloader/bootloader/
+">Bootloader</a>
+
+ </li>
+
+
+
+
+ <li>
+ <a href="../../../modules/filesystem/">File System Abstraction</a>
+ </li>
+
+
+
+
+
+ <li>
+ <a href="../../../modules/nffs/">Newtron Flash File System</a>
+ </li>
+
+
+
+
+
+ <li><a href="
+ ../../../modules/testutil/testutil/
+">Test Utilities</a>
+
+ </li>
+
+
+
+
+ <li><a href="
+ ../../../modules/imgmgr/imgmgr/
+">Image Manager</a>
+
+ </li>
+
+
+
+
+ <li>
+ <a href="../../../modules/baselibc/">Baselibc library</a>
+ </li>
+
+
+
+
+
+ <li><a href="
+ ../../../modules/elua/elua/
+">Embedded Lua</a>
+
+ </li>
+
+
+
+
+ <li><a href="
+ ../../../modules/json/json/
+">JSON</a>
+
+ </li>
+
+
+ </ul>
+
+ </li>
+
+
+ </ul>
+
+ </li>
+
+
+
+
+
+
+ <li><a href="
+ ../../../../newt/newt_intro/
+">Newt Tool Manual</a>
+
+ </li>
+
+
+
+
+
+
+ <li><a href="
+ ../../../../newtmgr/overview/
+">Newt Manager Manual</a>
+
+ </li>
+
+
+
+ </ul>
+</div></div>
+
+ <div class="show-sidebar-container">
+ <button class="show-sidebar">Docs Menu</button>
+ </div>
+
+ <div class="col-md-9 documentation-viewer" role="main">
+ <div role="navigation" aria-label="breadcrumbs navigation">
+ <ul class="wy-breadcrumbs">
+ <li><a href="../../../..">Docs</a> »</li>
+
+
+
+ <li>Memory Pools »</li>
+
+
+
+ <li>Functions »</li>
+
+
+
+ <li>OS_MEMPOOL_SIZE</li>
+ <li class="wy-breadcrumbs-aside">
+
+ </li>
+ </ul>
+ <hr/>
+</div>
+
+ <h2 id="os_mempool_size"><font color="#F2853F" style="font-size:24pt">OS_MEMPOOL_SIZE</font><a class="headerlink" href="#os_mempool_size" title="Permanent link">¶</a></h2>
+<pre><code class="no-highlight">OS_MEMPOOL_SIZE(n,blksize)
+</code></pre>
+
+<p>Calculates the number of os_membuf_t elements used by <em>n</em> blocks of size <em>blksize</em> bytes.</p>
+<p>Note that os_membuf_t is used so that memory blocks are aligned on OS_ALIGNMENT boundaries.</p>
+<p>The <em>blksize</em> variable is the minimum number of bytes required for each block; the actual block size is padded so that each block is aligned on OS_ALIGNMENT boundaries. </p>
+<p><br></p>
+<h4 id="arguments">Arguments<a class="headerlink" href="#arguments" title="Permanent link">¶</a></h4>
+<table>
+<thead>
+<tr>
+<th>Arguments</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>n</td>
+<td>Number of elements</td>
+</tr>
+<tr>
+<td>blksize</td>
+<td>Size of an element is number of bytes</td>
+</tr>
+</tbody>
+</table>
+<h4 id="returned-values">Returned values<a class="headerlink" href="#returned-values" title="Permanent link">¶</a></h4>
+<p>The number of os_membuf_t elements used by the memory pool. Note that os_membuf_t is defined to be a unsigned, 32-bit integer when OS_ALIGNMENT is 4 and an unsigned, 64-bit integer when OS_ALIGNMENT is 8.</p>
+<p><br></p>
+<h4 id="notes">Notes<a class="headerlink" href="#notes" title="Permanent link">¶</a></h4>
+<p>OS_MEMPOOL_SIZE is a macro and not a function.</p>
+<p><br></p>
+<h4 id="example">Example<a class="headerlink" href="#example" title="Permanent link">¶</a></h4>
+<p>Here we define a memory buffer to be used by a memory pool using OS_MEMPOOL_SIZE</p>
+<pre><code class="no-highlight">#define NUM_BLOCKS (16)
+#define BLOCK_SIZE (32)
+
+os_membuf_t my_pool_memory[OS_MEMPOOL_SIZE(NUM_BLOCKS, BLOCK_SIZE)]
+</code></pre>
+
+<hr />
+
+ </div>
+ </div>
+
+ <div class="row">
+ <footer>
+ <div class="row">
+ <div class="col-md-12">
+
+ <p class="copyright">Copyright © 2015 The Apache Software Foundation, Licensed under the Apache License, Version 2.0 Apache and the Apache feather logo are trademarks of The Apache Software Foundation.<br>The Apache Software Foundation Apache Incubator</p>
+
+ </div>
+ </div>
+ <div class="copyright-logos">
+ <div class="row">
+ <div class="col-xs-6 text-right">
+ <img src="/img/apache-feather.png" alt="Apache" title="Apache">
+ </div>
+ <div class="col-xs-6 text-left">
+ <img src="/img/apache-logo.png" alt="Apache Incubator" title="Apache Incubator">
+ </div>
+ </div>
+ </div>
+ <div class="row">
+ <div class="col-md-12">
+ <small class="footnote">
+ MyNewt is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Apache Incubator. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF.
+ </small>
+ </div>
+ </div>
+</footer>
+ </div>
+ </div>
+
+ <script src="../../../../js/jquery-1.10.2.min.js"></script>
+ <script src="../../../../js/bootstrap-3.0.3.min.js"></script>
+ <script src="../../../../js/highlight.pack.js"></script>
+ <script src="../../../../js/base.js"></script>
+ <script src="../../../../js/custom.js"></script>
+
+ </body>
+</html>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/0760c397/os/core_os/memory_pool/memory_pool/index.html
----------------------------------------------------------------------
diff --git a/os/core_os/memory_pool/memory_pool/index.html b/os/core_os/memory_pool/memory_pool/index.html
index 3befe5a..5a20156 100644
--- a/os/core_os/memory_pool/memory_pool/index.html
+++ b/os/core_os/memory_pool/memory_pool/index.html
@@ -469,32 +469,55 @@
</div>
<h1 id="memory-pools">Memory Pools<a class="headerlink" href="#memory-pools" title="Permanent link">¶</a></h1>
-<p>Memory can be pre-allocated to a pool of fixed size elements.</p>
+<p>A memory pool is a collection of fixed sized elements called memory blocks. Generally, memory pools are used when the developer wants to allocate a certain amount of memory to a given feature. Unlike the heap, where a code module is at the mercy of other code modules to insure there is sufficient memory, memory pools can insure sufficient memory allocation.</p>
<h2 id="description">Description<a class="headerlink" href="#description" title="Permanent link">¶</a></h2>
-<p>Sometimes it's useful to have several memory blocks of same size preallocated for specific use. E.g. you want to limit the amount of memory used for it, or you want to make sure that there is memory available when you ask for it.</p>
-<p>This can be done using a memory pool. You allocate memory either statically or from heap, and then designate that memory to be used as storage for fixed size elements.</p>
-<p>Pool will be initialized by calling <em>os_mempool_init()</em>. Element can be allocated from it with <em>os_mempool_get()</em>, and released back with <em>os_mempool_put()</em>.</p>
+<p>In order to create a memory pool the developer needs to do a few things. The first task is to define the memory pool itself. This is a data structure which contains information about the pool itself (i.e. number of blocks, size of the blocks, etc).</p>
+<pre><code class="no-highlight">struct os_mempool my_pool;
+</code></pre>
+
+<p><br>
+The next order of business is to allocate the memory used by the memory pool. This memory can either be statically allocated (i.e. a global variable) or dynamically allocated (i.e. from the heap). When determining the amount of memory required for the memory pool, simply multiplying the number of blocks by the size of each block is not sufficient as the OS may have alignment requirements. The alignment size definition is named <code>OS_ALIGNMENT</code> and can be found in os_arch.h as it is architecture specific. The memory block alignment is usually for efficiency but may be due to other reasons. Generally, blocks are aligned on 32-bit boundaries. Note that memory blocks must also be of sufficient size to hold a list pointer as this is needed to chain memory blocks on the free list.</p>
+<p>In order to simplify this for the user two macros have been provided: <code>OS_MEMPOOL_BYTES(n, blksize)</code> and <code>OS_MEMPOOL_SIZE(n, blksize)</code>. The first macro returns the number of bytes needed for the memory pool while the second returns the number of <code>os_membuf_t</code> elements required by the memory pool. The <code>os_membuf_t</code> type is used to guarantee that the memory buffer used by the memory pool is aligned on the correct boundary. </p>
+<p>Here are some examples. Note that if a custom malloc implementation is used it must guarantee that the memory buffer used by the pool is allocated on the correct boundary (i.e. OS_ALIGNMENT).</p>
+<pre><code class="no-highlight">void *my_memory_buffer;
+my_memory_buffer = malloc(OS_MEMPOOL_BYTES(NUM_BLOCKS, BLOCK_SIZE));
+</code></pre>
+
+<pre><code class="no-highlight">os_membuf_t my_memory_buffer[OS_MEMPOOL_SIZE(NUM_BLOCKS, BLOCK_SIZE)];
+</code></pre>
+
+<p><br>
+Now that the memory pool has been defined as well as the memory required for the memory blocks which make up the pool the user needs to initialize the memory pool by calling <code>os_mempool_init</code>.</p>
+<pre><code class="no-highlight">os_mempool_init(&my_pool, NUM_BLOCKS, BLOCK_SIZE, my_memory_buffer,
+ "MyPool");
+</code></pre>
+
+<p><br>
+Once the memory pool has been initialized the developer can allocate memory blocks from the pool by calling <code>os_memblock_get</code>. When the memory block is no longer needed the memory can be freed by calling <code>os_memblock_put</code>. </p>
<h2 id="data-structures">Data structures<a class="headerlink" href="#data-structures" title="Permanent link">¶</a></h2>
<pre><code class="no-highlight">struct os_mempool {
int mp_block_size;
int mp_num_blocks;
int mp_num_free;
+ uint32_t mp_membuf_addr;
+ STAILQ_ENTRY(os_mempool) mp_list;
SLIST_HEAD(,os_memblock);
char *name;
};
</code></pre>
+<p><br></p>
<table>
<thead>
<tr>
-<th>Element</th>
-<th>Description</th>
+<th><strong>Element</strong></th>
+<th><strong>Description</strong></th>
</tr>
</thead>
<tbody>
<tr>
<td>mp_block_size</td>
-<td>Size of the memory blocks, in bytes</td>
+<td>Size of the memory blocks, in bytes. This is not the actual number of bytes used by each block; it is the requested size of each block. The actual memory block size will be aligned to OS_ALIGNMENT bytes</td>
</tr>
<tr>
<td>mp_num_blocks</td>
@@ -505,6 +528,18 @@
<td>Number of free blocks left</td>
</tr>
<tr>
+<td>mp_membuf_addr</td>
+<td>The address of the memory block. This is used to check that a valid memory block is being freed.</td>
+</tr>
+<tr>
+<td>mp_list</td>
+<td>List pointer to chain memory pools so they can be displayed by newt tools</td>
+</tr>
+<tr>
+<td>SLIST_HEAD(,os_memblock)</td>
+<td>List pointer to chain free memory blocks</td>
+</tr>
+<tr>
<td>name</td>
<td>Name for the memory block</td>
</tr>
@@ -517,6 +552,7 @@
<li><a href="../os_mempool_init">os_mempool_init</a></li>
<li><a href="../os_memblock_put">os_memblock_put</a></li>
<li><a href="../OS_MEMPOOL_BYTES">OS_MEMPOOL_BYTES</a></li>
+<li><a href="../OS_MEMPOOL_SIZE">OS_MEMPOOL_SIZE</a></li>
</ul>
</div>
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/0760c397/os/core_os/memory_pool/os_memblock_get/index.html
----------------------------------------------------------------------
diff --git a/os/core_os/memory_pool/os_memblock_get/index.html b/os/core_os/memory_pool/os_memblock_get/index.html
index 28d1fcc..9569121 100644
--- a/os/core_os/memory_pool/os_memblock_get/index.html
+++ b/os/core_os/memory_pool/os_memblock_get/index.html
@@ -295,6 +295,14 @@
+
+
+ <li>
+ <a href="../OS_MEMPOOL_SIZE/">OS_MEMPOOL_SIZE</a>
+ </li>
+
+
+
</ul>
</li>
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/0760c397/os/core_os/memory_pool/os_memblock_put/index.html
----------------------------------------------------------------------
diff --git a/os/core_os/memory_pool/os_memblock_put/index.html b/os/core_os/memory_pool/os_memblock_put/index.html
index a119b3f..a076668 100644
--- a/os/core_os/memory_pool/os_memblock_put/index.html
+++ b/os/core_os/memory_pool/os_memblock_put/index.html
@@ -295,6 +295,14 @@
+
+
+ <li>
+ <a href="../OS_MEMPOOL_SIZE/">OS_MEMPOOL_SIZE</a>
+ </li>
+
+
+
</ul>
</li>
@@ -508,7 +516,8 @@
<pre><code class="no-highlight">os_error_t os_memblock_put(struct os_mempool *mp, void *block_addr)
</code></pre>
-<p>Releases previously allocated element back to the pool.</p>
+<p>Releases previously allocated element back to the pool. </p>
+<p><br></p>
<h4 id="arguments">Arguments<a class="headerlink" href="#arguments" title="Permanent link">¶</a></h4>
<table>
<thead>
@@ -520,7 +529,7 @@
<tbody>
<tr>
<td>mp</td>
-<td>Pointer to memory pool where element is put</td>
+<td>Pointer to memory pool from which block was allocated</td>
</tr>
<tr>
<td>block_addr</td>
@@ -528,16 +537,17 @@
</tr>
</tbody>
</table>
+<p><br></p>
<h4 id="returned-values">Returned values<a class="headerlink" href="#returned-values" title="Permanent link">¶</a></h4>
-<p>OS_OK: operation was a success:
-OS_INVALID_PARAM: If either mp or block_addr were NULL.</p>
-<h4 id="notes">Notes<a class="headerlink" href="#notes" title="Permanent link">¶</a></h4>
+<p>OS_OK: operation was a success:<br />
+OS_INVALID_PARAM: If either mp or block_addr were NULL, or the block being freed was outside the range of the memory buffer or not on a true block size boundary.</p>
+<p><br></p>
<h4 id="example">Example<a class="headerlink" href="#example" title="Permanent link">¶</a></h4>
<p><Add text to set up the context for the example here></p>
<pre><code class="no-highlight"> if (file != NULL) {
rc = os_memblock_put(&nffs_file_pool, file);
if (rc != 0) {
- return FS_EOS;
+ /* Error freeing memory block */
}
}
</code></pre>
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/0760c397/os/core_os/memory_pool/os_mempool_init/index.html
----------------------------------------------------------------------
diff --git a/os/core_os/memory_pool/os_mempool_init/index.html b/os/core_os/memory_pool/os_mempool_init/index.html
index ec2a4bb..cb0ce9a 100644
--- a/os/core_os/memory_pool/os_mempool_init/index.html
+++ b/os/core_os/memory_pool/os_mempool_init/index.html
@@ -295,6 +295,14 @@
+
+
+ <li>
+ <a href="../OS_MEMPOOL_SIZE/">OS_MEMPOOL_SIZE</a>
+ </li>
+
+
+
</ul>
</li>
@@ -508,7 +516,7 @@
<pre><code class="no-highlight">os_error_t os_mempool_init(struct os_mempool *mp, int blocks, int block_size, void *membuf, char *name)
</code></pre>
-<p>Initializes the memory pool. Memory pointed by <em>membuf</em> is taken and <em>blocks</em> number of elements of size <em>block_size</em> are added to the pool. <em>name</em> is optional, and names the memory pool.</p>
+<p>Initializes the memory pool. Memory pointed to by <em>membuf</em> is divided into <em>blocks</em> number of elements of size OS_ALIGN(<em>block_size</em>). The <em>name</em> is optional, and names the memory pool.</p>
<p>It is assumed that the amount of memory pointed by <em>membuf</em> has at least <em>OS_MEMPOOL_BYTES(blocks, block_size)</em> number of bytes.</p>
<p><em>name</em> is not copied, so caller should make sure that the memory does not get reused.</p>
<h4 id="arguments">Arguments<a class="headerlink" href="#arguments" title="Permanent link">¶</a></h4>
@@ -530,7 +538,7 @@
</tr>
<tr>
<td>block_size</td>
-<td>Size of an individual element in pool</td>
+<td>Minimum size of an individual element in pool</td>
</tr>
<tr>
<td>membuf</td>
@@ -543,19 +551,23 @@
</tbody>
</table>
<h4 id="returned-values">Returned values<a class="headerlink" href="#returned-values" title="Permanent link">¶</a></h4>
-<p>OS_OK: operation was successful.
-OS_INVALID_PARAM: invalid parameters. Block count or block size was negative, or membuf or mp was NULL.
-OS_MEM_NOT_ALIGNED: membuf has to be aligned to 4 byte boundary.</p>
+<p>OS_OK: operation was successful.<br />
+OS_INVALID_PARAM: invalid parameters. Block count or block size was negative, or membuf or mp was NULL.<br />
+OS_MEM_NOT_ALIGNED: membuf was not aligned on correct byte boundary.</p>
<h4 id="notes">Notes<a class="headerlink" href="#notes" title="Permanent link">¶</a></h4>
-<p>Note that os_mempool_init() does not allocate backing storage. <em>membuf</em> has to be allocated by the caller.</p>
-<p>It's recommended that you use <em>OS_MEMPOOL_BYTES()</em> to figure out how much memory to allocate for the pool.</p>
+<p>Note that os_mempool_init() does not allocate backing storage; <em>membuf</em> has to be allocated by the caller.</p>
+<p>It's recommended that you use <em>OS_MEMPOOL_BYTES()</em> or <em>OS_MEMPOOL_SIZE()</em> to figure out how much memory to allocate for the pool.</p>
<h4 id="example">Example<a class="headerlink" href="#example" title="Permanent link">¶</a></h4>
<p><Add text to set up the context for the example here></p>
-<pre><code class="no-highlight"> rc = os_mempool_init(&nffs_file_pool, nffs_config.nc_num_files,
+<pre><code class="no-highlight"> void *nffs_file_mem;
+
+ nffs_file_mem = malloc(OS_MEMPOOL_BYTES(nffs_config.nc_num_files, sizeof (struct nffs_file)));
+
+ rc = os_mempool_init(&nffs_file_pool, nffs_config.nc_num_files,
sizeof (struct nffs_file), nffs_file_mem,
"nffs_file_pool");
if (rc != 0) {
- return FS_EOS;
+ /* Memory pool initialization failure */
}
</code></pre>
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/0760c397/sitemap.xml
----------------------------------------------------------------------
diff --git a/sitemap.xml b/sitemap.xml
index f02b10f..cb6de09 100644
--- a/sitemap.xml
+++ b/sitemap.xml
@@ -4,7 +4,7 @@
<url>
<loc>http://mynewt.incubator.apache.org/</loc>
- <lastmod>2016-02-24</lastmod>
+ <lastmod>2016-02-25</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -12,7 +12,7 @@
<url>
<loc>http://mynewt.incubator.apache.org/documentation/</loc>
- <lastmod>2016-02-24</lastmod>
+ <lastmod>2016-02-25</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -20,7 +20,7 @@
<url>
<loc>http://mynewt.incubator.apache.org/download/</loc>
- <lastmod>2016-02-24</lastmod>
+ <lastmod>2016-02-25</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -28,7 +28,7 @@
<url>
<loc>http://mynewt.incubator.apache.org/community/</loc>
- <lastmod>2016-02-24</lastmod>
+ <lastmod>2016-02-25</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -36,7 +36,7 @@
<url>
<loc>http://mynewt.incubator.apache.org/events/</loc>
- <lastmod>2016-02-24</lastmod>
+ <lastmod>2016-02-25</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -45,7 +45,7 @@
<url>
<loc>http://mynewt.incubator.apache.org/os/get_started/introduction/</loc>
- <lastmod>2016-02-24</lastmod>
+ <lastmod>2016-02-25</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -73,7 +73,7 @@
<url>
<loc>http://mynewt.incubator.apache.org/newt/newt_intro/</loc>
- <lastmod>2016-02-24</lastmod>
+ <lastmod>2016-02-25</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -95,7 +95,7 @@
<url>
<loc>http://mynewt.incubator.apache.org/newtmgr/overview/</loc>
- <lastmod>2016-02-24</lastmod>
+ <lastmod>2016-02-25</lastmod>
<changefreq>daily</changefreq>
</url>