libs/os/include/os/os_mempool.h

/**
 * Copyright (c) 2015 Runtime Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef _OS_MEMPOOL_H_
#define _OS_MEMPOOL_H_

#include "os/os.h"
#include "os/queue.h"

/* 
 * A memory block structure. This simply contains a pointer to the free list 
 * chain and is only used when the block is on the free list. When the block 
 * has been removed from the free list the entire memory block is usable by the 
 * caller. 
 */
struct os_memblock {
    SLIST_ENTRY(os_memblock) mb_next;
};

/* XXX: Change this structure so that we keep the first address in the pool? */
/* XXX: add memory debug structure and associated code */
/* XXX: Change how I coded the SLIST_HEAD here. It should be named:
   SLIST_HEAD(,os_memblock) mp_head; */

/* Memory pool */
struct os_mempool {
    int mp_block_size;          /* Size of the memory blocks, in bytes. */
    int mp_num_blocks;          /* The number of memory blocks. */
    int mp_num_free;            /* The number of free blocks left */
    SLIST_HEAD(,os_memblock);   /* Pointer to list of free blocks */
    char *name;                 /* Name for memory block */
};

/* 
 * To calculate size of the memory buffer needed for the pool. NOTE: This size 
 * is NOT in bytes! The size is the number of os_membuf_t elements required for 
 * the memory pool.
 */
#if (OS_CFG_ALIGNMENT == OS_CFG_ALIGN_4)
#define OS_MEMPOOL_SIZE(n,blksize)      ((((blksize) + 3) / 4) * (n))
typedef uint32_t os_membuf_t;
#else
#define OS_MEMPOOL_SIZE(n,blksize)      ((((blksize) + 7) / 8) * (n)) 
typedef uint64_t os_membuf_t;
#endif

/** Calculates the number of bytes required to initialize a memory pool. */
#define OS_MEMPOOL_BYTES(n,blksize)     \
    (sizeof (os_membuf_t) * OS_MEMPOOL_SIZE((n), (blksize)))

/* Initialize a memory pool */
os_error_t os_mempool_init(struct os_mempool *mp, int blocks, int block_size, 
                           void *membuf, char *name);

/* Get a memory block from the pool */
void *os_memblock_get(struct os_mempool *mp);

/* Put the memory block back into the pool */
os_error_t os_memblock_put(struct os_mempool *mp, void *block_addr);

#endif  /* _OS_MEMPOOL_H_ */