CPU delayed preemption API

Functions to manage delayed preemptions (DP). More...


Functions
int	l4cpu_reserve_delayed_preempt (l4_threadid_t thread, int id, int prio, int *delay)
	Add delayed preemption reservation for a thread, internal function.
int	l4cpu_dp_reserve_task (int *duration)
	Delayed Preemption: Reserve a duration for the whole task.
int	l4cpu_dp_remove (void)
	Delayed preemption: Cancel a reservation.
int	l4cpu_dp_begin (void)
	Delayed preemption: Start a delayed preemption After making a dp reservation with l4cpu_dp_reserve_task(), a thread can start an uninterruptible execution. Calls to this function may be nested, and the last call to l4cpu_dp_end() actually leaves the uninterruptible section.
int	l4cpu_dp_end (void)
	Delayed preemption: End a delayed preemption When calling this function, and un-nesting all previous calls to l4cpu_dp_begin(), the thread may be preempted by the kernel again.

Detailed Description

Functions to manage delayed preemptions (DP).

The function-prototypes can be found in <l4/cpu_reserve/sched.h>

The API implementation can be found in the libcpu_reserve.a library.

Function Documentation

int l4cpu_dp_begin ( void )

Delayed preemption: Start a delayed preemption

After making a dp reservation with l4cpu_dp_reserve_task(), a thread can start an uninterruptible execution. Calls to this function may be nested, and the last call to l4cpu_dp_end() actually leaves the uninterruptible section.

Nesting calls from different threads will be detected and interpreted as an error. Kernel debugger is entered.

Note:: Due to the currently missing support in the kernel, this call is implemented as a cli(), requiring cooperation from the calling thread.

Return values:

	0	OK
	!0	Error, e.g. nesting calls from different threads.

Precondition:: l4_tsc_init() must have been called successfully.

Definition at line 57 of file delayed_preempt.c.

References CONFIG_LOG_DP, l4cpu_dp_start_callback(), pc, preempt_counter, preempt_start, and thread.

int l4cpu_dp_end ( void )

Delayed preemption: End a delayed preemption

When calling this function, and un-nesting all previous calls to l4cpu_dp_begin(), the thread may be preempted by the kernel again.

Note:: In its current implementation, time measurement is used to verify the actual blocking time. A warning is printed if the blocking was too long.

Return values:

	0	OK. probably someone still in the preemption
	>0	OK, DP ended. Time left (in usecs).
	-L4_ETIME	blocking was too long
	-L4_EINVAL	DP was not running

Precondition:: l4_tsc_init() must have been called successfully.

Definition at line 89 of file delayed_preempt.c.

References CONFIG_LOG_DP, CONFIG_LOG_TO_KERN, dp_duration, l4cpu_dp_stop_callback(), pc, preempt_counter, preempt_start, and thread.

int l4cpu_dp_remove ( void )

Delayed preemption: Cancel a reservation.

Return values:

	0	OK
	!0	Error.

Note:: Currently unimplemented.

int l4cpu_dp_reserve_task ( int * duration )

Delayed Preemption: Reserve a duration for the whole task.

Parameters:

duration

time (microseconds)

Return values:

	duration	contains the actually reserved time.
	0	OK
	!0	Error.

This function reserves a non-preemptible duration at the kernel, for all existing and future threads of the calling task.

Note:: The task-abstraction is easy to use from client applications, as nothing has to be done on thread creation. It is easy to implement with the current scheme too. It is also correct in the sense of reservation and scheduling analysis, as long as the priority of the thread reserving the delayed preemption is _low_ enough. Keep in mind that only one blocking may happen at a time, and therefore the maximum blocking time of higher-prioritized threads is determined by the maximum the DP times of all lower-prioritized threads.
With future kernel releases, that might include real kernel support for DP, the task abstraction might be hard to implement, and support for DP must be programmed more explicitely. Think of interrupt threads that are created by DDE internally.

Definition at line 39 of file delayed_preempt.c.

References dp_duration, and l4cpu_reserve_delayed_preempt().

int l4cpu_reserve_delayed_preempt	(	l4_threadid_t	thread,
		int	id,
		int	prio,
		int *	delay
	)

Add delayed preemption reservation for a thread, internal function.

Parameters:

	thread	thread to add delayed preemption (DP) to
	id	id of the timeslice to add DP to
	prio	sensitive priority of DP, once it is activated. (Ignored and assumed to be 255, see note.)
	delay	max. duration of DP. Will be rounded up according to kernel capabilities and returned.

Return values:

	0	OK
	!0	Error

This function adds a delayed preemption to the specified timeslice, which must exist already. The non real-time timeslice with id=0 always exists, the others are created by calling l4cpu_reserve_add(). The actual duration of the delayed preemption is returned in *delay. The name returned by the diagnostic function l4cpu_reserve_scheds_get() is set to the name of the timeslice, suffixed by ".dp".

The delayed preemption reservation will be removed when the reservations for the thread are removed.

Note:: As of today (Oct 2004), the kernel has no support for DP, thus a user-level emulation is needed. CLI/STI comes into mind, which of course ignores the sensitive priority and prevents preemption entirely as long as DP is activated.

Definition at line 73 of file clientlib.c.

References server_id, and server_init().

Referenced by l4cpu_dp_reserve_task().