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

1. 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              */
          }