Creating a Memory Partition

Before using a memory partition, it must be created. This allows µC/OS-III to know something about the memory partition so that it can manage their allocation and deallocation. Once created, a memory partition is as shown in the figure below. Calling OSMemCreate() creates a memory partition.

Created Memory Partition

(1) When creating a partition, the application code supplies the address of a memory partition control block (OS_MEM). Typically, this memory control block is allocated from static memory, however it can also be obtained from the heap by calling malloc(). The application code should however never deallocate it.

(2) OSMemCreate() organizes the continuous memory provided into a singly linked list and stores the pointer to the beginning of the list in the OS_MEM structure.

(3) Each memory block must be large enough to hold a pointer. Given the nature of the linked list, a block needs to be able to point to the next block.

The listing below indicates how to create a memory partition with µC/OS-III.

Creating a Memory Partition

          OS_MEM       MyPartition;                                    (1) 
          CPU_INT08U   MyPartitionStorage[12][100];                    (2) 
           
           
          void  main (void)                                            (3) 
          {
              OS_ERR  err;
              :
              :
              OSInit(&err);
              :
              OSMemCreate((OS_MEM    *)&MyPartition,                   (4) 
                          (CPU_CHAR  *)"My Partition",                 (5) 
                          (void      *)&MyPartitionStorage[0][0],      (6) 
                          (OS_MEM_QTY ) 12,                            (7) 
                          (OS_MEM_SIZE)100,                            (8) 
                          (OS_ERR    *)&err);                          (9) 
              /* Check 'err' */
              :
              :
              OSStart(&err);
          }

(1) An application needs to allocate storage for a memory partition control block (i.e. OS_MEM structure). This can be a static allocation as shown here or malloc() can be used in the code. However, the application code must not deallocate the memory control block.

(2) The application also needs to allocate storage for the memory that will be split into memory blocks. This can also be a static allocation or malloc() can be used. The same reasoning applies. Do not deallocate this storage since other tasks may rely on the existence of this storage.

(3) Memory partition must be created before allocating and deallocating blocks from the partition. One of the best places to create memory partitions is in main() prior to starting the multitasking process. Of course, an application can call a function from main() to do this instead of actually placing the code directly in main().

(4) You pass the address of the memory partition control block to OSMemCreate(). You should never reference any of the internal members of the OS_MEM data structure. Instead, you should always use µC/OS-III’s API.

(5) You can assign a name to the memory partition. There is no limit to the length of the ASCII string as µC/OS-III saves a pointer to the ASCII string in the partition control block and not the actual characters.

(6) You then need to pass the base address of the storage area reserved for the memory blocks.

(7) Here, you specify how many memory blocks are available from this memory partition. Hard coded numbers are used for the sake of the illustration but you should instead use #define constants.

(8) You need to specify the size of each memory block in the partition. Again, a hard coded value is used for illustration, which is not recommended in real code.

(9) As with most µC/OS-III services, OSMemCreate() returns an error code indicating the outcome of the service. The call is successful if “err” contains OS_ERR_NONE.

The listing below shows how to create a memory partition with µC/OS-III, but this time, using malloc() to allocate storage. Do not deallocate the memory control block or the storage for the partition.

Creating a Memory Partition

          OS_MEM      *MyPartitionPtr;                                         (1) 
           
           
          void  main (void)                                                  
          {
              OS_ERR   err;
              void    *p_storage;
              :
              OSInit(&err);
              :
              MyPartitionPtr = (OS_MEM *)malloc(sizeof(OS_MEM));               (2) 
              if (MyPartitionPtr != (OS_MEM *)0) {
                  p_storage = malloc(12 * 100);                                (3) 
                  if (p_storage != (void *)0) {
                      OSMemCreate((OS_MEM    *)MyPartitionPtr,                 (4) 
                                  (CPU_CHAR  *)"My Partition",            
                                  (void      *)p_storage,                      (5) 
                                  (OS_MEM_QTY ) 12,                            (6) 
                                  (OS_MEM_SIZE)100,                            (6) 
                                  (OS_ERR    *)&err); 
                      /* Check 'err" */                       
                  }
              }
              :
              OSStart(&err);
          }

(1) Instead of allocating static storage for the memory partition control block, you can assign a pointer that receives the OS_MEM allocated using malloc().

(2) The application allocates storage for the memory control block.

(3) We then allocate storage for the memory partition.

(4) A pointer is passed to the allocated memory control block to OSMemCreate().

(5) The base address of the storage used for the partition is passed to OSMemCreate().

(6) Finally, the number of blocks and the size of each block is passed so that µC/OS-III can create the linked list of 12 blocks of 100 bytes each. Again, hard coded numbers are used, but these would typically be replaced by #defines.