CPU reservation API

Functions to manage reservations. More...

Functions

int l4cpu_reserve_add (l4_threadid_t thread, const char *name, int prio, int period, int *wcet, int deadline, int *id)
 Make a reservation.
int l4cpu_reserve_change (l4_threadid_t thread, int id, int new_prio, int *new_wcet, int new_deadline)
 Change the reservation of a thread.
int l4cpu_reserve_delete_thread (l4_threadid_t thread)
 Remove the reservations of a thread.
int l4cpu_reserve_delete_task (l4_threadid_t task)
 Remove the reservations of a task.
int l4cpu_reserve_begin_strictly_periodic (l4_threadid_t thread, l4_kernel_clock_t clock)
 Start strictly periodic execution.
int l4cpu_reserve_begin_strictly_periodic_self (l4_threadid_t me)
 Start strictly periodic execution of own thread ASAP.
int l4cpu_reserve_begin_minimal_periodic (l4_threadid_t thread, l4_kernel_clock_t clock)
 Start periodic execution with minimal interrelease times.
int l4cpu_reserve_begin_minimal_periodic_self (l4_threadid_t thread)
 Start periodic execution with minimal interrelease times, own thread.
int l4cpu_reserve_end_periodic (l4_threadid_t thread)
 Stop periodic execution.
int l4cpu_reserve_watch (l4_threadid_t thread, unsigned **addr)
 Watch exception IPCs for the given thread.
int l4cpu_reserve_scheds_count (void)
 Return the number of reservations made.

Use this function for debugging/monitoring purposes.

int l4cpu_reserve_scheds_get (int idx, char **name, l4_threadid_t *thread, l4_threadid_t *creator, int *id, int *prio, int *period, int *wcet, int *deadline)
 Return a given reservation.

Detailed Description

Functions to manage reservations.

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_reserve_add ( l4_threadid_t  thread,
const char *  name,
int  prio,
int  period,
int *  wcet,
int  deadline,
int *  id 
)

Make a reservation.

Parameters:
thread thread to make a reservation for
name a name for the reservation
prio priority of the reservation
period period of the thread
wcet - in: WCET of the thread per period
  • out: reserved amount of CPU in case of success
deadline deadline within the period. Specify 0 for an optional reservation.
id will be filled with the id of the timeslice.
Return values:
0 OK
!0 Error
This function makes a reservation for the given thread and adds the needed timeslices at the kernel. Open success, it is ensured that the thread will receive the requested amount of CPU within the given deadline. However, a general assumption is that no other, higher prioritized threads exist in the system that are not registered at the CPU reservation server. Use the MCP mechanism of the kernel to ensure this.

To add multiple timeslices for a thread, call this function multiple times. This function sets the period of the thread when adding the first timeslice to thread. So there is no additional set_period() call as with the raw kernel interface.

Definition at line 50 of file clientlib.c.

References server_id, and server_init().

int l4cpu_reserve_begin_minimal_periodic ( l4_threadid_t  thread,
l4_kernel_clock_t  clock 
)

Start periodic execution with minimal interrelease times.

Parameters:
dest thread that starts periodic execution
clock absolute time to start.
Return values:
0 OK
!0 Error
Call this function to start the periodic execution after setting up the reservations using l4cpu_reserve_add().

For details, see l4_rt_begin_minimal_periodic() in the l4sys package.

Definition at line 176 of file clientlib.c.

References server_id, and server_init().

Referenced by l4cpu_reserve_wait_periodic_ready().

int l4cpu_reserve_begin_minimal_periodic_self ( l4_threadid_t  thread  ) 

Start periodic execution with minimal interrelease times, own thread.

Parameters:
me (cached) own ID. L4_INVALID_ID if you don't know.
clock absolute time to start. 0: ASAP.
Return values:
0 OK
!0 Error
Call this function to start the periodic execution for the calling thread after setting up the reservations using l4cpu_reserve_add(). The initial next_period() call is automatically executed.

For details, see l4_rt_begin_minimal_periodic() in the l4sys package. For notes, see l4cpu_reserve_begin_strictly_periodic_self().

Definition at line 189 of file clientlib.c.

References server_id, and server_init().

int l4cpu_reserve_begin_strictly_periodic ( l4_threadid_t  thread,
l4_kernel_clock_t  clock 
)

Start strictly periodic execution.

Parameters:
dest thread that starts periodic execution
clock absolute time to start.
Return values:
0 OK
!0 Error
Call this function to start the periodic execution of another thread after setting up the reservations using l4cpu_reserve_add().

For details, see l4_rt_begin_strictly_periodic() in the l4sys package.

Note:
Starting RT-mode of the own thread with a timeout is unsafe. As the thread has no reservation, a deadline for activating this call at the kernel can not be guaranteed. Starting the own thread requires the NP bit to be set when calling the scheduler to activate RT mode to ensure the thread is ready to receive its first NP-IPC at the right time. If, however, the RT-mode activation is triggered after the timeout, the operation fails. But, the thread is waiting for the NP-IPC and won't receive the answer indicating the error.

Definition at line 135 of file clientlib.c.

References server_id, and server_init().

Referenced by l4cpu_reserve_wait_periodic_ready().

int l4cpu_reserve_begin_strictly_periodic_self ( l4_threadid_t  me  ) 

Start strictly periodic execution of own thread ASAP.

Parameters:
me (cached) own ID. L4_INVALID_ID if you don't know.
Return values:
0 OK
!0 Error
Call this function to start the periodic execution for the calling thread after setting up the reservations using l4cpu_reserve_add(). The initial next_period() call is automatically executed, and periodic mode is activated as sonn as possible.

For details, see l4_rt_begin_strictly_periodic() in the l4sys package.

Definition at line 148 of file clientlib.c.

References server_id, and server_init().

int l4cpu_reserve_change ( l4_threadid_t  thread,
int  id,
int  new_prio,
int *  new_wcet,
int  new_deadline 
)

Change the reservation of a thread.

Parameters:
thread thread to change the reservation for
id id of the timeslice to change
new_prio new priority, -1 does not change
new_wcet - in: new wcet, -1 does not change
  • out: reserved amount of CPU if successfully modified
deadline new deadline, -1 does not change.
Return values:
0 OK
!0 Error
This function changes a reservation for the given thread and timeslice. Checks are performed to ensure that all existing reservations can be met.

Definition at line 90 of file clientlib.c.

References server_id, and server_init().

int l4cpu_reserve_delete_task ( l4_threadid_t  task  ) 

Remove the reservations of a task.

Parameters:
task task to remove all reservations from
Return values:
0 OK
!0 Error
This function removes all reservations for all threads of the given task.

Definition at line 124 of file clientlib.c.

References server_id, and server_init().

int l4cpu_reserve_delete_thread ( l4_threadid_t  thread  ) 

Remove the reservations of a thread.

Parameters:
thread thread to remove all reservations from
Return values:
0 OK
!0 Error
This function removes all reservations for the given thread.

Definition at line 109 of file clientlib.c.

References l4cpu_reserve_set_preempter(), server_id, and server_init().

int l4cpu_reserve_end_periodic ( l4_threadid_t  thread  ) 

Stop periodic execution.

Parameters:
thread thread that stops periodic execution
Return values:
0 OK
!0 Error
This function aborts the periodic execution of the given thread.

For details, see l4_rt_end_periodic() in the l4sys package.

Definition at line 217 of file clientlib.c.

References server_id, and server_init().

int l4cpu_reserve_scheds_count ( void   ) 

Return the number of reservations made.

Use this function for debugging/monitoring purposes.

Definition at line 255 of file clientlib.c.

References server_id, and server_init().

Referenced by l4cpu_reserve_dump().

int l4cpu_reserve_scheds_get ( int  idx,
char **  name,
l4_threadid_t *  thread,
l4_threadid_t *  creator,
int *  id,
int *  prio,
int *  period,
int *  wcet,
int *  deadline 
)

Return a given reservation.

Parameters:
idx reservation index, 0<=idx<=l4cpu_reserve_scheds_count()
name will set to the name, free() it after use
thread thread-id of reservation
creator thread-id of the creator of the reservation
id id of the reservation
prio priority of the reservation
period period of the reservation
wcet WCET of the reservation
deadline deadline of the reservation, 0 means optional
Use this function for debugging/monitoring purposes.

Definition at line 264 of file clientlib.c.

References server_id, and server_init().

Referenced by l4cpu_reserve_dump().

int l4cpu_reserve_watch ( l4_threadid_t  thread,
unsigned **  addr 
)

Watch exception IPCs for the given thread.

Parameters:
thread thread to be watched
addr will contain ptr to overflow-field after return. if 0, no address will be provided in return.
The function starts watching for exception IPCs (deadline miss or timeslice expired) at cpu_reserved. If addr is not 0 on calling, the returned array contains an unsigned for each timeslice id, which is incremented on each timeslice expired IPC.

Definition at line 228 of file clientlib.c.

References l4cpu_reserve_set_preempter(), server_id, and server_init().

CPU reservation server Reference Manual, written by Jork Loeser  © 2004