//================================================================================================
/*! \file hifi_pool.c
\brief Implements simple, robust, fixed block size pools.

The pools implemented are defined in the in the hifi_pool.h file by specifying (by means of a define)
the pool ID, the block dimension and the number of blocks in the pool.

The pools can be accessed by means of the following interface functions:

- void  hifi_pool_init (void) 					inits the pools
- int  hifi_pool_get_block (int pool_id) 		gets a block 
- void  hifi_pool_free_block (int pool_id, int block_nr) 		frees a block
- int *  hifi_pool_get_pointer (int pool_id, int block_nr) 		gets a pointer to the block

For each pool three vectors exist:
- The data vector, i.e. the memory for the pool blocks 
- The block usage vector: as many entries as blocks in the pool. 1 = block used, 0 = block free.
- The block pointer vector: as many entries as blocks in the pool, each pointing to the corresponding block starting point.

The blocks are numbered from 0 to max-1 internally and from 1 to max externally. One of the blocks is 
used as the trash block, i.e. as a block to overwrite if a block is requested
but no blocks are free. Externally the trash block is numbered as block zero.
*/

//================================================================================================
/*! \fn  void  hifi_pool_init (void) 
This function should be called before using the other interfaces. It sets the values of several pointers and marks
all the block as unused.
*/

//================================================================================================
/*! \fn  int  hifi_pool_get_block (int pool_id) 
This function checks if a block is free in the specified pool, if yes marks the block as used and returns the
(external) block nr (internally blocks range from 0 to max-1, externally from 1 to max). 
If no block is free returns zero (i.e. the trash block) and issues an error.
*/

//================================================================================================
/*! \fn  void  hifi_pool_free_block (int pool_id, int block_nr) 
Marks block_nr of pool pool_id as unused (by setting block_used = 0).
*/

//================================================================================================
/*! \fn  int *  hifi_pool_get_pointer (int pool_id, int block_nr) 
This function returns a pointer to the block data. If block_nr is zero or if the pool_id is not recognized an error 
is issued and a pointer to the trash block is returned.
*/

//================================================================================================
/*! \fn  int *  get_pool_pointer (int **pool, int block_nr, int max_block_nr) 
Internal use. Finds the block pointer.
*/

//================================================================================================
/*! \fn  int  get_pool_block (int *pool_used, int block_nr) 
Internal use. Search a free block.
*/

//================================================================================================
/*! \fn  void  pool_free_block (int *pool_used, int block_nr, int max_block_nr) 
Internal use. Frees a block.
*/