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

#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.

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.

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 1296 of file rk_stub.c.
References NANOS_PER_MICRO.

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 1256 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 1276 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 924 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_reserve_t, 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(), and server_main().