include/frsh_fna.h

   1 //----------------------------------------------------------------------
   2 //  Copyright (C) 2006 - 2009 by the FRESCOR consortium:
   3 //
   4 //    Universidad de Cantabria,              SPAIN
   5 //    University of York,                    UK
   6 //    Scuola Superiore Sant'Anna,            ITALY
   7 //    Kaiserslautern University,             GERMANY
   8 //    Univ. Politecnica  Valencia,           SPAIN
   9 //    Czech Technical University in Prague,  CZECH REPUBLIC
  10 //    ENEA                                   SWEDEN
  11 //    Thales Communication S.A.              FRANCE
  12 //    Visual Tools S.A.                      SPAIN
  13 //    Rapita Systems Ltd                     UK
  14 //    Evidence                               ITALY
  15 //
  16 //    See http://www.frescor.org
  17 //
  18 //        The FRESCOR project (FP6/2005/IST/5-034026) is funded
  19 //        in part by the European Union Sixth Framework Programme
  20 //        The European Union is not liable of any use that may be
  21 //        made of this code.
  22 //
  23 //
  24 //  based on previous work (FSF) done in the FIRST project
  25 //
  26 //   Copyright (C) 2005  Mälardalen University, SWEDEN
  27 //                       Scuola Superiore S.Anna, ITALY
  28 //                       Universidad de Cantabria, SPAIN
  29 //                       University of York, UK
  30 //
  31 // This file is part of FNA (Frescor Network Adaptation)
  32 //
  33 // FNA is free software; you can redistribute it and/or modify it
  34 // under terms of the GNU General Public License as published by the
  35 // Free Software Foundation; either version 2, or (at your option) any
  36 // later version.  FNA is distributed in the hope that it will be
  37 // useful, but WITHOUT ANY WARRANTY; without even the implied warranty
  38 // of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  39 // General Public License for more details. You should have received a
  40 // copy of the GNU General Public License along with FNA; see file
  41 // COPYING. If not, write to the Free Software Foundation, 675 Mass Ave,
  42 // Cambridge, MA 02139, USA.
  43 //
  44 // As a special exception, including FNA header files in a file,
  45 // instantiating FNA generics or templates, or linking other files
  46 // with FNA objects to produce an executable application, does not
  47 // by itself cause the resulting executable application to be covered
  48 // by the GNU General Public License. This exception does not
  49 // however invalidate any other reasons why the executable file might be
  50 // covered by the GNU Public License.
  51 // -----------------------------------------------------------------------
  52
  53 //==============================================
  54 //  ******** ****     **     **
  55 //  **///// /**/**   /**    ****
  56 //  **      /**//**  /**   **//**
  57 //  ******* /** //** /**  **  //**
  58 //  **////  /**  //**/** **********
  59 //  **      /**   //****/**//////**
  60 //  **      /**    //***/**     /**
  61 //  /       //      /// //      //
  62 //
  63 // FNA(Frescor Network Adaptation layer), pronounced "efe ene a"
  64 //==============================================================
  65
  66 #ifndef _FRSH_FNA_H_
  67 #define _FRSH_FNA_H_
  68
  69 #include "frsh.h" /* for frsh_resource_id_t, network_address_t, stream_id_t*/
  70 #include <time.h> /* for timespec */
  71 #include <stdbool.h> /* for bool */
  72 #include "fna_configuration.h"
  73
  74 #ifdef RTEP_FNA_ENABLED
  75    #include "rtep.h"
  76 #endif
  77
  78 #ifdef FRESCAN_FNA_ENABLED
  79    #include "../src_frescan/frescan.h"
  80 #endif
  81
  82 /**
  83  * @defgroup frshfna FNA Public Interface
  84  *
  85  * FNA is a Network adaption layer that allows to plugin new
  86  * network protocols to the distributed module.
  87  *
  88  * It is divided in two parts:
  89  *  - FRSH_FNA: public types and functions for the FRSH API
  90  *  - FNA: private functions only used within FRSH.
  91  *
  92  **/
  93
  94 ////////////////////////////////////////////////////////////////////
  95 //          MAPPING FUNCTIONS
  96 ////////////////////////////////////////////////////////////////////
  97
  98 /**
  99  * @defgroup frshfnamap FNA Mapping Functions
 100  * @ingroup frshfna
 101  *
 102  * These functions are needed to map network specific types to FRSH types.
 103  * Instead of providing this mapping functions a static hardwired configuration
 104  * could be used.
 105  *
 106  * @{
 107  **/
 108
 109 /**
 110  * frsh_XXXX_map_network_address()
 111  *
 112  * To map a XXXX protocol network address into a FRSH address.
 113  * The protocol must keep this mapping consistent. Instead of using a function
 114  * a hardwired mapping could be used.
 115  *
 116  * @param[in] resource_id The network we are referring to (a protocol
 117  * could be able to handle several networks at the same time)
 118  * @param[in] in_address The network address we want to map to a frsh address
 119  * @param[out] out_address The FRSH abstract network address
 120  *
 121  * @return
 122  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 123  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 124  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 125  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 126  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 127  *
 128  **/
 129 #ifdef RTEP_FNA_ENABLED
 130 int frsh_rtep_map_network_address(const frsh_resource_id_t resource_id,
 131                                   const rtep_station_id_t in_address,
 132                                   frsh_network_address_t *out_address);
 133 #endif
 134
 135 #ifdef FRESCAN_FNA_ENABLED
 136 int frsh_frescan_map_network_address(const frsh_resource_id_t resource_id,
 137                                      const frescan_node_t in_address,
 138                                      frsh_network_address_t *out_address);
 139 #endif
 140
 141 /**
 142  * frsh_XXXX_map_stream_id()
 143  *
 144  * To map a XXXX protocol network stream, port, channel... into a FRSH stream.
 145  * The protocol must keep this mapping consistent. Instead of using a function
 146  * a hardwired mapping could be used.
 147  *
 148  * @param[in] resource_id The network we are referring to (a protocol
 149  * could be able to handle several networks at the same time)
 150  * @param[in] in_stream The network stream we want to map to a FRSH stream
 151  * @param[out] out_stream The FRSH abstract network stream
 152  *
 153  * @return
 154  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 155  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 156  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 157  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 158  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 159  *
 160  **/
 161 #ifdef RTEP_FNA_ENABLED
 162 int frsh_rtep_map_stream_id(const frsh_resource_id_t resource_id,
 163                             const rtep_channel_t in_stream,
 164                             frsh_stream_id_t *out_stream);
 165 #endif
 166
 167 #ifdef FRESCAN_FNA_ENABLED
 168 int frsh_frescan_map_stream_id(const frsh_resource_id_t resource_id,
 169                                const frescan_channel_t in_stream,
 170                                frsh_stream_id_t *out_stream);
 171 #endif
 172
 173 /*@}*/
 174
 175 ///////////////////////////////////////////////////////////////////
 176 //           NEGOTIATION SERVICE PARAMETERS
 177 ///////////////////////////////////////////////////////////////////
 178 /**
 179  * @defgroup frshfnaserv FNA Negotiation Service Parameters
 180  * @ingroup frshfna
 181  *
 182  * These functions are needed to set/get the negotiation service parameters.
 183  *
 184  * @{
 185  **/
 186
 187 /**
 188  * frsh_XXXX_negotiation_messages__vres_renegotiate()
 189  *
 190  * This function allows the application to change the minimum period
 191  * of the negotiation messages sent through the network. It is similar
 192  * to the service thread but for the network messages. We do not provide
 193  * budget here because the size of the negotiation messages is fixed.
 194  *
 195  * This change is similar to a renegotiation so a schedulability test
 196  * must be done to see if the change can be accepted or not.
 197  *
 198  * @param[in] resource_id The network we are referring to (a protocol
 199  * could be able to handle several networks at the same time)
 200  * @param[in] period The new period for negotiation messages
 201  * @param[out] accepted If the change has been accepted or not
 202  *
 203  * @return
 204  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 205  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 206  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 207  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 208  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 209  *   FNA_ERR_REJECTED_CONTRACT : if the renegotiation fails \n
 210  *
 211  **/
 212 #ifdef RTEP_FNA_ENABLED
 213 int frsh_rtep_negotiation_messages_vres_renegotiate
 214       (const frsh_resource_id_t resource_id,
 215        const struct timespec *period);
 216 #endif
 217
 218 #ifdef FRESCAN_FNA_ENABLED
 219 int frsh_frescan_negotiation_messages_vres_renegotiate
 220       (const frsh_resource_id_t resource_id,
 221        const struct timespec *period);
 222 #endif
 223
 224 /**
 225  * frsh_XXXX_negotiation_messages_vres_get_period()
 226  *
 227  * This function gets the minimum period of the negotiation messages
 228  * sent through the network.
 229  *
 230  * @param[in] resource_id The network we are referring to (a protocol
 231  * could be able to handle several networks at the same time)
 232  * @param[out] period The period for negotiation messages
 233  *
 234  * @return
 235  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 236  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 237  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 238  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 239  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 240  *
 241  **/
 242 #ifdef RTEP_FNA_ENABLED
 243 int frsh_rtep_negotiation_messages_vres_get_period
 244       (const frsh_resource_id_t resource_id,
 245        struct timespec *period);
 246 #endif
 247
 248 #ifdef FRESCAN_FNA_ENABLED
 249 int frsh_frescan_negotiation_messages_vres_get_period
 250       (const frsh_resource_id_t resource_id,
 251        struct timespec *period);
 252 #endif
 253
 254 /**
 255  * frsh_XXXX_service_thread_vres_renegotiate()
 256  *
 257  * This function allows the application to change the period and
 258  * budget of the service thread that makes the negotiations and
 259  * schedulability tests in a network.
 260  *
 261  * The service thread starts with a default budget and period that
 262  * should be configurable
 263  *
 264  * @param[in] resource_id The network we are referring to (a protocol
 265  * could be able to handle several networks at the same time)
 266  * @param[in] budget The new budget for the service thread
 267  * @param[in] period The new period for the service thread
 268  * @param[out] accepted If the negotiation has been accepted or not
 269  *
 270  * @return
 271  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 272  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 273  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 274  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 275  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 276  *
 277  **/
 278 #ifdef RTEP_FNA_ENABLED
 279 int frsh_rtep_service_thread_vres_renegotiate
 280    (const frsh_resource_id_t resource_id,
 281     const struct timespec *budget,
 282     const struct timespec *period,
 283     bool *accepted);
 284 #endif
 285
 286 #ifdef FRESCAN_FNA_ENABLED
 287 int frsh_frescan_service_thread_vres_renegotiate
 288    (const frsh_resource_id_t resource_id,
 289     const struct timespec *budget,
 290     const struct timespec *period,
 291     bool *accepted);
 292 #endif
 293
 294 /**
 295  * frsh_XXXX_service_thread_vres_get_budget_and_period()
 296  *
 297  * This function gets the budget and period of a service thread.
 298  *
 299  * @param[in] resource_id The network we are referring to (a protocol
 300  * could be able to handle several networks at the same time)
 301  * @param[out] budget The budget of the service thread
 302  * @param[out] period The period of the service thread
 303  *
 304  * @return
 305  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 306  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 307  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 308  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 309  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 310  *
 311  **/
 312 #ifdef RTEP_FNA_ENABLED
 313 int frsh_rtep_service_thread_vres_get_budget_and_period
 314       (const frsh_resource_id_t resource_id,
 315        struct timespec *budget,
 316        struct timespec *period);
 317 #endif
 318
 319 #ifdef FRESCAN_FNA_ENABLED
 320 int frsh_frescan_service_thread_vres_get_budget_and_period
 321       (const frsh_resource_id_t resource_id,
 322        struct timespec *budget,
 323        struct timespec *period);
 324 #endif
 325
 326 /*@}*/
 327
 328 #endif /* _FRSH_FNA_H_ */