The scheduling concepts relate to the allocation of processing time for tasks. More...

Macros
#define	rtems_scheduler_get_processor(void) _SMP_Get_current_processor()
	Returns the index of the current processor.

#define	rtems_scheduler_get_processor_maximum(void) _SMP_Get_processor_maximum()
	Returns the processor maximum supported by the system.

Functions
rtems_status_code	rtems_scheduler_ident (rtems_name name, rtems_id *id)
	Identifies a scheduler by the object name.

rtems_status_code	rtems_scheduler_ident_by_processor (uint32_t cpu_index, rtems_id *id)
	Identifies a scheduler by the processor index.

rtems_status_code	rtems_scheduler_ident_by_processor_set (size_t cpusetsize, const cpu_set_t cpuset, rtems_id id)
	Identifies a scheduler by the processor set.

rtems_status_code	rtems_scheduler_get_maximum_priority (rtems_id scheduler_id, rtems_task_priority *priority)
	Gets the maximum task priority of the scheduler.

rtems_status_code	rtems_scheduler_map_priority_to_posix (rtems_id scheduler_id, rtems_task_priority priority, int *posix_priority)
	Maps a Classic API task priority to the corresponding POSIX thread priority.

rtems_status_code	rtems_scheduler_map_priority_from_posix (rtems_id scheduler_id, int posix_priority, rtems_task_priority *priority)
	Maps a POSIX thread priority to the corresponding Classic API task priority.

rtems_status_code	rtems_scheduler_get_processor_set (rtems_id scheduler_id, size_t cpusetsize, cpu_set_t *cpuset)
	Gets the set of processors owned by the scheduler.

rtems_status_code	rtems_scheduler_add_processor (rtems_id scheduler_id, uint32_t cpu_index)
	Adds the processor to the set of processors owned by the scheduler.

rtems_status_code	rtems_scheduler_remove_processor (rtems_id scheduler_id, uint32_t cpu_index)
	Removes the processor from the set of processors owned by the scheduler.

Detailed Description

The scheduling concepts relate to the allocation of processing time for tasks.

The concept of scheduling in real-time systems dictates the ability to provide an immediate response to specific external events, particularly the necessity of scheduling tasks to run within a specified time limit after the occurrence of an event. For example, software embedded in life-support systems used to monitor hospital patients must take instant action if a change in the patient’s status is detected.

The component of RTEMS responsible for providing this capability is appropriately called the scheduler. The scheduler’s sole purpose is to allocate the all important resource of processor time to the various tasks competing for attention.

Macro Definition Documentation

◆ rtems_scheduler_get_processor

uint32_t rtems_scheduler_get_processor ( void ) _SMP_Get_current_processor()

Returns the index of the current processor.

Where the system was built with SMP support disabled, this directive evaluates to a compile time constant of zero.

Where the system was built with SMP support enabled, this directive returns the index of the current processor. The set of processor indices is the range of integers starting with zero up to rtems_scheduler_get_processor_maximum() minus one.

Returns: Returns the index of the current processor.

Notes: Outside of sections with disabled thread dispatching the current processor index may change after every instruction since the thread may migrate from one processor to another. Sections with disabled interrupts are sections with thread dispatching disabled.

Constraints

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

◆ rtems_scheduler_get_processor_maximum

uint32_t rtems_scheduler_get_processor_maximum ( void ) _SMP_Get_processor_maximum()

Returns the processor maximum supported by the system.

Where the system was built with SMP support disabled, this directive evaluates to a compile time constant of one.

Where the system was built with SMP support enabled, this directive returns the minimum of the processors (physically or virtually) available at the target and the configured processor maximum (see CONFIGURE_MAXIMUM_PROCESSORS). Not all processors in the range from processor index zero to the last processor index (which is the processor maximum minus one) may be configured to be used by a scheduler or may be online (online processors have a scheduler assigned).

Returns: Returns the processor maximum supported by the system.

Constraints

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

Function Documentation

◆ rtems_scheduler_add_processor()

rtems_status_code rtems_scheduler_add_processor	(	rtems_id	scheduler_id,
		uint32_t	cpu_index
	)

Adds the processor to the set of processors owned by the scheduler.

Parameters

scheduler_id	is the scheduler identifier.
cpu_index	is the index of the processor to add.

This directive adds the processor specified by the cpu_index to the scheduler specified by scheduler_id.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ID	There was no scheduler associated with the identifier specified by `scheduler_id`.
RTEMS_NOT_CONFIGURED	The processor was not configured to be used by the application.
RTEMS_INCORRECT_STATE	The processor was configured to be used by the application, however, it was not online.
RTEMS_RESOURCE_IN_USE	The processor was already assigned to a scheduler.

Constraints

The following constraints apply to this directive:

The directive may be called from within device driver initialization context.
The directive may be called from within task context.
The directive may obtain and release the object allocator mutex. This may cause the calling task to be preempted.

◆ rtems_scheduler_get_maximum_priority()

rtems_status_code rtems_scheduler_get_maximum_priority	(	rtems_id	scheduler_id,
		rtems_task_priority *	priority
	)

Gets the maximum task priority of the scheduler.

Parameters

	scheduler_id	is the scheduler identifier.
[out]	priority	is the pointer to an rtems_task_priority object. When the directive the maximum priority of the scheduler will be stored in this object.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ID	There was no scheduler associated with the identifier specified by `scheduler_id`.
RTEMS_INVALID_ADDRESS	The `priority` parameter was NULL.

Constraints

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

◆ rtems_scheduler_get_processor_set()

rtems_status_code rtems_scheduler_get_processor_set	(	rtems_id	scheduler_id,
		size_t	cpusetsize,
		cpu_set_t *	cpuset
	)

Gets the set of processors owned by the scheduler.

Parameters

	scheduler_id	is the scheduler identifier.
	cpusetsize	is the size of the processor set referenced by `cpuset` in bytes.
[out]	cpuset	is the pointer to a cpu_set_t object. When the directive call is successful, the processor set of the scheduler will be stored in this object. A set bit in the processor set means that the corresponding processor is owned by the scheduler, otherwise the bit is cleared.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ADDRESS	The `cpuset` parameter was NULL.
RTEMS_INVALID_ID	There was no scheduler associated with the identifier specified by `scheduler_id`.
RTEMS_INVALID_SIZE	The provided processor set was too small for the set of processors owned by the scheduler.

Constraints

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

◆ rtems_scheduler_ident()

rtems_status_code rtems_scheduler_ident	(	rtems_name	name,
		rtems_id *	id
	)

Identifies a scheduler by the object name.

Parameters

	name	is the scheduler name to look up.
[out]	id	is the pointer to an rtems_id object. When the directive call is successful, the identifier of the scheduler will be stored in this object.

This directive obtains a scheduler identifier associated with the scheduler name specified in name.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_NAME	There was no scheduler associated with the name.
RTEMS_INVALID_ADDRESS	The `id` parameter was NULL.

Notes

The scheduler name is determined by the scheduler configuration.

The scheduler identifier is used with other scheduler related directives to access the scheduler.

Constraints

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

◆ rtems_scheduler_ident_by_processor()

rtems_status_code rtems_scheduler_ident_by_processor	(	uint32_t	cpu_index,
		rtems_id *	id
	)

Identifies a scheduler by the processor index.

Parameters

	cpu_index	is the processor index to identify the scheduler.
[out]	id	is the pointer to an rtems_id object. When the directive call is successful, the identifier of the scheduler will be stored in this object.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ADDRESS	The `id` parameter was NULL.
RTEMS_INVALID_NAME	The processor index was invalid.
RTEMS_INCORRECT_STATE	The processor index was valid, however, the corresponding processor was not owned by a scheduler.

Constraints

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

◆ rtems_scheduler_ident_by_processor_set()

rtems_status_code rtems_scheduler_ident_by_processor_set	(	size_t	cpusetsize,
		const cpu_set_t *	cpuset,
		rtems_id *	id
	)

Identifies a scheduler by the processor set.

Parameters

	cpusetsize	is the size of the processor set referenced by `cpuset` in bytes. The size shall be positive.
	cpuset	is the pointer to a cpu_set_t. The referenced processor set will be used to identify the scheduler.
[out]	id	is the pointer to an rtems_id object. When the directive call is successful, the identifier of the scheduler will be stored in this object.

The scheduler is selected according to the highest numbered online processor in the specified processor set.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ADDRESS	The `id` parameter was NULL.
RTEMS_INVALID_ADDRESS	The `cpuset` parameter was NULL.
RTEMS_INVALID_SIZE	The processor set size was invalid.
RTEMS_INVALID_NAME	The processor set contained no online processor.
RTEMS_INCORRECT_STATE	The processor set was valid, however, the highest numbered online processor in the processor set was not owned by a scheduler.

Constraints

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

◆ rtems_scheduler_map_priority_from_posix()

rtems_status_code rtems_scheduler_map_priority_from_posix	(	rtems_id	scheduler_id,
		int	posix_priority,
		rtems_task_priority *	priority
	)

Maps a POSIX thread priority to the corresponding Classic API task priority.

Parameters

	scheduler_id	is the scheduler identifier.
	posix_priority	is the POSIX thread priority to map.
[out]	priority	is the pointer to an rtems_task_priority object. When the directive call is successful, the Classic API task priority value corresponding to the specified POSIX thread priority value will be stored in this object.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ADDRESS	The `priority` parameter was NULL.
RTEMS_INVALID_ID	There was no scheduler associated with the identifier specified by `scheduler_id`.
RTEMS_INVALID_PRIORITY	The POSIX thread priority was invalid.

Constraints

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

◆ rtems_scheduler_map_priority_to_posix()

rtems_status_code rtems_scheduler_map_priority_to_posix	(	rtems_id	scheduler_id,
		rtems_task_priority	priority,
		int *	posix_priority
	)

Maps a Classic API task priority to the corresponding POSIX thread priority.

Parameters

	scheduler_id	is the scheduler identifier.
	priority	is the Classic API task priority to map.
[out]	posix_priority	is the pointer to an `int` object. When the directive call is successful, the POSIX thread priority value corresponding to the specified Classic API task priority value will be stored in this object.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ADDRESS	The `posix_priority` parameter was NULL.
RTEMS_INVALID_ID	There was no scheduler associated with the identifier specified by `scheduler_id`.
RTEMS_INVALID_PRIORITY	The Classic API task priority was invalid.

Constraints

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

◆ rtems_scheduler_remove_processor()

rtems_status_code rtems_scheduler_remove_processor	(	rtems_id	scheduler_id,
		uint32_t	cpu_index
	)

Removes the processor from the set of processors owned by the scheduler.

Parameters

scheduler_id	is the scheduler identifier.
cpu_index	is the index of the processor to remove.

This directive removes the processor specified by the cpu_index from the scheduler specified by scheduler_id.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ID	There was no scheduler associated with the identifier specified by `scheduler_id`.
RTEMS_INVALID_NUMBER	The processor was not owned by the scheduler.
RTEMS_RESOURCE_IN_USE	The processor was required by at least one non-idle task that used the scheduler as its home scheduler.
RTEMS_RESOURCE_IN_USE	The processor was the last processor owned by the scheduler and there was at least one task that used the scheduler as a helping scheduler.

Notes: Removing a processor from a scheduler is a complex operation that involves all tasks of the system.

Constraints

The following constraints apply to this directive:

The directive may be called from within device driver initialization context.
The directive may be called from within task context.
The directive may obtain and release the object allocator mutex. This may cause the calling task to be preempted.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ rtems_scheduler_get_processor

◆ rtems_scheduler_get_processor_maximum

Function Documentation

◆ rtems_scheduler_add_processor()

◆ rtems_scheduler_get_maximum_priority()

◆ rtems_scheduler_get_processor_set()

◆ rtems_scheduler_ident()

◆ rtems_scheduler_ident_by_processor()

◆ rtems_scheduler_ident_by_processor_set()

◆ rtems_scheduler_map_priority_from_posix()

◆ rtems_scheduler_map_priority_to_posix()

◆ rtems_scheduler_remove_processor()