--- /dev/null
+// -----------------------------------------------------------------------
+// Copyright (C) 2006 - 2007 FRESCOR consortium partners:
+//
+// Universidad de Cantabria, SPAIN
+// University of York, UK
+// Scuola Superiore Sant'Anna, ITALY
+// Kaiserslautern University, GERMANY
+// Univ. Politécnica Valencia, SPAIN
+// Czech Technical University in Prague, CZECH REPUBLIC
+// ENEA SWEDEN
+// Thales Communication S.A. FRANCE
+// Visual Tools S.A. SPAIN
+// Rapita Systems Ltd UK
+// Evidence ITALY
+//
+// See http://www.frescor.org for a link to partners' websites
+//
+// FRESCOR project (FP6/2005/IST/5-034026) is funded
+// in part by the European Union Sixth Framework Programme
+// The European Union is not liable of any use that may be
+// made of this code.
+//
+//
+// based on previous work (FSF) done in the FIRST project
+//
+// Copyright (C) 2005 Mälardalen University, SWEDEN
+// Scuola Superiore S.Anna, ITALY
+// Universidad de Cantabria, SPAIN
+// University of York, UK
+//
+// FSF API web pages: http://marte.unican.es/fsf/docs
+// http://shark.sssup.it/contrib/first/docs/
+//
+// This file is part of FRSH API
+//
+// FRSH API is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2, or (at your option)
+// any later version.
+//
+// FRSH API is distributed in the hope that it will be useful, but
+// WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+// General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// distributed with FRSH API; see file COPYING. If not, write to the
+// Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
+// 02111-1307, USA.
+//
+// As a special exception, if you include this header file into source
+// files to be compiled, this header file does not by itself cause
+// the resulting executable to be covered by the GNU General Public
+// License. This exception does not however invalidate any other
+// reasons why the executable file might be covered by the GNU General
+// Public License.
+// -----------------------------------------------------------------------
+
+//==============================================
+// ******** **** ** **
+// **///// /**/** /** ****
+// ** /**//** /** **//**
+// ******* /** //** /** ** //**
+// **//// /** //**/** **********
+// ** /** //****/**//////**
+// ** /** //***/** /**
+// / // /// // //
+//
+// FNA(Frescor Network Adaptation layer), pronounced "efe ene a"
+//==============================================================
+
+#ifndef _FNA_H_
+#define _FNA_H_
+
+#include "frsh_core_types.h" /* for frsh_resource_id_t, frsh_contract_t, etc */
+#include "fna_error.h" /* for ERROR constants */
+#include <stdint.h> /* for uint32_t, UINT32_MAX */
+
+/**
+ * @defgroup fna FNA Private Interface
+ *
+ * FNA is a Network adaption layer that allows to plugin new
+ * network protocols to the distributed module.
+ *
+ * It is divided in two parts:
+ * - FRSH_FNA: public types and functions for the FRSH API
+ * - FNA: private functions only used within FRSH.
+ *
+ **/
+
+//////////////////////////////////////////////////////////////////////
+// INITIALIZATION
+//////////////////////////////////////////////////////////////////////
+
+/**
+ * @defgroup fnainit FNA Initialization
+ * @ingroup fna
+ *
+ * These functions need to be called before using any network
+ *
+ * @{
+ **/
+
+/**
+ * fna_init()
+ *
+ * This function will be hooked to the frsh_init function and it is
+ * intented to initialize the protocol and its structures.
+ *
+ * @param[in] resource_id The network we are referring to (a protocol
+ * could be able to handle several networks at the same time)
+ *
+ * @return
+ * FNA_NO_ERROR \n
+ * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
+ * FNA_ERR_ALREADY_INITIALIZED:
+ * if the function has already been called before (with success) \n
+ *
+ **/
+int fna_init(const frsh_resource_id_t resource_id);
+
+/*@}*/
+
+///////////////////////////////////////////////////////////////////
+// VIRTUAL RESOURCES
+///////////////////////////////////////////////////////////////////
+
+/**
+ * @defgroup fnavres FNA Virtual Resources
+ * @ingroup fna
+ *
+ * The following functions are used to negotiate, renegotiate and cancel
+ * virtual network resources.
+ *
+ * @{
+ **/
+
+/**
+ * fna_vres_id_t
+ *
+ * Internal virtual resource id. The type fna_vres_id_t is a pointer to void.
+ * The FRSH layer will keep a map between the frsh_vres_id_t, this
+ * pointer and the resource_id. This pointer could be used as the ID
+ * itself using casting, or as internal pointer to any structure.
+ *
+ **/
+typedef void *fna_vres_id_t;
+
+/**
+ * fna_vres_create()
+ *
+ * The operation negotiates a contract and if accepted it will return
+ * a fna_vres_id_t. It will also check that the given contract_id is unique
+ * within the network.
+ *
+ * In object oriented terminology it is similar to a constructor of the
+ * virtual resource class.
+ *
+ * If the on-line admission test is enabled, it determines whether the
+ * contract can be admitted or not based on the current contracts
+ * established in the network. Then it creates the vres and
+ * recalculates all necessary parameters for the contracts already
+ * present in the system.
+ *
+ * This is a potentially blocking operation, it returns when the
+ * system has either rejected the contract, or admitted it and made it
+ * effective.
+ *
+ * @param[in] resource_id The network we are referring to (a protocol
+ * could be able to handle several networks at the same time)
+ * @param[in] contract The contract parameters to negotiate
+ * @param[out] vres The internal virtual resource id
+ *
+ * @return
+ * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FNA_ERR_TOO_MANY_VRES: if there is no space for more vres \n
+ * FNA_ERR_CONTRACT_ID_ALREADY_EXISTS: contract_id is not unique \n
+ * FNA_ERR_CONTRACT_REJECTED: if the contract is not accepted \n
+ * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
+ *
+ **/
+int fna_vres_create
+ (const frsh_resource_id_t resource_id,
+ const frsh_contract_t *contract,
+ fna_vres_id_t *vres);
+
+/**
+ * fna_vres_renegotiate_sync()
+ *
+ * The operation renegotiates a contract for an existing vres. If
+ * the on-line admission test is enabled it determines whether the
+ * contract can be admitted or not based on the current contracts
+ * established in the system. If it cannot be admitted, the old
+ * contract remains in effect and an error is returned. If it can be
+ * admitted, it recalculates all necessary parameters for the
+ * contracts already present in the system and returns zero. This is a
+ * potentially blocking operation; it returns when the system has
+ * either rejected the new contract, or admitted it and made it
+ * effective.
+ *
+ * @param[in] resource_id The network we are referring to (a protocol
+ * could be able to handle several networks at the same time)
+ * @param[in] vres The internal virtual resource id to renegotiate
+ * @param[in] new_contract The new contract
+ *
+ * @return
+ * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
+ * FNA_ERR_CONTRACT_ID_ALREADY_EXISTS: contract_id is not unique \n
+ * FNA_ERR_CONTRACT_REJECTED: if the contract is not accepted \n
+ * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
+ *
+ **/
+int fna_vres_renegotiate_sync
+ (const frsh_resource_id_t resource_id,
+ const fna_vres_id_t vres,
+ const frsh_contract_t *new_contract);
+
+/**
+ * fna_vres_renegotiate_async()
+ *
+ * The operation enqueues a renegotiate operation for an existing
+ * vres, and returns immediately. The renegotiate operation is
+ * performed asynchronously, as soon as it is practical; meanwhile the
+ * system operation will continue normally. When the renegotiation is
+ * made, if the on-line admission test is enabled it determines
+ * whether the contract can be admitted or not based on the current
+ * contracts established in the system. If it cannot be admitted, the
+ * old contract remains in effect. If it can be admitted, it
+ * recalculates all necessary parameters for the contracts already
+ * present in the system.
+ *
+ * When the operation is completed, notification is made to the
+ * caller, if requested, via a signal. The status of the operation (in
+ * progress, admitted, rejected) can be checked with the
+ * frsh_vres_get_renegotiation_status() operation. The argument
+ * sig_notify can be FRSH_NULL_SIGNAL (no notification), or any FRSH
+ * signal value and in this case signal_info is to be sent with the signal.
+ *
+ * @param[in] resource_id The network we are referring to (a protocol
+ * could be able to handle several networks at the same time)
+ * @param[in] vres The internal virtual resource id to renegotiate
+ * @param[in] new_contract The new contract
+ * @param[in] signal_to_notify Signal number to use to notify vres of
+ * the negotiation result. If FRSH_NULL_SIGNAL, no signal will be raised.
+ * @param[in] signal_info: Associated info that will come with the signal.
+ * This parameter will be ignored if signal_to_notify == FRSH_NULL_SIGNAL.
+ *
+ * @return
+ * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
+ * FNA_ERR_CONTRACT_ID_ALREADY_EXISTS: contract_id is not unique \n
+ * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL, or sig_notify is neither
+ * NULL nor a valid POSIX signal \n
+ *
+ **/
+int fna_vres_renegotiate_async
+ (const frsh_resource_id_t resource_id,
+ const fna_vres_id_t vres,
+ const frsh_contract_t *new_contract,
+ frsh_signal_t signal_to_notify,
+ frsh_signal_info_t signal_info);
+
+/**
+ * fna_vres_get_renegotiation_status()
+ *
+ * The operation reports on the status of the last renegotiation
+ * operation enqueued for the specified vres. It is callable even
+ * after notification of the completion of such operation, if
+ * requested.
+ *
+ * If the vres is not and has not been involved in any of the
+ * frsh_contract_renegotiate_async() or frsh_group_change_mode_async()
+ * operations, the status returned is FNA_NOT_REQUESTED
+ *
+ * @param[in] resource_id The network we are referring to (a protocol
+ * could be able to handle several networks at the same time)
+ * @param[in] vres The internal virtual resource id we want the status from
+ * @param[in] renegotiation_status The status of the last renegotiation on
+ * vres (FRSH_RS_IN_PROGRESS, FRSH_RS_REJECTED, FRSH_RS_ADMITTED,
+ * FRSH_RS_NOT_REQUESTED)
+ *
+ * @return
+ * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
+ * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
+ *
+ **/
+int fna_vres_get_renegotiation_status
+ (const frsh_resource_id_t resource_id,
+ const fna_vres_id_t vres,
+ frsh_renegotiation_status_t *renegotiation_status);
+
+/**
+ * fna_vres_destroy()
+ *
+ * The operation eliminates the specified vres
+ * and recalculates all necessary parameters for the contracts
+ * remaining in the system. This is a potentially blocking operation;
+ * it returns when the system has made the changes effective.
+ *
+ * @param[in] resource_id The network we are referring to (a protocol
+ * could be able to handle several networks at the same time)
+ * @param[in] vres The internal virtual resource id to destroy
+ *
+ * @return
+ * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
+ * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
+ *
+ **/
+int fna_vres_destroy
+ (const frsh_resource_id_t resource_id,
+ const fna_vres_id_t vres);
+
+/**
+ * fna_vres_get_contract()
+ *
+ * This operation stores the contract parameters currently associated
+ * with the specified vres in the variable pointed to by
+ * contract. It returns an error if the vres_id is not recognised.
+ *
+ * @param[in] resource_id The network we are referring to (a protocol
+ * could be able to handle several networks at the same time)
+ * @param[in] vres The internal virtual resource id
+ * @param[out] contract The contract parameters that we want
+ *
+ * @return
+ * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
+ * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
+ *
+ **/
+int fna_vres_get_contract
+ (const frsh_resource_id_t resource_id,
+ const fna_vres_id_t vres,
+ frsh_contract_t *contract);
+
+/**
+ * fna_vres_get_usage()
+ *
+ * This function gets the execution time spent by all messages that have been
+ * sent through the specified vres.
+ *
+ * @param[in] resource_id The network we are referring to (a protocol
+ * could be able to handle several networks at the same time)
+ * @param[in] vres The internal virtual resource id
+ * @param[out] usage Execution time spent by this vres
+ *
+ * @return
+ * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
+ * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
+ *
+ **/
+int fna_vres_get_usage
+ (const frsh_resource_id_t resource_id,
+ const fna_vres_id_t vres,
+ struct timespec *usage);
+
+/**
+ * fna_vres_get_remaining_budget()
+ *
+ * This function stores in the variable pointed to by budget the
+ * remaining execution-time budget associated with the specified
+ * vres in the present period.
+ *
+ * @param[in] resource_id The network we are referring to (a protocol
+ * could be able to handle several networks at the same time)
+ * @param[in] vres The internal virtual resource id
+ * @param[out] remaining_budget The remaining budget for this period
+ *
+ * @return
+ * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
+ * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
+ *
+ **/
+int fna_vres_get_remaining_budget
+ (const frsh_resource_id_t resource_id,
+ const fna_vres_id_t vres,
+ struct timespec *remaining_budget);
+
+/**
+ * fna_vres_get_budget_and_period()
+ *
+ * This function gets the budget and period associated with the specified vres
+ * for each period. If one of these pointers is NULL, the corresponding
+ * information is not stored.
+ *
+ * @param[in] resource_id The network we are referring to (a protocol
+ * could be able to handle several networks at the same time)
+ * @param[in] vres The internal virtual resource id
+ * @param[out] budget The budget associated to vres
+ * @param[out] period The period associated to vres
+ *
+ * @return
+ * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
+ * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
+ * FNA_ERR_BAD_ARGUMENT: if both pointers are NULL \n
+ *
+ **/
+int fna_vres_get_budget_and_period
+ (const frsh_resource_id_t resource_id,
+ const fna_vres_id_t vres,
+ struct timespec *budget,
+ struct timespec *period);
+
+/*@}*/
+
+///////////////////////////////////////////////////////////////////
+// SPARE CAPACITY FUNCIONS
+///////////////////////////////////////////////////////////////////
+
+/**
+ * @defgroup fnaspare FNA Spare Capacity
+ * @ingroup fna
+ *
+ * The following functions are used to get spare capacity data
+ *
+ * @{
+ **/
+
+/**
+ * fna_spare_get_capacity()
+ *
+ * This operation gets the spare capacity currently assigned to a importance
+ * level. If we divide this value by UINT32_MAX we will get the network
+ * utilization associated to the spare capacity of a importance level.
+ *
+ * The following is typically in stdint.h: \n
+ * - typedef unsigned int uint32_t; \n
+ * - # define UINT32_MAX (4294967295U) \n
+ *
+ * @param[in] resource_id The network we are referring to (a protocol
+ * could be able to handle several networks at the same time)
+ * @param[in] importance The importance we want the capacity of
+ * @param[out] capacity The spare capacity for that importance level
+ *
+ * @return
+ * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
+ *
+ **/
+int fna_spare_get_capacity
+ (const frsh_resource_id_t resource_id,
+ const int importance,
+ uint32_t *capacity);
+
+/**
+ * fna_spare_get_total_weight()
+ *
+ * This function gets the sum of the weight parameters for all vres in a
+ * network of an importance level.
+ *
+ * @param[in] resource_id The network we are referring to (a protocol
+ * could be able to handle several networks at the same time)
+ * @param[in] importance The importance we want the total weight of
+ * @param[out] total_weight The total weight for that importance level
+ *
+ * @return
+ * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
+ *
+ **/
+int fna_spare_get_total_weight
+ (const frsh_resource_id_t resource_id,
+ const int importance,
+ int *total_weight);
+
+/**
+ * fna_spare_release_capacity()
+ *
+ * This function allows to ask for less budget and period than what we
+ * received. The request must be compatible with the rest of contract
+ * parameters of the vres. If we want to recover the released capacity
+ * we will need to renegotiate.
+ *
+ * @param[in] resource_id The network we are referring to (a protocol
+ * could be able to handle several networks at the same time)
+ * @param[in] vres The internal virtual resource id
+ * @param[in] new_budget The new_budget
+ * @param[in] new_period The new Period
+ *
+ * @return
+ * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
+ * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
+ * FNA_ERR_CONTRACT_REJECTED: if it is incompatible with the current
+ * contract \n
+ *
+ **/
+int fna_spare_release_capacity
+ (const frsh_resource_id_t resource_id,
+ const fna_vres_id_t vres,
+ const struct timespec new_budget,
+ const struct timespec new_period);
+
+/*@}*/
+
+///////////////////////////////////////////////////////////////////
+// SEND RECEIVE OPERATIONS
+///////////////////////////////////////////////////////////////////
+
+/**
+ * @defgroup fnasendrecv FNA Send and Receive
+ * @ingroup fna
+ *
+ * The following functions are used to send and receive
+ *
+ * @{
+ **/
+
+/**
+ * fna_send_sync()
+ *
+ * Similar to previous function but now the sending thread gets blocked
+ * until the message is already sent to the network.
+ *
+ * @param[in] endpoint The send endpoint we are sending through. It must
+ * be bound to a virtual resource (resource_id is in the endpoint).
+ * @param[in] msg The message we want to send
+ * @param[in] size The size in bytes of the message
+ *
+ * @returns
+ * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FNA_ERR_NOT_BOUND: if endpoint is not bound to a valid vres \n
+ * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
+ * FNA_ERR_TOO_LARGE: if the message is too large for the network protocol \n
+ * FNA_ERR_BUFFER_FULL: if the message has been discarded because
+ * the queue is full (and does not have the policy FNA_QP_OLDEST) \n
+ *
+ **/
+int fna_send_sync
+ (const frsh_send_endpoint_t *endpoint,
+ const void *msg,
+ const size_t size);
+
+/**
+ * fna_send_async()
+ *
+ * This operation sends a message stored in msg and of length size
+ * through the given send endpoint. The operation is non-blocking and
+ * returns immediately.
+ *
+ * @param[in] endpoint The send endpoint we are sending through. It must
+ * be bound to a virtual resource (resource_id is in the endpoint).
+ * @param[in] msg The message we want to send
+ * @param[in] size The size in bytes of the message
+ *
+ * @returns
+ * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FNA_ERR_NOT_BOUND: if endpoint is not bound to a valid vres \n
+ * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
+ * FNA_ERR_TOO_LARGE: if the message is too large for the network protocol \n
+ * FNA_ERR_BUFFER_FULL: if the message has been discarded because
+ * the queue is full (and does not have the policy FNA_QP_OLDEST) \n
+ *
+ **/
+int fna_send_async
+ (const frsh_send_endpoint_t *endpoint,
+ const void *msg,
+ const size_t size);
+
+/**
+ * fna_receive_sync()
+ *
+ * This operation is used to receive messages from the network with a
+ * blocking behavior (if there are no messages this operation blocks
+ * the calling thread).
+ *
+ * When a message is available, it is copied to buffer (up to its size).
+ * The number of bytes copied is returned in received_bytes. The rest
+ * of the bytes of that message will be lost or not depending on the
+ * protocol (FNA_ERR_NO_SPACE will be returned if it is).
+ *
+ * The function fails with FNA_ERR_NO_SPACE if the buffersize is
+ * too small for the message received. In this case the message is
+ * lost.
+ *
+ * Messages arriving at a receiver buffer that is full will be handled
+ * according to the queueing policy of the endpoint (overwrite oldest,
+ * discard it,etc).
+ *
+ * @param[in] endpoint The receive endpoint we are receiving from.
+ * (resource_id is in the endpoint).
+ * @param[out] buffer Buffer for storing the received message
+ * @param[in] buffer_size The size in bytes of this buffer
+ * @param[out] received_bytes The actual number of received bytes
+ *
+ * @return
+ * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
+ * FNA_ERR_NO_SPACE: if the message size is bigger than the
+ * provided buffer. \n
+ *
+ **/
+int fna_receive_sync
+ (const frsh_receive_endpoint_t *endpoint,
+ void *buffer,
+ const size_t buffer_size,
+ size_t *received_bytes);
+
+/**
+ * fna_receive_async()
+ *
+ * This operation is similar to the previous one but it works in a non
+ * blocking (asynchronous) fashion. If no message is available it
+ * returns with error FNA_NO_MESSAGE.
+ *
+ * @param[in] endpoint The receive endpoint we are receiving from.
+ * (resource_id is in the endpoint).
+ * @param[out] buffer Buffer for storing the received message
+ * @param[in] buffer_size The size in bytes of this buffer
+ * @param[out] received_bytes The actual number of received bytes
+ *
+ * @return
+ * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
+ * FNA_ERR_NO_SPACE: if the message size is bigger than the
+ * provided buffer. \n
+ * FNA_NO_MESSAGE: if no messages are available in the queue. \n
+ *
+ **/
+int fna_receive_async
+ (const frsh_receive_endpoint_t *endpoint,
+ void *buffer,
+ const size_t buffer_size,
+ size_t *received_bytes);
+
+/**
+ * fna_send_endpoint_get_pending_messages()
+ *
+ * This function tells the number of messages still pending
+ *
+ * @param[in] endpoint The send endpoint (resource_id is in the endpoint).
+ * @param[out] number_of_pending_messages The number of pending messages
+ *
+ * @return
+ * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
+ *
+ **/
+int fna_send_endpoint_get_pending_messages
+ (const frsh_send_endpoint_t *endpoint,
+ int *number_of_pending_messages);
+
+/**
+ * fna_receive_endpoint_get_pending_messages
+ *
+ * This function tells the number of messages still pending in the
+ * receive endpoint queue
+ *
+ * @param[in] endpoint The receive endpoint (resource_id is in the endpoint).
+ * @param[out] number_of_pending_messages The number of pending messages
+ *
+ * @return
+ * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
+ *
+ **/
+int fna_receive_endpoint_get_pending_messages
+ (const frsh_receive_endpoint_t *endpoint,
+ int *number_of_pending_messages);
+
+/*@}*/
+
+//////////////////////////////////////////////////////////////////////
+// NETWORK CONFIGURATION FUNCTIONS
+//////////////////////////////////////////////////////////////////////
+
+/**
+ * @defgroup frshfnaconfig FNA Network Configuration
+ * @ingroup fna
+ *
+ * These functions are needed to set/get some network dependent values
+ *
+ * @{
+ **/
+
+/**
+ * fna_message_get_tx_time()
+ *
+ * This operation gives the worst case transmission time that it takes to
+ * send a message of the nbytes size through the network designated by
+ * resource_id, including any network overheads (fragmentation in packets,
+ * headers, retransmissions,...).
+ *
+ * It is be used by the application to calculate the minimum and
+ * maximum budgets used in the preparation of network contracts.
+ *
+ * @param[in] resource_id The network we want the tx time from.
+ * @param[in] nbytes Number of bytes of the message
+ * @param[out] tx_time The transmission time for nbytes (including overheads)
+ *
+ * @return
+ * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL or nbytes is bigger than
+ * the maximum message size \n
+ *
+ **/
+int fna_message_get_tx_time
+ (const frsh_resource_id_t resource_id,
+ const size_t nbytes,
+ struct timespec *tx_time);
+
+/**
+ * fna_message_get_max_size()
+ *
+ * This operation gives the maximum number of bytes that can be sent
+ * in a single message through the network designated by resource_id.
+ * If the application needs to send bigger messages it will have to
+ * split them. Some protocols like TCP/IP are capable of sending large
+ * messages (and use fragmentation internally) but other protocols doesn't
+ * provide fragmentation features so the maximum size will be the MTU itself.
+ *
+ * It is be used by the application to calculate the minimum and
+ * maximum budgets used in the preparation of network contracts.
+ *
+ * @param[in] resource_id The network we want the tx time from.
+ * @param[out] max_size The maximum number of bytes for each message
+ *
+ * @return
+ * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL or nbytes is bigger than
+ * the maximum message size \n
+ *
+ **/
+int fna_message_get_max_size
+ (const frsh_resource_id_t *resource_id,
+ size_t *max_size);
+
+/*@}*/
+
+#endif // _FNA_H_
+
--- /dev/null
+// -----------------------------------------------------------------------
+// Copyright (C) 2006 - 2007 FRESCOR consortium partners:
+//
+// Universidad de Cantabria, SPAIN
+// University of York, UK
+// Scuola Superiore Sant'Anna, ITALY
+// Kaiserslautern University, GERMANY
+// Univ. Politécnica Valencia, SPAIN
+// Czech Technical University in Prague, CZECH REPUBLIC
+// ENEA SWEDEN
+// Thales Communication S.A. FRANCE
+// Visual Tools S.A. SPAIN
+// Rapita Systems Ltd UK
+// Evidence ITALY
+//
+// See http://www.frescor.org for a link to partners' websites
+//
+// FRESCOR project (FP6/2005/IST/5-034026) is funded
+// in part by the European Union Sixth Framework Programme
+// The European Union is not liable of any use that may be
+// made of this code.
+//
+//
+// based on previous work (FSF) done in the FIRST project
+//
+// Copyright (C) 2005 Mälardalen University, SWEDEN
+// Scuola Superiore S.Anna, ITALY
+// Universidad de Cantabria, SPAIN
+// University of York, UK
+//
+// FSF API web pages: http://marte.unican.es/fsf/docs
+// http://shark.sssup.it/contrib/first/docs/
+//
+// This file is part of FRSH API
+//
+// FRSH API is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2, or (at your option)
+// any later version.
+//
+// FRSH API is distributed in the hope that it will be useful, but
+// WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+// General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// distributed with FRSH API; see file COPYING. If not, write to the
+// Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
+// 02111-1307, USA.
+//
+// As a special exception, if you include this header file into source
+// files to be compiled, this header file does not by itself cause
+// the resulting executable to be covered by the GNU General Public
+// License. This exception does not however invalidate any other
+// reasons why the executable file might be covered by the GNU General
+// Public License.
+// -----------------------------------------------------------------------
+
+//==============================================
+// ******** **** ** **
+// **///// /**/** /** ****
+// ** /**//** /** **//**
+// ******* /** //** /** ** //**
+// **//// /** //**/** **********
+// ** /** //****/**//////**
+// ** /** //***/** /**
+// / // /// // //
+//
+// FNA(Frescor Network Adaptation layer), pronounced "efe ene a"
+//==============================================================
+
+#ifndef _FRSH_FNA_H_
+#define _FRSH_FNA_H_
+
+#define RTEP
+
+/**
+ * @defgroup frshfna FNA Public Interface
+ *
+ * FNA is a Network adaption layer that allows to plugin new
+ * network protocols to the distributed module.
+ *
+ * It is divided in two parts:
+ * - FRSH_FNA: public types and functions for the FRSH API
+ * - FNA: private functions only used within FRSH.
+ *
+ **/
+
+//////////////////////////////////////////////////////////////////////
+// MAPPING FUNCTIONS
+//////////////////////////////////////////////////////////////////////
+
+/**
+ * @defgroup frshfnamap FNA Mapping Functions
+ * @ingroup frshfna
+ *
+ * These functions are needed to map network specific types to FRSH types.
+ * Instead of providing this mapping functions a static hardwired configuration
+ * could be used.
+ *
+ * @{
+ **/
+
+/**
+ * frsh_XXXX_map_network_address()
+ *
+ * To map a XXXX protocol network address into a FRSH address.
+ * The protocol must keep this mapping consistent. Instead of using a function
+ * a hardwired mapping could be used.
+ *
+ * @param[in] resource_id The network we are referring to (a protocol
+ * could be able to handle several networks at the same time)
+ * @param[in] in_address The network address we want to map to a frsh address
+ * @param[out] out_address The FRSH abstract network address
+ *
+ * @return
+ * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
+ *
+ **/
+#ifdef RTEP
+int frsh_rtep_map_network_address
+ (const frsh_resource_id_t resource_id,
+ const rtep_network_address_t *in_address,
+ frsh_network_address_t *out_address);
+#elif OTHER
+ ...
+#endif
+
+/**
+ * frsh_XXXX_map_stream_id()
+ *
+ * To map a XXXX protocol network stream, port, channel... into a FRSH stream.
+ * The protocol must keep this mapping consistent. Instead of using a function
+ * a hardwired mapping could be used.
+ *
+ * @param[in] resource_id The network we are referring to (a protocol
+ * could be able to handle several networks at the same time)
+ * @param[in] in_stream The network stream we want to map to a FRSH stream
+ * @param[out] out_stream The FRSH abstract network stream
+ *
+ * @return
+ * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
+ *
+ **/
+#ifdef RTEP
+int frsh_rtep_map_stream_id
+ (const frsh_resource_id_t resource_id,
+ const rtep_channel_t *in_stream,
+ frsh_stream_id_t *out_stream);
+#elif OTHER
+ ...
+#endif
+
+/*@}*/
+
+///////////////////////////////////////////////////////////////////
+// NEGOTIATION SERVICE PARAMETERS
+///////////////////////////////////////////////////////////////////
+/**
+ * @defgroup frshfnaserv FNA Negotiation Service Parameters
+ * @ingroup frshfna
+ *
+ * These functions are needed to set/get the negotiation service parameters.
+ *
+ * @{
+ **/
+
+/**
+ * frsh_XXXX_negotiation_messages__vres_renegotiate()
+ *
+ * This function allows the application to change the minimum period
+ * of the negotiation messages sent through the network. It is similar
+ * to the service thread but for the network messages. We do not provide
+ * budget here because the size of the negotiation messages is fixed.
+ *
+ * This change is similar to a renegotiation so a schedulability test
+ * must be done to see if the change can be accepted or not.
+ *
+ * @param[in] resource_id The network we are referring to (a protocol
+ * could be able to handle several networks at the same time)
+ * @param[in] period The new period for negotiation messages
+ * @param[out] accepted If the change has been accepted or not
+ *
+ * @return
+ * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
+ *
+ **/
+#ifdef RTEP
+int frsh_rtep_negotiation_messages_vres_renegotiate
+ (const frsh_resource_id_t resource_id,
+ const struct timespec *period,
+ bool *accepted);
+#elif OTHER
+ ...
+#endif
+
+/**
+ * frsh_XXXX_negotiation_messages_vres_get_period()
+ *
+ * This function gets the minimum period of the negotiation messages
+ * sent through the network.
+ *
+ * @param[in] resource_id The network we are referring to (a protocol
+ * could be able to handle several networks at the same time)
+ * @param[out] period The period for negotiation messages
+ *
+ * @return
+ * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
+ *
+ **/
+#ifdef RTEP
+int frsh_rtep_negotiation_messages_vres_get_period
+ (const frsh_resource_id_t resource_id,
+ struct timespec *period);
+#elif OTHER
+ ...
+#endif
+
+/**
+ * frsh_XXXX_service_thread_vres_renegotiate()
+ *
+ * This function allows the application to change the period and
+ * budget of the service thread that makes the negotiations and
+ * schedulability tests in a network.
+ *
+ * The service thread starts with a default budget and period that
+ * should be configurable
+ *
+ * @param[in] resource_id The network we are referring to (a protocol
+ * could be able to handle several networks at the same time)
+ * @param[in] budget The new budget for the service thread
+ * @param[in] period The new period for the service thread
+ * @param[out] accepted If the negotiation has been accepted or not
+ *
+ * @return
+ * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
+ *
+ **/
+#ifdef RTEP
+int frsh_rtep_service_thread_vres_renegotiate
+ (const frsh_resource_id_t resource_id,
+ const struct timespec *budget,
+ const struct timespec *period,
+ bool *accepted);
+#elif OTHER
+ ...
+#endif
+
+/**
+ * frsh_XXXX_service_thread_vres_get_budget_and_period()
+ *
+ * This function gets the budget and period of a service thread.
+ *
+ * @param[in] resource_id The network we are referring to (a protocol
+ * could be able to handle several networks at the same time)
+ * @param[out] budget The budget of the service thread
+ * @param[out] period The period of the service thread
+ *
+ * @return
+ * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
+ *
+ **/
+#ifdef RTEP
+int frsh_rtep_service_thread_vres_get_budget_and_period
+ (const frsh_resource_id_t resource_id,
+ struct timespec *budget,
+ struct timespec *period);
+#elif OTHER
+ ...
+#endif
+
+/*@}*/
+
+#endif /* _FRSH_FNA_H_ */
projects / frescor / fna.git / commitdiff