Stack Handler

This group contains the Stack Handler implementation. More...

Files
file	stack.h
	This header file provides interfaces of the Stack Handler which are used by the implementation and the Application Configuration.
file	stackimpl.h
	This header file provides interfaces of the Stack Handler which are only used by the implementation.
file	stackallocator.c
	This source file contains a definition of _Stack_Allocator_avoids_workspace and _Stack_Allocator_allocate which allocates the thread stacks from the RTEMS Workspace.
file	stackallocatorforidle.c
	This source file contains the implementation of _Stack_Allocator_allocate_for_idle_static().
file	stackallocatorforidlewkspace.c
	This source file contains the implementation of _Stack_Allocator_allocate_for_idle_workspace().
file	stackallocatorfree.c
	This source file contains a definition of _Stack_Allocator_free which frees the thread stacks to the RTEMS Workspace.
file	stackallocatorinit.c
	This source file contains the implementation of _Stack_Allocator_do_initialize().
file	threadstackallocate.c
	This source file contains the implementation of _Stack_Allocate().
file	threadstackfree.c
	This source file contains the implementation of _Stack_Free().

Data Structures
struct	Stack_Control

Macros
#define	STACK_MINIMUM_SIZE   CPU_STACK_MINIMUM_SIZE

Typedefs
typedef void(*	Stack_Allocator_initialize) (size_t stack_space_size)
	The stack allocator initialization handler.
typedef void *(*	Stack_Allocator_allocate) (size_t stack_size)
	Stack allocator allocate handler.
typedef void(*	Stack_Allocator_free) (void *addr)
	Stack allocator free handler.
typedef void *(*	Stack_Allocator_allocate_for_idle) (uint32_t cpu, size_t *stack_size)
	Stack allocator allocate for idle handler.

Functions
void	_Stack_Allocator_do_initialize (void)
	Do the stack allocator initialization during system initialize.
void *	_Stack_Allocator_allocate_for_idle_workspace (uint32_t unused, size_t *storage_size)
	Allocates the IDLE thread storage area from the workspace.
void *	_Stack_Allocator_allocate_for_idle_static (uint32_t cpu_index, size_t *storage_size)
	Allocates the IDLE thread storage from the memory statically allocated by <rtems/confdefs.h>.
void *	_Stack_Allocate (size_t stack_size)
	Allocate the requested stack space.
void	_Stack_Free (void *stack_area)
	Free the stack area allocated by _Stack_Allocate().

Variables
uint32_t	rtems_minimum_stack_size
	The minimum stack size.
const uintptr_t	_Stack_Space_size
	The configured stack space size.
const bool	_Stack_Allocator_avoids_workspace
	Indicates if the stack allocator avoids the workspace.
const Stack_Allocator_initialize	_Stack_Allocator_initialize
	The stack allocator initialization handler.
const Stack_Allocator_allocate	_Stack_Allocator_allocate
	The stack allocator allocate handler.
const Stack_Allocator_free	_Stack_Allocator_free
	The stack allocator free handler.
const size_t	_Stack_Allocator_allocate_for_idle_storage_size
	The size in bytes of the idle thread storage area used by _Stack_Allocator_allocate_for_idle_static().
char	_Stack_Allocator_allocate_for_idle_storage_areas []
	The thread storage areas used by _Stack_Allocator_allocate_for_idle_static().
const Stack_Allocator_allocate_for_idle	_Stack_Allocator_allocate_for_idle
	The stack allocator allocate stack for idle thread handler.

Detailed Description

This group contains the Stack Handler implementation.

This handler encapsulates functionality which is used in the management of thread stacks. It provides mechanisms which can be used to initialize and utilize stacks.

Macro Definition Documentation

STACK_MINIMUM_SIZE

#define STACK_MINIMUM_SIZE   CPU_STACK_MINIMUM_SIZE

The following constant defines the minimum stack size which every thread must exceed.

Typedef Documentation

Stack_Allocator_allocate

typedef void *(* Stack_Allocator_allocate) (size_t stack_size)

Stack allocator allocate handler.

Parameters

stack_size

The size of the stack area to allocate in bytes.

Return values

NULL	Not enough memory.
other	Pointer to begin of stack area.

Stack_Allocator_allocate_for_idle

typedef void *(* Stack_Allocator_allocate_for_idle) (uint32_t cpu, size_t *stack_size)

Stack allocator allocate for idle handler.

The allocate for idle handler is optional even when the user thread stack allocator and deallocator are configured.

Parameters

cpu	is the index of the CPU for the IDLE thread using this stack.
stack_size[in,out]	is pointer to a size_t object. On function entry, the object contains the proposed size of the stack area to allocate in bytes. The proposed size does not take the actual thread-local storage size of the application into account. The stack allocator can modify the size to ensure that there is enough space available in the stack area for the thread-local storage.

Return values

NULL	There was not enough memory available to allocate a stack area.

Returns

Returns the pointer to begin of the allocated stack area.

Stack_Allocator_free

typedef void(* Stack_Allocator_free) (void *addr)

Stack allocator free handler.

Parameters

]	addr A pointer to previously allocated stack area or NULL.

Stack_Allocator_initialize

typedef void(* Stack_Allocator_initialize) (size_t stack_space_size)

The stack allocator initialization handler.

Parameters

stack_space_size

The size of the stack space in bytes.

Function Documentation

_Stack_Allocate()

void * _Stack_Allocate

(

size_t

stack_size

)

Allocate the requested stack space.

Parameters

stack_size

The stack space that is requested.

Return values

stack_area	The allocated stack area.
NULL	The allocation failed.

_Stack_Allocator_allocate_for_idle_static()

void * _Stack_Allocator_allocate_for_idle_static	(	uint32_t	cpu_index,
		size_t *	storage_size
	)

Allocates the IDLE thread storage from the memory statically allocated by <rtems/confdefs.h>.

Parameters

cpu_index	is the index of the CPU for the IDLE thread using this stack.
stack_size[out]	is pointer to a size_t object. On function return, the object value is set to the value of _Stack_Allocator_allocate_for_idle_storage_size.

Returns

Returns a pointer to the begin of the allocated task storage area.

_Stack_Allocator_allocate_for_idle_workspace()

void * _Stack_Allocator_allocate_for_idle_workspace	(	uint32_t	unused,
		size_t *	storage_size
	)

Allocates the IDLE thread storage area from the workspace.

If the thread storage area cannot be allocated, then the ::INTERNAL_ERROR_NO_MEMORY_FOR_IDLE_TASK_STACK fatal error will occur.

Parameters

unused	is an unused parameter.
stack_size[in]	is pointer to a size_t object. On function entry, the object contains the size of the task storage area to allocate in bytes.

Returns

Returns a pointer to the begin of the allocated task storage area.

_Stack_Allocator_do_initialize()

void _Stack_Allocator_do_initialize

(

void

)

Do the stack allocator initialization during system initialize.

This function is used to initialize application provided stack allocators.

_Stack_Free()

void _Stack_Free

(

void *

stack_area

)

Free the stack area allocated by _Stack_Allocate().

Do nothing if the stack area is NULL.

Parameters

stack_area

The stack area to free, or NULL.

Variable Documentation

_Stack_Allocator_allocate

const Stack_Allocator_allocate _Stack_Allocator_allocate

extern

The stack allocator allocate handler.

Application provided via <rtems/confdefs.h>.

_Stack_Allocator_allocate_for_idle

const Stack_Allocator_allocate_for_idle _Stack_Allocator_allocate_for_idle

extern

The stack allocator allocate stack for idle thread handler.

Application provided via <rtems/confdefs.h>.

_Stack_Allocator_allocate_for_idle_storage_areas

char _Stack_Allocator_allocate_for_idle_storage_areas[]

extern

The thread storage areas used by _Stack_Allocator_allocate_for_idle_static().

Application provided via <rtems/confdefs.h>.

_Stack_Allocator_allocate_for_idle_storage_size

const size_t _Stack_Allocator_allocate_for_idle_storage_size

extern

The size in bytes of the idle thread storage area used by _Stack_Allocator_allocate_for_idle_static().

Application provided via <rtems/confdefs.h>.

_Stack_Allocator_avoids_workspace

const bool _Stack_Allocator_avoids_workspace

extern

Indicates if the stack allocator avoids the workspace.

Application provided via <rtems/confdefs.h>.

_Stack_Allocator_free

const Stack_Allocator_free _Stack_Allocator_free

extern

The stack allocator free handler.

Application provided via <rtems/confdefs.h>.

_Stack_Allocator_initialize

const Stack_Allocator_initialize _Stack_Allocator_initialize

extern

The stack allocator initialization handler.

Application provided via <rtems/confdefs.h>.

_Stack_Space_size

const uintptr_t _Stack_Space_size

extern

The configured stack space size.

Application provided via <rtems/confdefs.h>.

rtems_minimum_stack_size

uint32_t rtems_minimum_stack_size

extern

The minimum stack size.

Application provided via <rtems/confdefs.h>.