tn_fmem.h File Reference

Detailed Description

Fixed memory blocks pool.

A fixed-sized memory blocks pool is used for managing fixed-sized memory blocks dynamically. A pool has a memory area where fixed-sized memory blocks are allocated and the wait queue for acquiring a memory block. If there are no free memory blocks, a task trying to acquire a memory block will be placed into the wait queue until a free memory block arrives (another task returns it to the memory pool).

The operations of getting the block from memory pool and releasing it back take O(1) time independently of number or size of the blocks.

For the useful pattern on how to use fixed memory pool together with queue, refer to the example: examples/queue. Be sure to examine the readme there.

Definition in file tn_fmem.h.

Go to the source code of this file.

Data Structures
struct	TN_FMem
	Fixed memory blocks pool. More...
struct	TN_FMemTaskWait
	FMem-specific fields related to waiting task, to be included in struct TN_Task. More...

Macros
#define	TN_FMEM_BUF_DEF(name, item_type, size)
	Convenience macro for the definition of buffer for memory pool. More...

Functions
enum TN_RCode	tn_fmem_create (struct TN_FMem *fmem, void *start_addr, unsigned int block_size, int blocks_cnt)
	Construct fixed memory blocks pool. More...
enum TN_RCode	tn_fmem_delete (struct TN_FMem *fmem)
	Destruct fixed memory blocks pool. More...
enum TN_RCode	tn_fmem_get (struct TN_FMem *fmem, void **p_data, TN_TickCnt timeout)
	Get memory block from the pool. More...
enum TN_RCode	tn_fmem_get_polling (struct TN_FMem *fmem, void **p_data)
	The same as tn_fmem_get() with zero timeout. More...
enum TN_RCode	tn_fmem_iget_polling (struct TN_FMem *fmem, void **p_data)
	The same as tn_fmem_get() with zero timeout, but for using in the ISR. More...
enum TN_RCode	tn_fmem_release (struct TN_FMem *fmem, void *p_data)
	Release memory block back to the pool. More...
enum TN_RCode	tn_fmem_irelease (struct TN_FMem *fmem, void *p_data)
	The same as tn_fmem_get(), but for using in the ISR. More...
int	tn_fmem_free_blocks_cnt_get (struct TN_FMem *fmem)
	Returns number of free blocks in the memory pool. More...
int	tn_fmem_used_blocks_cnt_get (struct TN_FMem *fmem)
	Returns number of used (non-free) blocks in the memory pool. More...

Macro Definition Documentation

TN_FMEM_BUF_DEF

#define TN_FMEM_BUF_DEF	(		name,
			item_type,
			size
	)

Value:

TN_UWord name[                                                 \
        (size)                                                    \
      * (TN_MAKE_ALIG_SIZE(sizeof(item_type)) / sizeof(TN_UWord)) \
      ]

Convenience macro for the definition of buffer for memory pool.

See tn_fmem_create() for usage example.

Parameters

name	C variable name of the buffer array (this name should be given to the tn_fmem_create() function as the start_addr argument)
item_type	Type of item in the memory pool, like struct MyMemoryItem.
size	Number of items in the memory pool.

Definition at line 146 of file tn_fmem.h.

Function Documentation

tn_fmem_create()

enum TN_RCode tn_fmem_create	(	struct TN_FMem *	fmem,
		void *	start_addr,
		unsigned int	block_size,
		int	blocks_cnt
	)

Construct fixed memory blocks pool.

id_fmp field should not contain TN_ID_FSMEMORYPOOL, otherwise, TN_RC_WPARAM is returned.

Note that start_addr and block_size should be a multiple of sizeof(TN_UWord).

For the definition of buffer, convenience macro TN_FMEM_BUF_DEF() was invented.

Typical definition looks as follows:

//-- number of blocks in the pool
#define MY_MEMORY_BUF_SIZE    8

//-- type for memory block
struct MyMemoryItem {
   // ... arbitrary fields ...
};

//-- define buffer for memory pool
TN_FMEM_BUF_DEF(my_fmem_buf, struct MyMemoryItem, MY_MEMORY_BUF_SIZE);

//-- define memory pool structure
struct TN_FMem my_fmem;

And then, construct your my_fmem as follows:

enum TN_RCode rc;
rc = tn_fmem_create( &my_fmem,
                     my_fmem_buf,
                     TN_MAKE_ALIG_SIZE(sizeof(struct MyMemoryItem)),
                     MY_MEMORY_BUF_SIZE );
if (rc != TN_RC_OK){
   //-- handle error
}

If given start_addr and/or block_size aren't aligned properly, TN_RC_WPARAM is returned.

(refer to Legend for details)

Parameters

fmem	pointer to already allocated struct TN_FMem.
start_addr	pointer to start of the array; should be aligned properly, see example above
block_size	size of memory block; should be a multiple of sizeof(TN_UWord), see example above
blocks_cnt	capacity (total number of blocks in the memory pool)

Returns

• TN_RC_OK if memory pool was successfully created;
• If TN_CHECK_PARAM is non-zero, additional return code is available: TN_RC_WPARAM.

See also

TN_MAKE_ALIG_SIZE

tn_fmem_delete()

enum TN_RCode tn_fmem_delete

(

struct TN_FMem *

fmem

)

Destruct fixed memory blocks pool.

All tasks that wait for free memory block become runnable with TN_RC_DELETED code returned.

(refer to Legend for details)

Parameters

fmem	pointer to memory pool to be deleted

Returns

• TN_RC_OK if memory pool is successfully deleted;
• TN_RC_WCONTEXT if called from wrong context;
• If TN_CHECK_PARAM is non-zero, additional return codes are available: TN_RC_WPARAM and TN_RC_INVALID_OBJ.

tn_fmem_get()

enum TN_RCode tn_fmem_get	(	struct TN_FMem *	fmem,
		void **	p_data,
		TN_TickCnt	timeout
	)

Get memory block from the pool.

Start address of the memory block is returned through the p_data argument. The content of memory block is undefined. If there is no free block in the pool, behavior depends on timeout value: refer to TN_TickCnt.

(refer to Legend for details)

Parameters

fmem	Pointer to memory pool
p_data	Address of the (void *) to which received block address will be saved
timeout	Refer to TN_TickCnt

Returns

• TN_RC_OK if block was successfully returned through p_data;
• TN_RC_WCONTEXT if called from wrong context;
• Other possible return codes depend on timeout value, refer to TN_TickCnt
• If TN_CHECK_PARAM is non-zero, additional return codes are available: TN_RC_WPARAM and TN_RC_INVALID_OBJ.

tn_fmem_get_polling()

enum TN_RCode tn_fmem_get_polling	(	struct TN_FMem *	fmem,
		void **	p_data
	)

The same as tn_fmem_get() with zero timeout.

(refer to Legend for details)

tn_fmem_iget_polling()

enum TN_RCode tn_fmem_iget_polling	(	struct TN_FMem *	fmem,
		void **	p_data
	)

The same as tn_fmem_get() with zero timeout, but for using in the ISR.

(refer to Legend for details)

tn_fmem_release()

enum TN_RCode tn_fmem_release	(	struct TN_FMem *	fmem,
		void *	p_data
	)

Release memory block back to the pool.

The kernel does not check the validity of the membership of given block in the memory pool. If all the memory blocks in the pool are free already, TN_RC_OVERFLOW is returned.

(refer to Legend for details)

Parameters

fmem	Pointer to memory pool.
p_data	Address of the memory block to release.

Returns

• TN_RC_OK on success
• TN_RC_WCONTEXT if called from wrong context;
• If TN_CHECK_PARAM is non-zero, additional return codes are available: TN_RC_WPARAM and TN_RC_INVALID_OBJ.

tn_fmem_irelease()

enum TN_RCode tn_fmem_irelease	(	struct TN_FMem *	fmem,
		void *	p_data
	)

The same as tn_fmem_get(), but for using in the ISR.

(refer to Legend for details)

tn_fmem_free_blocks_cnt_get()

int tn_fmem_free_blocks_cnt_get

(

struct TN_FMem *

fmem

)

Returns number of free blocks in the memory pool.

(refer to Legend for details)

Parameters

fmem	Pointer to memory pool.

Returns

Number of free blocks in the memory pool, or -1 if wrong params were given (the check is performed if only TN_CHECK_PARAM is non-zero)

tn_fmem_used_blocks_cnt_get()

int tn_fmem_used_blocks_cnt_get

(

struct TN_FMem *

fmem

)

Returns number of used (non-free) blocks in the memory pool.

(refer to Legend for details)

Parameters

fmem	Pointer to memory pool.

Returns

Number of used (non-free) blocks in the memory pool, or -1 if wrong params were given (the check is performed if only TN_CHECK_PARAM is non-zero)