Protected Heap Handler

Functions
boolean	_Protected_heap_Extend (Heap_Control *the_heap, void *starting_address, size_t size)
void *	_Protected_heap_Allocate (Heap_Control *the_heap, size_t size)
void *	_Protected_heap_Allocate_aligned (Heap_Control *the_heap, size_t size, uint32_t alignment)
boolean	_Protected_heap_Get_block_size (Heap_Control *the_heap, void *starting_address, size_t *size)
boolean	_Protected_heap_Resize_block (Heap_Control *the_heap, void *starting_address, size_t size)
boolean	_Protected_heap_Free (Heap_Control *the_heap, void *start_address)
boolean	_Protected_heap_Walk (Heap_Control *the_heap, int source, boolean do_dump)
void	_Protected_heap_Get_information (Heap_Control *the_heap, Heap_Information_block *the_info)
void	_Protected_heap_Get_free_information (Heap_Control *the_heap, Heap_Information *info)

---

Detailed Description

This handler encapsulates functionality which provides the foundation Protected Heap services.

It is a simple wrapper for the help with the addition of the allocation mutex being used for protection.

---

Function Documentation

void* _Protected_heap_Allocate	(	Heap_Control *	the_heap,
		size_t	size
	)

This function attempts to allocate a block of size bytes from the_heap. If insufficient memory is free in the_heap to allocate a block of the requested size, then NULL is returned.

Parameters:

[in]	the_heap	is the heap to operate upon
[in]	size	is the amount of memory to allocate in bytes

Returns:

NULL if unsuccessful and a pointer to the block if successful

void* _Protected_heap_Allocate_aligned	(	Heap_Control *	the_heap,
		size_t	size,
		uint32_t	alignment
	)

This function attempts to allocate a memory block of size bytes from the_heap so that the start of the user memory is aligned on the alignment boundary. If alignment is 0, it is set to CPU_ALIGNMENT. Any other value of alignment is taken "as is", i.e., even odd alignments are possible. Returns pointer to the start of the memory block if success, NULL if failure.

Parameters:

[in]	the_heap	is the heap to operate upon
[in]	size	is the amount of memory to allocate in bytes
[in]	alignment	the required alignment

Returns:

NULL if unsuccessful and a pointer to the block if successful

boolean _Protected_heap_Extend	(	Heap_Control *	the_heap,
		void *	starting_address,
		size_t	size
	)

This routine grows the_heap memory area using the size bytes which begin at starting_address.

Parameters:

[in]	the_heap	is the heap to operate upon
[in]	starting_address	is the starting address of the memory to add to the heap
[in]	size	is the size in bytes of the memory area to add

Returns:

a status indicating success or the reason for failure

boolean _Protected_heap_Free	(	Heap_Control *	the_heap,
		void *	start_address
	)

This routine returns the block of memory which begins at starting_address to the_heap. Any coalescing which is possible with the freeing of this routine is performed.

Parameters:

[in]	the_heap	is the heap to operate upon
[in]	start_address	is the starting address of the user block to free

Returns:

TRUE if successfully freed, FALSE otherwise

boolean _Protected_heap_Get_block_size	(	Heap_Control *	the_heap,
		void *	starting_address,
		size_t *	size
	)

This function sets *size to the size of the block of user memory which begins at starting_address. The size returned in *size could be greater than the size requested for allocation. Returns TRUE if the starting_address is in the heap, and FALSE otherwise.

Parameters:

[in]	the_heap	is the heap to operate upon
[in]	starting_address	is the starting address of the user block to obtain the size of
[in]	size	points to a user area to return the size in

Returns:

TRUE if successfully able to determine the size, FALSE otherwise

*size filled in with the size of the user area for this block

void _Protected_heap_Get_free_information	(	Heap_Control *	the_heap,
		Heap_Information *	info
	)

This heap routine returns information about the free blocks in the specified heap.

Parameters:

[in]	the_heap	pointer to heap header.
[in]	info	pointer to the free block information.

Returns:

free block information filled in.

void _Protected_heap_Get_information	(	Heap_Control *	the_heap,
		Heap_Information_block *	the_info
	)

This routine walks the heap and tots up the free and allocated sizes.

Parameters:

[in]	the_heap	pointer to heap header
[in]	the_info	pointer to a status information area

boolean _Protected_heap_Resize_block	(	Heap_Control *	the_heap,
		void *	starting_address,
		size_t	size
	)

This function tries to resize in place the block that is pointed to by the starting_address to the new size.

Parameters:

[in]	the_heap	is the heap to operate upon
[in]	starting_address	is the starting address of the user block to be resized
[in]	size	is the new size

Returns:

TRUE if successfully able to resize the block. FALSE if the block can't be resized in place.

boolean _Protected_heap_Walk	(	Heap_Control *	the_heap,
		int	source,
		boolean	do_dump
	)

This routine walks the heap to verify its integrity.

Parameters:

[in]	the_heap	is the heap to operate upon
[in]	source	is a user specified integer which may be used to indicate where in the application this was invoked from
[in]	do_dump	is set to TRUE if errors should be printed

Returns:

TRUE if the test passed fine, FALSE otherwise.