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

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	cpu_reserve_attr
	The CPU reservation parameters. More...
struct	rk_reserve_param
	The resource reservation parameters. More...
Defines
#define	RK_STUB   1
	Inform the includer that this is the stub version.
#define	RK_NAME_LEN   32
	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.
#define	clock_gettime(clock_id, ts)   rk_clock_gettime(clock_id, ts)
	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.
#define	clock_settime(clock_id, ts)   rk_clock_settime(clock_id, ts)
	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.
#define	clock_getres(clock_id, ts)   rk_clock_getres(clock_id, ts)
	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.
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.
rk_resource_set_t	rk_resource_set_create (const char *name)
	Construct a mock resource set with the given name.
void	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 to the 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.
void	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.

---

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.

enum rk_reserve_mode_t

The resource reservation modes. Enumeration values: RSV_HARD  Hard reservation. RSV_FIRM  Firm reservation. RSV_SOFT  Soft reservation.

---

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.

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.

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.

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.

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.

void rk_cpu_reserve_delete (  rk_resource_set_t  rs  )

Delete a CPU reserve held by a resource set. Parameters: rs  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. 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.

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.

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.

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: _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.

void rk_resource_set_destroy (  rk_resource_set_t  rs  )

Destroy a resource set. Parameters: rs  The resource set to destroy.

int rk_resource_set_detach_process (  rk_resource_set_t  rs, pid_t  pid )

Detach a process to 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.

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.

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.

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.

---