/shark/trunk/ports/first/fsf_include/fsf_shared_objects.h |
---|
1,3 → 1,7 |
/** |
@file Shared Objects |
*/ |
//fsf_shared_objects.h |
//================================================== |
// FFFFFFIII RRRRR SSTTTTTTT |
/shark/trunk/ports/first/fsf_include/fsf_distributed.h |
---|
1,3 → 1,7 |
/** |
@file Distributed. |
*/ |
//fsf_distributed.h |
//===================================================================== |
// FFFFFFIII RRRRR SSTTTTTTT |
20,36 → 24,36 |
#define FSF_DISTRIBUTED_MODULE_SUPPORTED 1 |
//This operation identifies a contract as a |
//bandwidth reservation on the network identified |
//by the network input parameter. Then the |
//contract negotiation is performed using the |
//conventional negotiation functions, including |
//the possibility of grouping the contract with |
//others. If the network_id given is |
//FSF_NULL_NETWORK_ID, the contract is considered |
//not to reserve bandwidth in a network but to |
//operate as any other regular contract. It |
//returns 0 if successful, or FSF_ERR_BAD_ARGUMENT |
//if contract is null or the network id is not |
//valid. |
/** |
\ingroup distjmodule |
This operation identifies a contract as a bandwidth reservation on |
the network identified by the network input parameter. Then the |
contract negotiation is performed using the conventional |
negotiation functions, including the possibility of grouping the |
contract with others. If the network_id given is |
FSF_NULL_NETWORK_ID, the contract is considered not to reserve |
bandwidth in a network but to operate as any other regular |
contract. It returns 0 if successful, or FSF_ERR_BAD_ARGUMENT if |
contract is null or the network id is not valid. |
*/ |
int |
fsf_set_contract_network_id |
(fsf_contract_parameters_t *contract, |
fsf_network_id_t network_id); |
/** |
//This operation puts the network identification |
//corresponding to the contract parameters object |
//pointed to by contract in the variable pointed |
//to by network_id. If the contract is a regular |
//one and therefore has not a network_id set, it |
//puts the FSF_NULL_NETWORK_ID constant instead. |
//it returns 0 if successful, or |
//FSF_ERR_BAD_ARGUMENT if any of the pointers is |
//null. |
\ingroup distjmodule |
This operation puts the network identification corresponding to the |
contract parameters object pointed to by contract in the variable |
pointed to by network_id. If the contract is a regular one and |
therefore has not a network_id set, it puts the FSF_NULL_NETWORK_ID |
constant instead. it returns 0 if successful, or |
FSF_ERR_BAD_ARGUMENT if any of the pointers is null. |
*/ |
int |
fsf_get_contract_network_id |
(const fsf_contract_parameters_t *contract, |
61,34 → 65,40 |
typedef FSF_SEND_ENDPOINT_T_OPAQUE fsf_send_endpoint_t; |
typedef FSF_RECEIVE_ENDPOINT_T_OPAQUE fsf_receive_endpoint_t; |
//The node_address type specifies the node address |
//in a communication-protocol-independent way. The actual |
//address is obtained via a configuration dependent mapping |
//function |
/** |
\ingroup distjmodule |
The node_address type specifies the node address in a |
communication-protocol-independent way. The actual address is |
obtained via a configuration dependent mapping function |
*/ |
typedef unsigned int fsf_node_address_t; |
//The port type specifies the information that is |
//necessary to get in contact with the thread in the |
//receiving node, in a protocol-independent way. |
//The actual port number is obtained via a configuration |
//dependent mapping function |
/** |
\ingroup distjmodule |
The port type specifies the information that is necessary to get in |
contact with the thread in the receiving node, in a |
protocol-independent way. The actual port number is obtained via a |
configuration dependent mapping function |
*/ |
typedef unsigned int fsf_port_t; |
//This operation creates a unidirectional input |
//data endpoint through which, after the |
//corresponding binding, it is possible to send |
//data. network_id identifies the network to use, |
//receiver specifies the communication protocol |
//dependent information that is necessary to |
//address the receiving node, and port specifies |
//the communication protocol dependent information |
//that is necessary to get in contact with the |
//desired destination. |
//It returns 0 if |
//successful. It returns FSF_ERR_BAD_ARGUMENT if |
//the endpoint is null, if the network_id is not |
//valid, or if the receiver or the port do not |
//conform to their expected formats. |
/** |
\ingroup distjmodule |
This operation creates a unidirectional input data endpoint through |
which, after the corresponding binding, it is possible to send |
data. network_id identifies the network to use, receiver specifies |
the communication protocol dependent information that is necessary |
to address the receiving node, and port specifies the communication |
protocol dependent information that is necessary to get in contact |
with the desired destination. It returns 0 if successful. It |
returns FSF_ERR_BAD_ARGUMENT if the endpoint is null, if the |
network_id is not valid, or if the receiver or the port do not |
conform to their expected formats. |
*/ |
int |
fsf_create_send_endpoint |
(fsf_network_id_t network_id, |
96,25 → 106,28 |
fsf_port_t port, |
fsf_send_endpoint_t *endpoint); |
//This operation eliminates any resources reserved |
//for the referenced endpoint. If the endpoint is |
//bound to a network server, it is unbound from it |
//and can not be further used to invoke send |
//operations on it. |
//It returns 0 if successful, |
//or FSF_ERR_BAD_ARGUMENT if the endpoint is not |
//valid. |
/** |
\ingroup distjmodule |
This operation eliminates any resources reserved for the referenced |
endpoint. If the endpoint is bound to a network server, it is |
unbound from it and can not be further used to invoke send |
operations on it. It returns 0 if successful, or |
FSF_ERR_BAD_ARGUMENT if the endpoint is not valid. |
*/ |
int |
fsf_destroy_send_endpoint |
(fsf_send_endpoint_t *endpoint); |
//This operation returns (except for those NULL |
//arguments) in the variables pointed to by |
//network_id, receiver, or port, the corresponding |
//parameters used in the creation of the given |
//send endpoint. It returns 0 if successful, or |
//FSF_ERR_BAD_ARGUMENT if the endpoint is not |
//valid. |
/** |
\ingroup distjmodule |
This operation returns (except for those NULL arguments) in the |
variables pointed to by network_id, receiver, or port, the |
corresponding parameters used in the creation of the given send |
endpoint. It returns 0 if successful, or FSF_ERR_BAD_ARGUMENT if |
the endpoint is not valid. |
*/ |
int |
fsf_get_send_endpoint_parameters |
(const fsf_send_endpoint_t *endpoint, |
122,59 → 135,67 |
fsf_node_address_t *receiver, |
fsf_port_t *port); |
//This operation associates a send endpoint with a |
//server, which means that messages sent through |
//that endpoint will consume the server's reserved |
//bandwidth and its packets will be sent according |
//to the contract established for that server. If |
//the endpoint is already bound to another server, |
//it is effectively unbound from it and bound to |
//the specified one. |
//The operation returns 0 if successful, or |
//FSF_ERR_BAD_ARGUMENT if the endpoint or the server |
//are not valid, it also fails with a |
//value of FSF_ERR_ALREADY_BOUND if the server is |
//already bound to some other send endpoint. |
//It fails with FSF_ERR_WRONG_NETWORK if the server |
//network id is not the same as the one in the endpoint |
/** |
\ingroup distjmodule |
This operation associates a send endpoint with a server, which |
means that messages sent through that endpoint will consume the |
server's reserved bandwidth and its packets will be sent according |
to the contract established for that server. If the endpoint is |
already bound to another server, it is effectively unbound from it |
and bound to the specified one. The operation returns 0 if |
successful, or FSF_ERR_BAD_ARGUMENT if the endpoint or the server |
are not valid, it also fails with a value of FSF_ERR_ALREADY_BOUND |
if the server is already bound to some other send endpoint. It |
fails with FSF_ERR_WRONG_NETWORK if the server network id is not |
the same as the one in the endpoint */ |
int |
fsf_bind_endpoint_to_server |
(fsf_server_id_t server, |
fsf_send_endpoint_t *endpoint); |
//This operation unbinds a send endpoint from a |
//server Endpoints with no server associated |
//cannot be used to send data, and they stay in |
//that state until they are either eliminated or |
//bound again. The operation fails with |
//FSF_ERR_NOT_BOUND if the endpoint has no server |
//bound |
/** |
\ingroup distjmodule |
This operation unbinds a send endpoint from a server Endpoints with |
no server associated cannot be used to send data, and they stay in |
that state until they are either eliminated or bound again. The |
operation fails with FSF_ERR_NOT_BOUND if the endpoint has no |
server bound */ |
int |
fsf_unbind_endpoint_from_server |
(fsf_send_endpoint_t *endpoint); |
//This operation copies the id of the server that |
//is bound to the specified send endpoint into the |
//variable pointed to by server. It returns 0 if |
//successful, or FSF_ERR_BAD_ARGUMENT if the |
//endpoint is not valid or server is NULL |
/** |
\ingroup distjmodule |
This operation copies the id of the server that |
is bound to the specified send endpoint into the |
variable pointed to by server. It returns 0 if |
successful, or FSF_ERR_BAD_ARGUMENT if the |
endpoint is not valid or server is NULL |
*/ |
int |
fsf_get_endpoint_server |
(const fsf_send_endpoint_t *endpoint, |
fsf_server_id_t *server); |
//This operation sends a message stored in msg and of length size |
//through the given endpoint. The operation is non-blocking and |
//returns immediately. An internal fsf service will schedule the |
//sending of messages and implement the communications sporadic server |
//corresponding to the network server bound to the given endpoint. |
//Messages sent through the same endpoint are received in the same |
//order in which they were sent It returns 0 if successful, but it |
//fails with FSF_ERR_BAD_ARGUMENT if endpoint is not valid; it fails |
//with FSF_ERR_NOT_BOUND is not bound to a valid server; it fails with |
//FSF_ERR_TOO_LARGE if the message is too large for the network |
//protocol; it fails with FSF_ERR_BUFFER_FULL if the sending queue is |
//full |
/** |
\ingroup distjmodule |
This operation sends a message stored in msg and of length size |
through the given endpoint. The operation is non-blocking and |
returns immediately. An internal fsf service will schedule the |
sending of messages and implement the communications sporadic |
server corresponding to the network server bound to the given |
endpoint. Messages sent through the same endpoint are received in |
the same order in which they were sent It returns 0 if successful, |
but it fails with FSF_ERR_BAD_ARGUMENT if endpoint is not valid; it |
fails with FSF_ERR_NOT_BOUND is not bound to a valid server; it |
fails with FSF_ERR_TOO_LARGE if the message is too large for the |
network protocol; it fails with FSF_ERR_BUFFER_FULL if the sending |
queue is full */ |
int |
fsf_send |
(const fsf_send_endpoint_t *endpoint, |
181,10 → 202,14 |
void *msg, |
size_t size); |
//This operation creates a receive endpoint with all the information |
//that is necessary to receive information from the specified network |
//and port It returns 0 if successful, but it fails with |
//FSF_ERR_BAD_ARGUMENT if the port or the network id are not valid. |
/** |
\ingroup distjmodule |
This operation creates a receive endpoint with all the information |
that is necessary to receive information from the specified network |
and port It returns 0 if successful, but it fails with |
FSF_ERR_BAD_ARGUMENT if the port or the network id are not |
valid. */ |
int |
fsf_create_receive_endpoint |
(fsf_network_id_t network_id, |
191,20 → 216,23 |
fsf_port_t port, |
fsf_receive_endpoint_t *endpoint); |
//If there are no messages available in the specified receive endpoint |
//this operation blocks the calling thread waiting for a message to be |
//received. When a message is available, if its size is less than or |
//equal to the buffersize, the function stores it in the variable |
//pointed to by buffer and puts the number of bytes received in the |
//variable pointed to by messagesize. The function fails with |
//FSF_ERR_NO_SPACE if the buffersize is too small for the message |
//received (in which case the message is lost), or with |
//FSF_ERR_BAD_ARGUMENT if the endpoint is not valid, or if buffer or |
//messagesize are NULL. Messages arriving at a receiver buffer that |
//is full will be silently discarded. The application is responsible |
//of reading the receive endpoints with appropriate regularity, or of |
//using a sequence number or some other mechanism to detect any lost |
//messages. |
/** |
\ingroup distjmodule |
If there are no messages available in the specified receive |
endpoint this operation blocks the calling thread waiting for a |
message to be received. When a message is available, if its size is |
less than or equal to the buffersize, the function stores it in the |
variable pointed to by buffer and puts the number of bytes received |
in the variable pointed to by messagesize. The function fails with |
FSF_ERR_NO_SPACE if the buffersize is too small for the message |
received (in which case the message is lost), or with |
FSF_ERR_BAD_ARGUMENT if the endpoint is not valid, or if buffer or |
messagesize are NULL. Messages arriving at a receiver buffer that |
is full will be silently discarded. The application is responsible |
of reading the receive endpoints with appropriate regularity, or of |
using a sequence number or some other mechanism to detect any lost |
messages.*/ |
int |
fsf_receive |
(const fsf_receive_endpoint_t *endpoint, |
212,11 → 240,13 |
size_t buffersize, |
size_t *messagesize); |
//This operation is the same as fsf_receive, except |
//that if there are no messages available in the |
//specified receive endpoint at the time of the call |
//the operation returns with an error of |
//FSF_ERR_NO_MESSAGES |
/** |
\ingroup distjmodule |
This operation is the same as fsf_receive, except that if there are |
no messages available in the specified receive endpoint at the time |
of the call the operation returns with an error of |
FSF_ERR_NO_MESSAGES */ |
int |
fsf_try_receive |
(const fsf_receive_endpoint_t *endpoint, |
224,13 → 254,17 |
size_t buffersize, |
size_t *messagesize); |
//This operation is used to calculate the minimum and/or maximum |
//budgets used in the preparation of network contracts. It puts in the |
//variable pointed to by budget the transmission time that it takes to |
//send a message of size msg_size through the network designated by |
//network_id, when there is no contention, but including any network |
//overheads It returns FSF_ERR_BAD_ARGUMENT if network_id is not a |
//valid identifier or if budget is a NULL pointer. |
/** |
\ingroup distjmodule |
This operation is used to calculate the minimum and/or maximum |
budgets used in the preparation of network contracts. It puts in |
the variable pointed to by budget the transmission time that it |
takes to send a message of size msg_size through the network |
designated by network_id, when there is no contention, but |
including any network overheads It returns FSF_ERR_BAD_ARGUMENT if |
network_id is not a valid identifier or if budget is a NULL |
pointer.*/ |
int |
fsf_tx_time |
(fsf_network_id_t network_id, |
237,9 → 271,12 |
size_t msg_size, |
struct timespec *budget); |
//This operation is used to obtain the maximum message size for the |
//specified network It returns FSF_ERR_BAD_ARGUMENT if network_id is |
//not a valid identifier or if max_msg_size is NULL |
/** |
\ingroup distjmodule |
This operation is used to obtain the maximum message size for the |
specified network It returns FSF_ERR_BAD_ARGUMENT if network_id is |
not a valid identifier or if max_msg_size is NULL */ |
int |
fsf_max_message_size |
(fsf_network_id_t network_id, |
/shark/trunk/ports/first/fsf_include/docs/Doxyfile |
---|
12,28 → 12,28 |
REPEAT_BRIEF = YES |
ALWAYS_DETAILED_SEC = NO |
INLINE_INHERITED_MEMB = NO |
FULL_PATH_NAMES = YES |
FULL_PATH_NAMES = NO |
STRIP_FROM_PATH = |
SHORT_NAMES = NO |
JAVADOC_AUTOBRIEF = NO |
MULTILINE_CPP_IS_BRIEF = NO |
DETAILS_AT_TOP = NO |
INHERIT_DOCS = YES |
DISTRIBUTE_GROUP_DOC = YES |
INHERIT_DOCS = NO |
DISTRIBUTE_GROUP_DOC = NO |
TAB_SIZE = 8 |
ALIASES = |
OPTIMIZE_OUTPUT_FOR_C = YES |
OPTIMIZE_OUTPUT_JAVA = NO |
SUBGROUPING = YES |
SUBGROUPING = NO |
#--------------------------------------------------------------------------- |
# Build related configuration options |
#--------------------------------------------------------------------------- |
EXTRACT_ALL = NO |
EXTRACT_ALL = YES |
EXTRACT_PRIVATE = NO |
EXTRACT_STATIC = NO |
EXTRACT_STATIC = YES |
EXTRACT_LOCAL_CLASSES = YES |
HIDE_UNDOC_MEMBERS = YES |
HIDE_UNDOC_CLASSES = YES |
HIDE_UNDOC_MEMBERS = NO |
HIDE_UNDOC_CLASSES = NO |
HIDE_FRIEND_COMPOUNDS = NO |
HIDE_IN_BODY_DOCS = NO |
INTERNAL_DOCS = NO |
62,7 → 62,14 |
# configuration options related to the input files |
#--------------------------------------------------------------------------- |
INPUT = maindocpage.h \ |
./../../fsf_include/ |
../fsf_core.h \ |
../fsf_spare_capacity.h \ |
../fsf_hierarchical.h \ |
../fsf_shared_objects.h \ |
../fsf_distributed.h \ |
../fsf_distributed_spare_capacity.h \ |
../fsf_dynamic_reclaiming.h \ |
../fsf_basic_types.h |
FILE_PATTERNS = *.c \ |
*.cc \ |
*.cxx \ |
87,7 → 94,7 |
*.inc \ |
*.m \ |
*.mm |
RECURSIVE = YES |
RECURSIVE = NO |
EXCLUDE = |
EXCLUDE_SYMLINKS = NO |
EXCLUDE_PATTERNS = |
110,7 → 117,7 |
# configuration options related to the alphabetical class index |
#--------------------------------------------------------------------------- |
ALPHABETICAL_INDEX = NO |
COLS_IN_ALPHA_INDEX = 5 |
COLS_IN_ALPHA_INDEX = 3 |
IGNORE_PREFIX = fsf_ |
#--------------------------------------------------------------------------- |
# configuration options related to the HTML output |
/shark/trunk/ports/first/fsf_include/docs/maindocpage.h |
---|
1,11 → 1,6 |
/** |
\mainpage FSF reference |
@author Giuseppe Lipari |
@author Michael Gonzalez Harbour |
@authos Alan Burns |
@author Gehrard Fohler |
This reference manual contains the description of the API provided |
by the FSF library. |
13,25 → 8,116 |
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. |
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 |
(from the FIRST documentation...) Links to the public documents. |
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. |
\section what What it provides |
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. |
description of the services and modules |
FSF provides a generalized architecture framework that combines |
different kinds of requirements: |
\section modu The modules |
- 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 |
47,37 → 133,87 |
/** |
\defgroup sparemodule Spare capacity sharing module |
This modules include functions for sharing the spare capacity in |
the system between the servers. It allows to mainly to specify |
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 very much (see the \ref |
core_negotiate module). |
influences the negotiation procedure (see the \ref core_negotiate |
module). |
@todo [PEPPE: TB continued] |
*/ |
/** |
\defgroup hiermodule Hierarchical scheduling module |
This module includes functions to schedule more than one thread in |
each server. Each server must be assigned a local scheduler which |
is responsible for scheduling the threads in the server. |
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. |
@todo [PEPPE: TB continued] |
We are currently providing three top-level schedulers: fixed |
priorities, EDF, and table-driven. |
*/ |
/** |
\defgroup shobjmodule Shared Objects module |
This module include functions to manage shared objects between |
threads. |
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. |
@todo [PEPPE: TB continued] |
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 |
*/ |
/shark/trunk/ports/first/fsf_include/fsf_spare_capacity.h |
---|
1,3 → 1,6 |
/** |
@file Spare capacity file. |
*/ |
//fsf_spare_capacity.h |
//=================================================== |
// FFFFFFIII RRRRR SSTTTTTTT |
/shark/trunk/ports/first/fsf_include/fsf_core.h |
---|
1,3 → 1,11 |
/** |
@file This file contains the functions and definitions for the core |
module. |
The file contains all fuinctions and data structures for the core |
module of the FSF. |
*/ |
//fsf_core.h |
//================================================================= |
// FFFFFFIII RRRRR SSTTTTTTT |
11,6 → 19,7 |
// Basic FSF(FIRST Scheduling Framework) contract management |
//================================================================ |
#include <time.h> |
#include <pthread.h> |
#include <sys/types.h> |
295,8 → 304,8 |
variable managed by the scheduler, and returns a handle to it in |
the variable pointed to by synch_handle. |
@param[out] pointer to the variable that will contain the handle to the |
newly created synchronization object |
@param[out] synch_handle pointer to the variable that will contain |
the handle to the newly created synchronization object |
@retval 0 if the operation is succesful |
@retval FSF_ERR_BAD_ARGUMENT if synch_handle is 0 |
423,7 → 432,7 |
parameter is set to NULL, no action is |
taken. |
@param [out] was_budget_overrun upon return of this function, the |
@param [out] was_budget_overran upon return of this function, the |
variable pointed by this function will be |
equal to true if the previous server budget was |
overrun, to false otherwise. If this |
496,7 → 505,7 |
parameter is set to NULL, no action is |
taken. |
@param [out] was_budget_overrun upon return of this function, the |
@param [out] was_budget_overran upon return of this function, the |
variable pointed by this function will be |
equal to true if the previous server budget was |
overrun, to false otherwise. If this |
570,9 → 579,7 |
The following functions are used to create servers for a contract |
parameters specification and also to assign one or more threads to |
a server (Note: the current implementation only supports one thread |
per server; this limitation will be removed in the next phase of |
the project) |
a server. |
*/ |
/*@{*/ |
778,11 → 785,11 |
@param [out] server server |
@retval 0 if the operation is succesful |
@retrun FSF_ERR_NOT_SCHEDULED_THREAD if the given thread is not scheduled |
@return FSF_ERR_NOT_SCHEDULED_THREAD if the given thread is not scheduled |
under the FSF |
@retrun FSF_ERR_UNBOUND if the given thread does not have a valid |
@return FSF_ERR_UNBOUND if the given thread does not have a valid |
server bound to it |
@retrun FSF_ERR_BAD_ARGUMENT if the given thread does not exist or the |
@return FSF_ERR_BAD_ARGUMENT if the given thread does not exist or the |
server argument is NULL |
*/ |
int |
888,7 → 895,7 |
@param [in] new_contract pointer to the new contract to be negotiated |
@param [in] server server id |
@param [in] sig_notify NULL (no signal) or any POSIX signal |
@param [in] sign_value a sigval structure that contains values to be |
@param [in] sig_value a sigval structure that contains values to be |
passed to the signal handler. Valid only if sig_notify |
is different from NULL. |
974,7 → 981,7 |
server is is not valid. |
@param [in] contracts_up list of contracts to negotiate |
@param [in] contracts_down list of contracts to be canceled |
@param [in] servers_down list of contracts to be canceled |
@param [out] servers_up list of server ids that have been created, they are |
given in the same order as the contract_up list of contracts; |
@param [out] accepted if the operation is succesful; |
994,8 → 1001,8 |
int |
fsf_negotiate_group |
(const fsf_contracts_group_t *contracts_up, |
const fsf_servers_group_t *severs_down, |
fsf_servers_group_t *severs_up, |
const fsf_servers_group_t *servers_down, |
fsf_servers_group_t *servers_up, |
bool *accepted); |
1116,9 → 1123,6 |
These functions are to the initialization and tuning of the service |
thread. |
@todo specify that the default budget and periods are in the |
configuration file. |
Implementation dependency: in the fixed priority implementation of |
fsf, the default priority is lower than the priority of any server, |
but higher than the background. According to the |
/shark/trunk/ports/first/fsf_include/fsf_distributed_spare_capacity.h |
---|
1,3 → 1,7 |
/** |
@file distributed spare capacity |
*/ |
//fsf_distributed_spare_capacity.h |
//===================================================================== |
// FFFFFFIII RRRRR SSTTTTTTT |
20,17 → 24,19 |
#define FSF_DISTRIBUTED_SPARE_CAPACITY_MODULE_SUPPORTED 1 |
/** |
\ingroup distsparemodule |
//This operation sets the granted capacity flag in the contract |
//parameters object pointed to by contract to the boolean specified in |
//granted_capacity_flag. This flag indicates to the scheduler that |
//once the negotiation of the respective contract is finished, the |
//first values for the budget and period given to the corresponding |
//server must not be changed due to the negotiation or renegotiation |
//of any other contract in the system. The period can change, though, |
//if a renegotiation or a change of quality and importance is |
//requested for the corresponding server It fails with |
//FSF_ERR_BAD_ARGUMENT if contract is NULL. |
This operation sets the granted capacity flag in the contract |
parameters object pointed to by contract to the boolean specified |
in granted_capacity_flag. This flag indicates to the scheduler that |
once the negotiation of the respective contract is finished, the |
first values for the budget and period given to the corresponding |
server must not be changed due to the negotiation or renegotiation |
of any other contract in the system. The period can change, though, |
if a renegotiation or a change of quality and importance is |
requested for the corresponding server It fails with |
FSF_ERR_BAD_ARGUMENT if contract is NULL. */ |
int |
fsf_set_contract_granted_capacity_flag |
(fsf_contract_parameters_t *contract, |
37,10 → 43,13 |
bool granted_capacity_flag); |
//This operation returns in the place pointed to by |
//granted_capacity_flag the value of the corresponding flag in the |
//contract parameters object pointed to by contract. It fails with |
//FSF_ERR_BAD_ARGUMENT if any of the pointers is NULL |
/** |
\ingroup distsparemodule |
This operation returns in the place pointed to by |
granted_capacity_flag the value of the corresponding flag in the |
contract parameters object pointed to by contract. It fails with |
FSF_ERR_BAD_ARGUMENT if any of the pointers is NULL */ |
int |
fsf_get_contract_granted_capacity_flag |
(fsf_contract_parameters_t *contract, |
47,21 → 56,24 |
bool *granted_capacity_flag); |
//This operation is used to return spare capacity that was assigned to |
//a server but that cannot be used due to restrictions in other |
//servers of a distributed transaction. This operation changes the |
//cycle period and budget of the given server to the values given in |
//new_period and new_budget, respectively. It fails with |
//FSF_ERR_BAD_ARGUMENT if the server does not have the |
//granted_capacity flag set, if the new period is less than the |
//current one, or if the new budget is larger than the current one. It |
//also fails with the same error number if the new period is greater |
//than the maximum period currently specified in the contract |
//associated to the server or, similarly, if the new budget is smaller |
//than the minimum budget in the contract. It also fails with the |
//same number if the granularity is discrete and the new period and |
//budget do not match any of the period-budget pairs in the |
//utilization set of the server |
/** |
\ingroup distsparemodule |
This operation is used to return spare capacity that was assigned |
to a server but that cannot be used due to restrictions in other |
servers of a distributed transaction. This operation changes the |
cycle period and budget of the given server to the values given in |
new_period and new_budget, respectively. It fails with |
FSF_ERR_BAD_ARGUMENT if the server does not have the |
granted_capacity flag set, if the new period is less than the |
current one, or if the new budget is larger than the current |
one. It also fails with the same error number if the new period is |
greater than the maximum period currently specified in the contract |
associated to the server or, similarly, if the new budget is |
smaller than the minimum budget in the contract. It also fails |
with the same number if the granularity is discrete and the new |
period and budget do not match any of the period-budget pairs in |
the utilization set of the server */ |
int |
fsf_set_server_capacity |
(fsf_server_id_t server, |