rk.h File Reference

---

Detailed Description

This file contains a replica of the TimeSys resource control APIs.

The goal is to provide a close enough approximation that the same code can be used in the simulated and real worlds. The only visible difference between the two is the definition of RK_STUB, so any simulation specific code should be enclosed in an "#if defined(RK_STUB)".

See also:

rk_stub.h

Definition in file rk.h.

Include dependency graph for rk.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	rk_reserve_param
	The resource reservation parameters. More...
struct	cpu_reserve_attr
	The CPU reservation parameters. More...
Defines
#define	RK_STUB   1
	Inform the includer that this is the stub version.
#define	RK_NAME_LEN   16
	Maximum length for resource kernel names in general.
#define	RSET_NAME_LEN   RK_NAME_LEN
	Maximum length for resource set names.
#define	RT_MIN_PERIOD   (struct timespec){0, 20000}
	Minimum period of periodic process.
#define	NULL_RESOURCE_SET   ((rk_resource_set_t)0)
	NULL constant value for a resource set.
#define	NULL_RESERVE   ((rk_reserve_t)0)
	NULL constant value for a reserve.
Typedefs
typedef rk_reserve_param *	rk_reserve_param_t
	The resource reservation parameters.
typedef cpu_reserve_attr *	cpu_reserve_attr_t
	The CPU reservation parameters.
typedef rk_resource_set *	rk_resource_set_t
	Opaque reference to a resource set.
typedef void *	rk_reserve_t
	Opaque reference to a resource reserve.
Enumerations
enum	rk_processor_t { RK_ANY_CPU = -1 }
	Enumeration that can be used to specify which CPU a resource set can be bound to. More...
enum	rk_reserve_mode_t { RSV_HARD = 0x1, RSV_FIRM = 0x2, RSV_SOFT = 0x4 }
	The resource reservation modes. More...
enum	clockid_t { CLOCK_REALTIME, CLOCK_VIRTUAL, CLOCK_PROF }
	A clockid_t enumeration for those OS's that do not support it.
Functions
void	rk_inherit_mode (int dummy)
	Not implemented.
int	rk_resource_sets_get_list (rk_resource_set_t *rs_inout, int count)
	Query the system for the list of mock resource sets.
int	rk_resource_sets_get_num (void)
rk_resource_set_t	rk_resource_set_create (const char *name)
	Construct a mock resource set with the given name.
int	rk_resource_set_destroy (rk_resource_set_t rs)
	Destroy a resource set.
int	rk_resource_set_set_name (rk_resource_set_t rs, const char *name)
	Set the name of a resource set.
int	rk_resource_set_get_name (rk_resource_set_t rs, char *name_out)
	Get the name of a resource set.
rk_reserve_t	rk_resource_set_get_cpu_rsv (rk_resource_set_t rs)
	Get the CPU reserve from the given resource set.
int	rk_resource_set_attach_process (rk_resource_set_t rs, pid_t pid)
	Attach a process to the resource set so that its callbacks will be used when a data period is starting/ending.
int	rk_resource_set_detach_process (rk_resource_set_t rs, pid_t pid)
	Detach a process from the resource set.
int	rk_resource_set_get_num_procs (rk_resource_set_t rs)
int	rk_resource_set_get_proclist (rk_resource_set_t rs, pid_t *procs_inout, int count)
	Query the system for the list of processes attached to the given resource set.
rk_resource_set_t	rk_proc_get_rset (pid_t pid)
	Get the resource set attached to the given process.
int	rk_cpu_reserve_create (rk_resource_set_t rs, rk_reserve_t *r_out, cpu_reserve_attr_t ra_in)
	Create a CPU reserve for the given resource set.
int	rk_cpu_reserve_delete (rk_resource_set_t rs)
	Delete a CPU reserve held by a resource set.
int	rk_cpu_reserve_get_attr (rk_reserve_t cr, cpu_reserve_attr_t ra_out)
	Get the reservation parameters for a given CPU reserve.
int	rk_cpu_reserve_ctl (rk_resource_set_t rs, cpu_reserve_attr_t ra_in)
	Change a CPU reserve's scheduling parameters.
int	rk_clock_gettime (clockid_t clock_id, struct timespec *ts)
	Get the simulator's virtual time.
int	rk_clock_settime (clockid_t clock_id, struct timespec *ts)
	Set the simulator's virtual time.
int	rk_clock_getres (clockid_t clock_id, struct timespec *ts)
	Get the simulator's virtual clock resolution.

---

Typedef Documentation

typedef struct rk_reserve_param * rk_reserve_param_t

The resource reservation parameters. XXX Currently, all three fields must contain the same RSV value. Referenced by rk_reserve_param_string(), and rk_reserve_param_valid().

---

Enumeration Type Documentation

enum rk_processor_t

Enumeration that can be used to specify which CPU a resource set can be bound to. Enumeration values: RK_ANY_CPU  Use any CPU available on the system. Definition at line 67 of file rk.h.

enum rk_reserve_mode_t

The resource reservation modes. Enumeration values: RSV_HARD  Hard reservation. RSV_FIRM  Firm reservation. RSV_SOFT  Soft reservation. Definition at line 74 of file rk.h. Referenced by RKTask::BeginCPUScheduling().

---

Function Documentation

int rk_clock_getres (  clockid_t  clock_id, struct timespec *  ts )

Get the simulator's virtual clock resolution. Parameters: clock_id  The clock type, only CLOCK_REALTIME is supported. ts  The timespec object to fill out. Returns: Zero if the query was successful, otherwise it returns -1 and sets errno appropriately. Definition at line 1295 of file rk_stub.c.

int rk_clock_gettime (  clockid_t  clock_id, struct timespec *  ts )

Get the simulator's virtual time. Parameters: clock_id  The clock type, only CLOCK_REALTIME is supported. ts  The timespec object to fill out. Returns: Zero if the query was successful, otherwise it returns -1 and sets errno appropriately. Definition at line 1255 of file rk_stub.c. References rk_stub_data. Referenced by BasicDelegate::postcall(), and BasicDelegate::precall().

int rk_clock_settime (  clockid_t  clock_id, struct timespec *  ts )

Set the simulator's virtual time. This function should really only be used to set the time to a value _before_ the next event. Parameters: clock_id  The clock type, only CLOCK_REALTIME is supported. ts  The new virtual time value. Returns: Zero if the query was successful, otherwise it returns -1 and sets errno appropriately. Definition at line 1275 of file rk_stub.c. References rk_stub_data.

int rk_cpu_reserve_create (  rk_resource_set_t  rs, rk_reserve_t *  r_out, cpu_reserve_attr_t  ra_in )

Create a CPU reserve for the given resource set. In order to simulate this reserve, a "times" file must be available in the current directory. The contents of the file should be a whitespace separated list of floats that specify the percentage of CPU time required by the process for a repeating sequence of periods. For example, the times file for a resource set named "steady_50" that required 50% of the CPU at every period would be named "steady_50_cpu_times" and contain only "50.0". Another, more complex example, would be a reserve that oscillated between 10% and 50% with 10% steps would contain "10.0 20.0 30.0 40.0 50.0 40.0 30.0 20.0 10.0". The output of CPU simulation is a set of files that can be fed into gnuplot. The contents of the file are two columns of numbers, a time value, and a CPU percentage or an arbitrary value that marks some event. The current list of files is: _cpu_period The CPU reserve's period. _cpu_deadline The CPU reserve's deadline. _cpu_complete Marks the completion of a data period. _cpu_drop Marks a data period as being dropped. _cpu_realtime The CPU time required by the process. _cpu_success The actual CPU time received by a process that is making its deadlines. _cpu_fail The actual CPU time received by a process that is missing its deadlines. Parameters: rs  The resource set that will hold the CPU reserve. r_out  A pointer that can be set to the new CPU reserve. ra_in  The reservation parameters. Returns: Zero if the reserve was created successfully, an errno value otherwise. Definition at line 923 of file rk_stub.c. References cpu_reserve_attr_string(), cpu_reserve_attr_t, cpu_reserve_string(), cpu_reserve_t, cpu_reserve_valid(), cpu_reserve_attr::deadline, ensure, microsec_to_timespec(), require, rk_cpu_reserve_attr_valid(), rk_cpu_reserve_delete(), rk_cpu_trace_names, rk_resource_set_string(), rk_resource_set_t, rk_resource_set_valid(), rk_stub_data, RK_STUB_LOG, RK_STUB_SIM, RSET_NAME_LEN, and timespec_to_microsec(). Referenced by RKTask::BeginCPUScheduling(), rktCreateSelfResourceSet(), rktGetChildResourceSet(), rts_set_schedule(), and server_main().

Here is the call graph for this function:

int rk_cpu_reserve_ctl (  rk_resource_set_t  rs, cpu_reserve_attr_t  ra_in )

Change a CPU reserve's scheduling parameters. Parameters: rs  The CPU reserve to change. ra_in  The new scheduling parameters. Returns: Zero if the change was successful, an errno value otherwise. Definition at line 1197 of file rk_stub.c. References cpu_reserve_attr::compute_time, cpu_reserve_attr_string(), cpu_reserve_attr_t, cpu_reserve_t, require, rk_cpu_reserve_attr_valid(), rk_cpu_reserve_tick(), rk_resource_set_string(), rk_resource_set_t, rk_resource_set_valid(), rk_stub_data, and tscmp. Referenced by rts_set_schedule(), and RKTask::SetComputeTime().

Here is the call graph for this function:

int rk_cpu_reserve_delete (  rk_resource_set_t  rs  )

Delete a CPU reserve held by a resource set. Parameters: rs  A resource set. Returns: Zero on success, -1 on error. Definition at line 1113 of file rk_stub.c. References cpu_reserve_t, cpu_reserve_valid(), ensure, require, rk_resource_set_string(), rk_resource_set_t, rk_resource_set_valid(), and rk_stub_data. Referenced by RKTask::BeginCPUScheduling(), RKTask::EndCPUScheduling(), rk_cpu_reserve_create(), rk_resource_set_destroy(), rktGetChildResourceSet(), rts_clear_schedule(), rts_grab_schedulable(), and rts_release_schedulable().

Here is the call graph for this function:

int rk_cpu_reserve_get_attr (  rk_reserve_t  cr, cpu_reserve_attr_t  ra_out )

Get the reservation parameters for a given CPU reserve. Parameters: cr  The CPU reserve to query. ra_out  The cpu_reserve_attr object to fill with the CPU reserve's current parameters. Returns: Zero if the query was successful, an errno value otherwise. Definition at line 1167 of file rk_stub.c. References cpu_reserve_attr_string(), cpu_reserve_attr_t, cpu_reserve_string(), cpu_reserve_t, cpu_reserve_valid(), ensure, require, rk_cpu_reserve_attr_valid(), and rk_stub_data. Referenced by rts_get_schedule(), and sigalrm().

Here is the call graph for this function:

rk_resource_set_t rk_proc_get_rset (  pid_t  pid  )

Get the resource set attached to the given process. Parameters: pid  The fake process ID to query. Returns: The resource set that is attached to the process or NULL if none is attached. Definition at line 890 of file rk_stub.c. References ensure, require, rk_resource_set_string(), rk_resource_set_t, rk_resource_set_valid(), rk_stub_data, and rk_stub_pcb_string(). Referenced by RKObserverAdvocate::BeginCPUScheduling(), RKTask::BeginCPUScheduling(), main(), paGetAdvocate(), rk_resource_set_attach_process(), rk_resource_set_detach_process(), rts_grab_schedulable(), and RKObserverAdvocate::run().

Here is the call graph for this function:

int rk_resource_set_attach_process (  rk_resource_set_t  rs, pid_t  pid )

Attach a process to the resource set so that its callbacks will be used when a data period is starting/ending. Note: The simulator only supports one process being attached at a time. Parameters: rs  The resource set that will be attached to the process. pid  The fake process ID to attach to the resource set. Returns: Zero if the process was successfully attached, an errno value otherwise. Definition at line 738 of file rk_stub.c. References ensure, require, rk_proc_get_rset(), rk_resource_set_string(), rk_resource_set_t, rk_resource_set_valid(), rk_stub_data, and rk_stub_pcb_string(). Referenced by RKTask::BeginCPUScheduling(), main(), rktChildPart(), rktParentPart(), rts_grab_schedulable(), RKObserverAdvocate::run(), and server_main().

Here is the call graph for this function:

rk_resource_set_t rk_resource_set_create (  const char *  name  )

Construct a mock resource set with the given name. The name has special meaning in the simulator, it will be used as the base for any files that are produced or read by the stub code. For example, a file produced or read by the CPU reserve will use file names of the form: <name>_cpu_<file-type>. See also: rk_cpu_reserve_create rk_cpu_reserve_trace_t Parameters: name  The name for the resource set. Returns: A new rk_resource_set_t object or NULL if the creation failed. Definition at line 548 of file rk_stub.c. References ensure, lnAddTail(), require, rk_name_valid(), rk_resource_set_t, rk_resource_set_valid(), rk_stub_data, and RSET_NAME_LEN. Referenced by RKTask::BeginCPUScheduling(), main(), paGetAdvocate(), rktCreateSelfResourceSet(), rktGetChildResourceSet(), rts_grab_schedulable(), and server_main().

Here is the call graph for this function:

int rk_resource_set_destroy (  rk_resource_set_t  rs  )

Destroy a resource set. Parameters: rs  The resource set to destroy. Definition at line 594 of file rk_stub.c. References ensure, lnRemove(), require, rk_cpu_reserve_delete(), rk_resource_set_string(), rk_resource_set_t, rk_resource_set_valid(), and rk_stub_data. Referenced by RKTask::BeginCPUScheduling(), RKTask::EndCPUScheduling(), main(), rktCreateSelfResourceSet(), rktRepairResourceSets(), rts_release_schedulable(), rts_repair_resource_sets(), server_main(), and sigexit_handler().

Here is the call graph for this function:

int rk_resource_set_detach_process (  rk_resource_set_t  rs, pid_t  pid )

Detach a process from the resource set. Parameters: rs  The attached resource set. pid  The fake process ID to detach from the resource set. Returns: Zero if the process was successfully detached, an errno value otherwise. Definition at line 782 of file rk_stub.c. References ensure, require, rk_proc_get_rset(), rk_resource_set_string(), rk_resource_set_t, rk_resource_set_valid(), rk_stub_data, and rk_stub_pcb_string(). Referenced by main(), and RKObserverAdvocate::run().

Here is the call graph for this function:

rk_reserve_t rk_resource_set_get_cpu_rsv (  rk_resource_set_t  rs  )

Get the CPU reserve from the given resource set. Parameters: rs  The resource set to query. Returns: A pointer to the CPU reserve or NULL if the resource set did not have a CPU reserve attached. Definition at line 705 of file rk_stub.c. References cpu_reserve_valid(), ensure, require, rk_reserve_t, rk_resource_set_string(), rk_resource_set_t, rk_resource_set_valid(), and rk_stub_data. Referenced by RKTask::BeginCPUScheduling(), rktGetChildResourceSet(), rktRepairResourceSets(), rts_grab_schedulable(), rts_repair_resource_sets(), rts_set_schedule(), and sigalrm().

Here is the call graph for this function:

int rk_resource_set_get_name (  rk_resource_set_t  rs, char *  name_out )

Get the name of a resource set. Parameters: rs  The resource set to query. name_out  The character array, of atleast RSET_NAME_LEN length, to fill out with the name of the resource set. Returns: Zero if the parameters were valid, an errno value otherwise. Definition at line 672 of file rk_stub.c. References ensure, require, rk_resource_set_string(), rk_resource_set_t, rk_resource_set_valid(), rk_stub_data, and RSET_NAME_LEN. Referenced by main(), and rk_resource_set_get_by_name().

Here is the call graph for this function:

int rk_resource_set_get_num_procs (  rk_resource_set_t  rs  )

Parameters: rs  The resource set to query. Returns: The number of processes attached to the given resource set. Definition at line 821 of file rk_stub.c. References require, rk_resource_set_string(), rk_resource_set_t, and rk_stub_data. Referenced by RKTask::BeginCPUScheduling(), rktGetChildResourceSet(), rktRepairResourceSets(), rts_grab_schedulable(), and rts_repair_resource_sets().

Here is the call graph for this function:

int rk_resource_set_get_proclist (  rk_resource_set_t  rs, pid_t *  procs_inout, int  count )

Query the system for the list of processes attached to the given resource set. Note: The simulator only supports one process being attached at a time. Parameters: rs  The resource set to query for attached processes. procs_inout  An array that can hold atleast 'count' pid_t elements. count  The size of the 'procs_inout' array. Returns: The actual number of elements in the 'procs_inout' array that were filled in with pid's. Definition at line 851 of file rk_stub.c. References require, rk_resource_set_string(), rk_resource_set_t, and rk_stub_data. Referenced by rk_resource_set_get_usage(), and sigalrm().

Here is the call graph for this function:

int rk_resource_set_set_name (  rk_resource_set_t  rs, const char *  name )

Set the name of a resource set. This is provided for compatibility and is otherwise unwise to use since the name has meaning in the simulation code. Parameters: rs  The resource set to rename. name  The new name. Returns: Zero if the name was valid, an errno value otherwise. Definition at line 628 of file rk_stub.c. References ensure, require, rk_name_valid(), rk_resource_set_string(), rk_resource_set_t, rk_resource_set_valid(), rk_stub_data, and RSET_NAME_LEN.

Here is the call graph for this function:

int rk_resource_sets_get_list (  rk_resource_set_t *  rs_inout, int  count )

Query the system for the list of mock resource sets. Parameters: rs_inout  An array that can hold atleast 'count' rk_resource_set_t elements. count  The size of the 'rs_inout' array. Returns: The actual number of elements in the 'rs_inout' array that were filled in with resource set pointers. Definition at line 486 of file rk_stub.c. References require, rk_resource_set_t, and rk_stub_data. Referenced by rk_resource_set_get_by_name(), rktRepairResourceSets(), and rts_repair_resource_sets().

int rk_resource_sets_get_num (  void   )

Returns: The number of mock resource sets that are currently active. Definition at line 525 of file rk_stub.c. References require, and rk_stub_data.

---