Subversion Repositories shark

Compare Revisions

Ignore whitespace Rev 928 → Rev 929

/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);
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
48,7 → 48,7
GENERATE_DEPRECATEDLIST= YES
ENABLED_SECTIONS =
MAX_INITIALIZER_LINES = 30
SHOW_USED_FILES = YES
SHOW_USED_FILES = YES
#---------------------------------------------------------------------------
# configuration options related to warning and progress messages
#---------------------------------------------------------------------------
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,17 → 133,24
/**
\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.
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).
 
@todo [PEPPE: TB continued]
influences the negotiation procedure (see the \ref core_negotiate
module).
*/
 
64,20 → 157,63
/**
\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,