Subversion Repositories shark

/**

   \mainpage FSF reference

   This reference manual contains the description of the API provided

   by the FSF library.

   \section intro Introduction to FSF

   The First Scheduling Framework (FSF) is the result of a joint

   effort from four european research groups to propose an API for

   flexible real-time scheduling in Real Time operating systems.  See

   <a href="http://130.243.76.81:8080/salsart/first/">the FIRST web

   page</a> for more details in the project.

   \section lib Objectives

Scheduling theory generally assumes that real-time systems are mostly

composed of activities with hard real-time requirements, many systems

are built today by composing different application or components in

the same system, leading to a mixture of many different kinds of

requirements with small parts of the system having hard real-time

requirements and other larger parts with requirements for more

flexible scheduling, taking into account quality of service. Hard

real-time scheduling techniques are extremely pessimistic for the

latter part of the application, and consequently it is necessary to

use techniques that let the system resources be fully utilized to

achieve the highest possible quality.

The FIRST project aims at developing a framework for a scheduling

architecture that provides the ability to compose several applications

or components into the system, and to flexibly schedule the available

resources while guaranteeing hard real-time requirements. The FIRST

Scheduling Framework (FSF) is independent of the underlying

implementation, and can run on different underlying scheduling

strategies. It is based on establishing service contracts that

represent the complex and flexible requirements of the application,

and which are managed by the underlying system to provide the required

level of service.

FSF provides a generalized architecture framework that combines

different kinds of requirements:

 - co-operation and coexistence of standard real-time scheduling

   schemes, time-triggered and eventtriggered, dynamic and fixed

   priority based, as well as off-line based through a common

   architecture that is independent on the underlying scheduling

   mechanism

- integration of different timing requirements such as hard and soft,

  and more flexible notions

- temporal encapsulation of subsystems in order to support the

  composability and reusability of available components including

  legacy subsystems.

FSF has been implemented in two POSIX compliant real-time operating

systems, <a href="http://marte.unican.es">MaRTE</a> and <a

href="http://shark.sssup.it/">SHARK</a>, which are based on FP and EDF

scheduling schemes, respectively, thus illustrating the platform

independence of the presented approach.

   \section Service Contracts

The service contract is the mechanism that we have chosen for the

application to dynamically specify its own set of complex and flexible

execution requirements. From the application s perspective, the

requirements of an application or application component are written as

a set of service contracts, which are negotiated with the underlying

implementation. To accept a set of contracts, the system has to check

as part of the negotiation if it has enough resources to guarantee all

the minimum requirements specified, while keeping guarantees on all

the previously accepted contracts negotiated by other application

components. If as a result of this negotiation the set of contracts is

accepted, the system will reserve enough capacity to guarantee the

minimum requested resources, and will adapt any spare capacity

available to share it among the different contracts that have

specified their desire or ability for using additional capacity.

As a result of the negotiation process, if a contract is accepted, a

server is created for it. The server is a software object that is the

run-time representation of the contract; it stores all the information

related to the resources currently reserved for that contract, the

resources already consumed, and the resources required to handle the

budget consumption and replenishment events in the particular

operating system being used.

Because there are various application requirements specified in the

contract, they are divided into several groups, also allowing the

underlying implementation to give different levels of support trading

them against implementation complexity. This gives way to a modular

implementation of the framework, with each module addressing specific

application requirements. The minimum resources required by the

application to be reserved by the system are specified in the core

module. The requirements for mutual exclusive synchronization among

parts of the application being scheduled by different servers or among

different applications are specified in the shared objects

module. Flexible resource usage is associated with the spare capacity

and dynamic reclamation modules. The ability to compose applications

or application components with several threads of control, thus

requiring hierarchical scheduling of several threads inside the same

server are supported by the hierarchical scheduling module. Finally,

the requirements of distributed applications are supported by the

distributed and the distributed spare capacity modules. We will now

explain these modules together with their associated application

requirements.

 */

/**

   \defgroup coremodule Core module

The core module contains the service contract information related to

the application minimum resource requirements, the operations required

to create contracts and negotiate them, and the underlying

implementation of the servers with a resource reservation mechanism

that allows the system to guarantee the resources granted to each

server.

   This module includes the basic functions and services that are

   provided by any FSF implementation. This module includes basic type

   definitions, and functions to

   - create a contract and initialize it

   - set/get the basic parameters of a contract

   - negotiate a service contract, obtaining a server id

   - create and bind threads to servers

   - create/destroy a synchronization object

   - manage bounded workloads

*/

/**

   \defgroup sparemodule Spare capacity sharing module

Many applications have requirements for flexibility regarding the

amount of resources that can be used. The spare capacity module allows

the system to share the spare capacity that may be left over from the

negotiation of the service contracts, in a static way. During the

negotiation, the minimum requested resources are granted to each

server, if possible. Then, if there is any extra capacity left, it is

distributed among those applications that have expressed their ability

to take advantage of it.

   This module include functions for sharing the spare capacity in the

   system between the servers. It allows to mainly to specify

   additional contract parameters to allow the sharing of the spare

   capacity.

   The features provided by this module are different from the

   services provided by the Dynamic reclamation module. This module

   influences the negotiation procedure (see the \ref core_negotiate

   module).

 */

/**

   \defgroup hiermodule Hierarchical scheduling module

One of the application requirements that FSF addresses is the ability

to compose different applications, possibly using different scheduling

policies, into the same system. This can be addressed with support in

the system for hierarchical scheduling. The lower level is the

scheduler that takes care of the service contracts, using an

unspecified scheduling policy (for instance, a CBS on top of EDF, or a

sporadic server on top of fixed priorities). The top level is a

scheduler running inside one particular FSF server, and scheduling the

application threads with whatever scheduling policy they were

designed. In this way, it is possible to have in the same system one

application with, for example, fixed priorities, and another one

running concurrently with an EDF scheduler.

We are currently providing three top-level schedulers: fixed

priorities, EDF, and table-driven.

 */

/**

   \defgroup shobjmodule Shared Objects module

The shared objects module of FSF allows the application to specify in

the contract attributes all the information required to do the

schedulability analysis.

The set of shared objects present in the system together with the

lists of critical sections specified for each contract are used for

schedulability analysis purposes only. A run-time mechanism for mutual

exclusion is not provided in FSF for two important reasons. One of

them is upward compatibility of previous code using regular primitives

such as mutexes or protected objects (in Ada); this is a key issue if

we want to persuade application developers to switch their systems to

the FSF environment. The second reason is that enforcing worst case

execution time for critical sections is expensive. The number of

critical sections in real pieces of code may be very high, in the tens

or in the hundreds per task, and monitoring all of them would require

a large amount of system resources.

The FSF application does not depend on any particular synchronization

protocol, but there is a requirement that a budget expiration cannot

occur inside a critical section, because otherwise the blocking delays

could be extremely large. This implies that the application is allowed

to overrun its budget for the duration, at most, of the critical

section, and this extra budget is taken into account in the

schedulability analysis.

 */

/**

   \defgroup distjmodule Distributed module

@todo Peppe complete description

 */

/**

   \defgroup distsparemodule Distributed spare capacity module

@todo Peppe complete description

 */