Main Page | Namespace List | Class Hierarchy | Class List | File List | Namespace Members | Class Members | File Members

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:

Include dependency graph

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

Included by dependency graph

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_paramrk_reserve_param_t
 The resource reservation parameters.

typedef cpu_reserve_attrcpu_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.


Generated on Mon Dec 1 16:22:26 2003 for CPUBroker by doxygen 1.3.4