OSMemCreate
Description
Creates and initializes a memory partition. A memory partition contains a user-specified number of fixed-size memory blocks. An application may obtain one of these memory blocks and, when completed, release the block back to the same partition where the block originated.
Files
os.h/os_mem.c
Prototype
void OSMemCreate (OS_MEM *p_mem,
CPU_CHAR *p_name,
void *p_addr,
OS_MEM_QTY n_blks,
OS_MEM_SIZE blk_size,
OS_ERR *p_err)
Arguments
p_mem
is a pointer to a memory partition control block that must be allocated in the application. It is assumed that storage will be allocated for the memory control blocks in the application. In other words, the user will declare a “global” variable as follows, and pass a pointer to this variable to OSMemCreate():
OS_MEM MyMemPartition;
p_name
is a pointer to an ASCII string to provide a name to the memory partition. The name can be displayed by debuggers or µC/Probe.
p_addr
is the address of the start of a memory area used to create fixed-size memory blocks. Memory partitions may be created using either static arrays or malloc() during startup. Note that the partition must align on a pointer boundary. Thus, if a pointer is 16-bits wide. the partition must start on a memory location with an address that ends with 0, 2, 4, 6, 8, etc. If a pointer is 32-bits wide, the partition must start on a memory location with an address that ends in 0, 4, 8 or C. The easiest way to ensure this is to create a static array as follows:
void *MyMemArray[N][M]
You should never deallocate memory blocks that were allocated from the heap to prevent fragmentation of your heap. It is quite acceptable to allocate memory blocks from the heap as long as the user does not deallocate them.
n_blks
contains the number of memory blocks available from the specified partition. You need to specify at least two memory blocks per partition.
blk_size
specifies the size (in bytes) of each memory block within a partition. A memory block must be large enough to hold at least a pointer. Also, the size of a memory block must be a multiple of the size of a pointer. If a pointer is 32-bits wide then the block size must be 4, 8, 12, 16, 20, etc. bytes (i.e., a multiple of 4 bytes).
p_err
is a pointer to a variable that holds an error code:
OS_ERR_NONE
If the memory partition is created successfully
OS_ERR_ILLEGAL_CREATE_RUN_TIME
If OS_SAFETY_CRITICAL_IEC61508 is defined: you called this after calling OSStart() and thus you are no longer allowed to create additional kernel objects.
OS_ERR_MEM_CREATE_ISR
If OS_CFG_CALLED_FROM_ISR_CHK_EN is set to DEF_ENABLED in os_cfg.h: if you called OSMemCreate() from an ISR.
OS_ERR_MEM_INVALID_BLKS
If OS_CFG_ARG_CHK_EN is set to DEF_ENABLED in os_cfg.h: if the user does not specify at least two memory blocks per partition
OS_ERR_MEM_INVALID_P_ADDR
If OS_CFG_ARG_CHK_EN is set to DEF_ENABLED in os_cfg.h: if specifying an invalid address (i.e., p_addr is a NULL pointer) or the partition is not properly aligned.
OS_ERR_MEM_INVALID_SIZE
If OS_CFG_ARG_CHK_EN is set to DEF_ENABLED in os_cfg.h: if the user does not specify a block size that can contain at least a pointer variable, and if it is not a multiple of a pointer-size variable.
Returned Value
None
Required Configuration
OS_CFG_MEM_EN must be enabled in os_cfg.h. Refer to µC-OS-III Configuration Manual.
Callers
Application.
Notes/Warnings
- Memory partitions must be created before they are used.
Example Usage
OS_MEM CommMem;
CPU_INT32U *CommBuf[16][32]; /* 16 buffers of 32 words of 32 bits */
void main (void)
{
OS_ERR err;
OSInit(&err); /* Initialize µC/OS-III */
:
:
OSMemCreate(&CommMem,
"Comm Buffers",
&CommBuf[0][0],
16,
32 * sizeof(CPU_INT32U),
&err);
/* Check "err" */
:
:
OSStart(&err); /* Start Multitasking */
}