Pool Management

group OS_87x3e_Pool

Manage task-safe and fixed-size blocks of dynamic memory.

Memory pools are fixed-size blocks of memory that are task-safe. They operate much faster than the dynamically allocated heap and do not suffer from fragmentation. Being task-safe, they can be accessed from tasks and ISRs alike.

Shared memory is one of the basic models to exchange information between tasks. Using memory pools for exchanging data, you can share more complex objects between taks if compared to the Message Queue. Memory pool management functions are used to define and manage such fixed-sized memory pools.

Defines

OS_POOL_INVALID_HANDLE

The invalid pool handle. Valid pool handles should be less than OS_POOL_INVALID_HANDLE.

os_pool.h

os_pool_create(p_handle, ram_type, buf_size, buf_count)

Creates and initialize a memory pool.

os_pool.h

Example usage

#define BUF_SIZE 0x40
#define BUF_NUM  16

int test(void)
{
    uint8_t handle;

    // Create a memory pool capable of containing 16 buffers.
    if (os_pool_create(&handle, RAM_TYPE_DATA_ON, BUF_SIZE, BUF_NUM) == true)
    {
        // Memory pool created successfully.
    }
    else
    {
        // Memory pool failed to create.
        return -1;
    }

    return 0;
}

Parameters:

p_handle – [out] Used to pass back a handle by which the memory pool can be referenced.
ram_type – [in] RAM type for the memory pool buffer.
- RAM_TYPE_DATA_ON Data ON RAM type.
- RAM_TYPE_DATA_OFF Data OFF RAM type.
- RAM_TYPE_BUFFER_ON BUFFER ON RAM type.
- RAM_TYPE_BUFFER_OFF BUFFER OFF RAM type.
buf_size – [in] The pool buffer size in bytes.
buf_count – [in] The number of pool buffers allocated.

Return values:

true – Pool was created successfully.
false – Pool was failed to create.

Returns:

The status of the memory pool creation.

os_pool_extend(handle, buf_size, buf_count)

Extend a set of buffers to the created memory pool. The extended pool buffers have the same RAM type with the created buffers.

os_pool.h

Example usage

#define BUF_SIZE1 0x40
#define BUF_NUM1  16
#define BUF_SIZE2 0x20
#define BUF_NUM2  8

int test(void)
{
    uint8_t handle;

    // Create a memory pool capable of containing 16 buffers.
    if (os_pool_create(&handle, RAM_TYPE_DATA_ON, BUF_SIZE1, BUF_NUM1) == true)
    {
        // Memory pool created successfully.
    }
    else
    {
        // Memory pool failed to create.
        return -1;
    }

    // Extend the memory pool to have extra 8 buffers each in 0x20 bytes.
    os_pool_extend(handle, BUF_SIZE2, BUF_NUM2);

    return 0;
}

Parameters:

handle – [in] The handle of the created memory pool.
buf_size – [in] The pool buffer size in bytes.
buf_count – [in] The number of pool buffers allocated.

Return values:

true – Pool was extended successfully.
false – Pool was failed to extend.

Returns:

The status of the memory pool extension.

os_pool_delete(handle)

Delete a memory pool.

os_pool.h

Example usage

#define BUF_SIZE 0x40
#define BUF_NUM  16

int test(void)
{
    uint8_t handle;

    // Create a memory pool capable of containing 16 buffers.
    if (os_pool_create(&handle, RAM_TYPE_DATA_ON, BUF_SIZE, BUF_NUM) == true)
    {
        // Memory pool created successfully.
    }
    else
    {
        // Memory pool failed to create.
        return -1;
    }

    // Delete the memory pool.
    os_pool_delete(handle);

    return 0;
}

Parameters:

handle – [in] The handle of the memory pool to be deleted.

Return values:

true – Pool was deleted successfully.
false – Pool was failed to delete.

Returns:

The status of the memory pool deletion.

os_buffer_get(handle, buf_size)

Allocate a pool buffer from the specified memory pool. The allocated pool buffer size may be larger than the required size.

os_pool.h

Example usage

#define BUF_SIZE1 0x40
#define BUF_NUM1  16
#define BUF_SIZE2 0x20
#define BUF_NUM2  8

int test(void)
{
    uint8_t handle;
    void *p_buf;

    // Create a memory pool capable of containing 16 buffers.
    if (os_pool_create(&handle, RAM_TYPE_DATA_ON, BUF_SIZE1, BUF_NUM1) == true)
    {
        // Memory pool created successfully.
    }
    else
    {
        // Memory pool failed to create.
        return -1;
    }

    // Extend the memory pool to have extra 8 buffers each in 0x20 bytes.
    os_pool_extend(handle, BUF_SIZE2, BUF_NUM2);

    // Allocate a pool buffer in 0x30 bytes. While, the memory pool will
    // give a buffer in 0x40 bytes.
    p_buf = os_buffer_get(handle, 0x30);

    return 0;
}

Parameters:

handle – [in] The handle of the created memory pool.
buf_size – [in] The pool buffer size in bytes.

Returns:

The address of the allocated pool buffer. If the address is NULL, the buffer allocation failed.

os_buffer_put(p_buf)

Free and return the pool buffer to the specified memory pool.

os_pool.h

Example usage

#define BUF_SIZE1 0x40
#define BUF_NUM1  16
#define BUF_SIZE2 0x20
#define BUF_NUM2  8

int test(void)
{
    uint8_t handle;
    void *p_buf;

    // Create a memory pool capable of containing 16 buffers.
    if (os_pool_create(&handle, RAM_TYPE_DATA_ON, BUF_SIZE1, BUF_NUM1) == true)
    {
        // Memory pool created successfully.
    }
    else
    {
        // Memory pool failed to create.
        return -1;
    }

    // Extend the memory pool to have extra 8 buffers each in 0x20 bytes.
    os_pool_extend(handle, BUF_SIZE2, BUF_NUM2);

    // Allocate a pool buffer in 0x30 bytes. While, the memory pool will
    // give a buffer in 0x40 bytes.
    p_buf = os_buffer_get(handle, 0x30);

    // Free the pool buffer by the address.
    os_buffer_put(p_buf);

    return 0;
}

Parameters:

p_buf – [in] The address of the pool buffer allocated by os_buffer_get() API function.

Return values:

true – Pool was freed successfully.
false – Pool was failed to free.

Returns:

The status of the pool buffer freeing.

Functions

void os_pool_dump(uint8_t handle)

Dump the pool buffers of the specified memory pool.

os_pool.h

Example usage

#define BUF_SIZE1 0x40
#define BUF_NUM1  16
#define BUF_SIZE2 0x20
#define BUF_NUM2  8

int test(void)
{
    uint8_t handle;
    void *p_buf;

    // Create a memory pool capable of containing 16 buffers.
    if (os_pool_create(&handle, RAM_TYPE_DATA_ON, BUF_SIZE1, BUF_NUM1) == true)
    {
        // Memory pool created successfully.
    }
    else
    {
        // Memory pool failed to create.
        return -1;
    }

    // Extend the memory pool to have extra 8 buffers each in 0x20 bytes.
    os_pool_extend(handle, BUF_SIZE2, BUF_NUM2);

    // Allocate a pool buffer in 0x30 bytes. While, the memory pool will
    // give a buffer in 0x40 bytes.
    p_buf = os_buffer_get(handle, 0x30);

    // Dump the memory pool.
    os_pool_dump(handle);

    return 0;
}

Parameters:: handle – [in] The handle of the memory pool buffer to be dumped. If the memory pool handle is invalid, all created memory pools will be dumped.
Returns:: None.