include/fna.h

   1 //----------------------------------------------------------------------
   2 //  Copyright (C) 2006 - 2007 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 _FNA_H_
  67 #define _FNA_H_
  68
  69 /* for frsh_resource_id_t, frsh_contract_t, for frsh_network_address_t,
  70    frsh_stream_id_t, ... */
  71 #include "frsh.h"
  72 /* for timespec */
  73 #include <time.h>
  74 /* for ERROR constants */
  75 // #include "fna_error.h"
  76 /* for uint32_t, UINT32_MAX */
  77 #include <stdint.h>
  78
  79 /**
  80  * @defgroup fna FNA Private Interface
  81  *
  82  * FNA is a Network adaption layer that allows to plugin new
  83  * network protocols to the distributed module.
  84  *
  85  * It is divided in two parts:
  86  *  - FRSH_FNA:  public types and functions for the FRSH API
  87  *  - FNA: private functions only used within FRSH.
  88  *
  89  **/
  90
  91
  92 //////////////////////////////////////////////////////////////////////
  93 //           INITIALIZATION
  94 //////////////////////////////////////////////////////////////////////
  95
  96 /**
  97  * @defgroup fnainit FNA Initialization
  98  * @ingroup fna
  99  *
 100  * These functions need to be called before using any network
 101  *
 102  * @{
 103  **/
 104
 105 /**
 106  * fna_init()
 107  *
 108  * This function will be hooked to the frsh_init function and it is
 109  * intented to initialize the protocol and its structures.
 110  *
 111  * @param[in]  resource_id The network we are referring to (a protocol
 112  * could be able to handle several networks at the same time)
 113  *
 114  * @return
 115  *   0 if there are no errors \n
 116  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 117  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 118  *   FNA_ERR_ALREADY_INITIALIZED:
 119  *      if the function has already been called before (with success) \n
 120  *
 121  **/
 122 typedef int fna_init_t(const frsh_resource_id_t resource_id);
 123
 124 /*@}*/
 125
 126 ///////////////////////////////////////////////////////////////////
 127 //           VIRTUAL RESOURCES
 128 ///////////////////////////////////////////////////////////////////
 129
 130 /**
 131  * @defgroup fnavres FNA Virtual Resources
 132  * @ingroup fna
 133  *
 134  * The following functions are used to negotiate, renegotiate and cancel
 135  * virtual network resources.
 136  *
 137  * @{
 138  **/
 139
 140 #ifndef FRSH_FORB
 141 /**
 142  * fna_vres_id_t
 143  *
 144  * Internal virtual resource id. In the current implementation it is a 16 bits
 145  * value (up to 65536 vres) so it can be integrated easily with the
 146  * frsh_vres_id_t type (see frsh_internal_data.h)
 147  *
 148  **/
 149 typedef uint16_t fna_vres_id_t;
 150 #else
 151 /**
 152  * In FRSH_FORB implementation, we do not distinguish between vreses
 153  * of different resources.
 154  */
 155 typedef frsh_vres_id_t fna_vres_id_t;
 156 #endif
 157
 158 typedef  struct {
 159         int            size;
 160         fna_vres_id_t  vres[FRSH_MAX_GROUP_OPS];
 161 } fna_vres_group_t;
 162
 163 /**
 164  * frsh_group_change_mode_sync()
 165  *
 166  * This function performs a set of negotiation operations which can
 167  * include: adding new contracts (neg), modifying existing vres (reneg)
 168  * or cancelling existing vres (cancel).
 169  *
 170  * If one of the group operations has a NULL value, unless it causes an
 171  * inconsistency the system will suppose that no operation of that
 172  * type (neg, reneg or cancel) should be done.
 173  *
 174  * The virtual resources resulting from negotiations of new contracts are
 175  * returned in the parameter 'new_vres' which must be provided by the user.
 176  *
 177  * If the on-line admission test is enabled, FRSH analizes the
 178  * schedulability of the context that would  result in the new
 179  * contract situation with removed, changed and added contracts.
 180  *
 181  * A successful return code will mean that all contracts have been
 182  * accepted  and all required operations (creation, cancellation or
 183  * update of vres) have been carried out to reach the new running
 184  * context.
 185  *
 186  * If any of the contracts is not accepted a corresponding error shall be
 187  * returned and no changes will be made to the previously running context.
 188  *
 189  * This call is a synchronous, potentially blocking operation.  It
 190  * returns when the system has rejected the contracts or accepted
 191  * and made them effective.
 192  *
 193  * @param[in] contracts_to_neg    List of new contracts to negotiate
 194  * @param[in] contracts_to_reneg  List of contracts to renegotiate
 195  * @param[in] vres_to_reneg       List of vres to renegotiate
 196  * @param[in] vres_to_cancel      List of vres to cancel
 197  * @param[out] new_vres           List of vres of new contracts.
 198  *
 199  * @return 0 if no error \n
 200  *   0 if there are no errors (in this case it also means contract accepted) \n
 201  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 202  *   FNA_ERR_TOO_MANY_VRES: if there is no space for more vres \n
 203  *   FNA_ERR_CONTRACT_ID_ALREADY_EXISTS: contract_id is not unique \n
 204  *   FNA_ERR_CONTRACT_REJECTED: if the contract is not accepted \n
 205  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 206  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 207  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 208  *
 209  **/
 210 typedef int fna_group_change_mode_sync_t
 211                 (const frsh_resource_id_t     resource_id,
 212                  const frsh_contracts_group_t *contracts_to_neg,
 213                  const frsh_contracts_group_t *contracts_to_reneg,
 214                  const fna_vres_group_t       *vres_to_reneg,
 215                  const fna_vres_group_t       *vres_to_cancel,
 216                  fna_vres_group_t             *new_vres);
 217
 218 /**
 219  * fna_contract_negotiate()
 220  *
 221  * The operation negotiates a contract and if accepted it will return
 222  * a fna_vres_id_t. It will also check that the given contract_id is unique
 223  * within the network.
 224  *
 225  * If the on-line admission test is enabled, it determines whether the
 226  * contract can be admitted or not based on the current contracts
 227  * established in the network. Then it creates the vres and
 228  * recalculates all necessary parameters for the contracts already
 229  * present in the system.
 230  *
 231  * This is a potentially blocking operation, it returns when the
 232  * system has either rejected the contract, or admitted it and made it
 233  * effective.
 234  *
 235  * @param[in] resource_id The network we are referring to (a protocol
 236  * could be able to handle several networks at the same time)
 237  * @param[in] contract  The contract parameters to negotiate
 238  * @param[out] vres The internal virtual resource id
 239  *
 240  * @return
 241  *   0 if there are no errors (in this case it also means contract accepted) \n
 242  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 243  *   FNA_ERR_TOO_MANY_VRES: if there is no space for more vres \n
 244  *   FNA_ERR_CONTRACT_ID_ALREADY_EXISTS: contract_id is not unique \n
 245  *   FNA_ERR_CONTRACT_REJECTED: if the contract is not accepted \n
 246  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 247  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 248  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 249  *
 250  **/
 251 typedef int fna_contract_negotiate_t
 252    (const frsh_resource_id_t resource_id,
 253     const frsh_contract_t *contract,
 254     fna_vres_id_t *vres);
 255
 256 /**
 257  * fna_contract_renegotiate_sync()
 258  *
 259  * The operation renegotiates a contract for an existing vres. If
 260  * the on-line admission test is enabled it determines whether the
 261  * contract can be admitted or not based on the current contracts
 262  * established in the system. If it cannot be admitted, the old
 263  * contract remains in effect and an error is returned. If it can be
 264  * admitted, it recalculates all necessary parameters for the
 265  * contracts already present in the system and returns zero. This is a
 266  * potentially blocking operation; it returns when the system has
 267  * either rejected the new contract, or admitted it and made it
 268  * effective.
 269  *
 270  * @param[in] resource_id The network we are referring to (a protocol
 271  * could be able to handle several networks at the same time)
 272  * @param[in] vres The internal virtual resource id to renegotiate
 273  * @param[in] new_contract The new contract
 274  *
 275  *  @return
 276  *   0 if there are no errors (in this case it also means contract accepted) \n
 277  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 278  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 279  *   FNA_ERR_CONTRACT_ID_ALREADY_EXISTS: contract_id is not unique \n
 280  *   FNA_ERR_CONTRACT_REJECTED: if the contract is not accepted \n
 281  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 282  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 283  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 284  *
 285  **/
 286 typedef int fna_contract_renegotiate_sync_t
 287    (const frsh_resource_id_t resource_id,
 288     const fna_vres_id_t vres,
 289     const frsh_contract_t *new_contract);
 290
 291 /**
 292  * fna_contract_renegotiate_async()
 293  *
 294  * The operation enqueues a renegotiate operation for an existing
 295  * vres, and returns immediately. The renegotiate operation is
 296  * performed asynchronously, as soon as it is practical; meanwhile the
 297  * system operation will continue normally. When the renegotiation is
 298  * made, if the on-line admission test is enabled it determines
 299  * whether the contract can be admitted or not based on the current
 300  * contracts established in the system. If it cannot be admitted, the
 301  * old contract remains in effect. If it can be admitted, it
 302  * recalculates all necessary parameters for the contracts already
 303  * present in the system.
 304  *
 305  * When the operation is completed, notification is made to the
 306  * caller, if requested, via a signal. The status of the operation (in
 307  * progress, admitted, rejected) can be checked with the
 308  * frsh_vres_get_renegotiation_status() operation.  The argument
 309  * sig_notify can be FRSH_NULL_SIGNAL (no notification), or any FRSH
 310  * signal value and in this case signal_info is to be sent with the signal.
 311  *
 312  * @param[in] resource_id The network we are referring to (a protocol
 313  * could be able to handle several networks at the same time)
 314  * @param[in] vres The internal virtual resource id to renegotiate
 315  * @param[in] new_contract The new contract
 316  * @param[in] signal_to_notify  Signal number to use to notify vres of
 317  * the negotiation result. If FRSH_NULL_SIGNAL,  no signal will be raised.
 318  * @param[in] signal_info: Associated info that will come with the signal.
 319  * This parameter will be ignored if signal_to_notify == FRSH_NULL_SIGNAL.
 320  *
 321  * @return
 322  *   0 if there are no errors \n
 323  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 324  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 325  *   FNA_ERR_CONTRACT_ID_ALREADY_EXISTS: contract_id is not unique \n
 326  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 327  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 328  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL, or sig_notify is neither
 329  *      NULL nor a valid POSIX signal \n
 330  *
 331  **/
 332 typedef int fna_contract_renegotiate_async_t
 333    (const frsh_resource_id_t resource_id,
 334     const fna_vres_id_t vres,
 335     const frsh_contract_t *new_contract,
 336     frsh_signal_t signal_to_notify,
 337     frsh_signal_info_t signal_info);
 338
 339 /**
 340  * fna_vres_get_renegotiation_status()
 341  *
 342  * The operation reports on the status of the last renegotiation
 343  * operation enqueued for the specified vres. It is callable even
 344  * after notification of the completion of such operation, if
 345  * requested.
 346  *
 347  * If the vres is not and has not been involved in any of the
 348  * frsh_contract_renegotiate_async() or frsh_group_change_mode_async()
 349  * operations, the status returned is FNA_NOT_REQUESTED
 350  *
 351  * @param[in] resource_id The network we are referring to (a protocol
 352  * could be able to handle several networks at the same time)
 353  * @param[in] vres The internal virtual resource id we want the status from
 354  * @param[in] renegotiation_status The status of the last renegotiation on
 355  * vres (FRSH_RS_IN_PROGRESS, FRSH_RS_REJECTED, FRSH_RS_ADMITTED,
 356  * FRSH_RS_NOT_REQUESTED)
 357  *
 358  * @return
 359  *   0 if there are no errors \n
 360  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 361  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 362  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 363  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 364  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 365  *
 366  **/
 367 typedef int fna_vres_get_renegotiation_status_t
 368    (const frsh_resource_id_t resource_id,
 369     const fna_vres_id_t vres,
 370     frsh_renegotiation_status_t *renegotiation_status);
 371
 372 /**
 373  * fna_vres_destroy()
 374  *
 375  * The operation eliminates the specified vres
 376  * and recalculates all necessary parameters for the contracts
 377  * remaining in the system. This is a potentially blocking operation;
 378  * it returns when the system has made the changes effective.
 379  *
 380  * @param[in] resource_id The network we are referring to (a protocol
 381  * could be able to handle several networks at the same time)
 382  * @param[in] vres The internal virtual resource id to destroy
 383  *
 384  * @return
 385  *   0 if there are no errors \n
 386  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 387  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 388  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 389  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 390  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 391  *
 392  **/
 393 typedef int fna_vres_destroy_t
 394    (const frsh_resource_id_t resource_id,
 395     const fna_vres_id_t vres);
 396
 397 /**
 398  * fna_vres_get_contract()
 399  *
 400  * This operation stores the contract parameters currently associated
 401  * with the specified vres in the variable pointed to by
 402  * contract. It returns an error if the vres_id is not recognised.
 403  *
 404  * @param[in] resource_id The network we are referring to (a protocol
 405  * could be able to handle several networks at the same time)
 406  * @param[in] vres The internal virtual resource id
 407  * @param[out] contract  The contract parameters that we want
 408  *
 409  * @return
 410  *   0 if there are no errors \n
 411  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 412  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 413  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 414  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 415  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 416  *
 417  **/
 418 typedef int fna_vres_get_contract_t
 419    (const frsh_resource_id_t resource_id,
 420     const fna_vres_id_t vres,
 421     frsh_contract_t *contract);
 422
 423 /**
 424  * fna_vres_get_usage()
 425  *
 426  * This function gets the execution time spent by all messages that have been
 427  * sent through the specified vres.
 428  *
 429  * @param[in] resource_id The network we are referring to (a protocol
 430  * could be able to handle several networks at the same time)
 431  * @param[in] vres The internal virtual resource id
 432  * @param[out] usage  Execution time spent by this vres
 433  *
 434  * @return
 435  *   0 if there are no errors \n
 436  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 437  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 438  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 439  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 440  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 441  *
 442  **/
 443 typedef int fna_vres_get_usage_t
 444    (const frsh_resource_id_t resource_id,
 445     const fna_vres_id_t vres,
 446     struct timespec *usage);
 447
 448 /**
 449  * fna_vres_get_remaining_budget()
 450  *
 451  * This function stores in the variable pointed to by budget the
 452  * remaining execution-time budget associated with the specified
 453  * vres in the present period.
 454  *
 455  * @param[in] resource_id The network we are referring to (a protocol
 456  * could be able to handle several networks at the same time)
 457  * @param[in] vres The internal virtual resource id
 458  * @param[out] remaining_budget  The remaining budget for this period
 459  *
 460  *  @return
 461  *   0 if there are no errors \n
 462  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 463  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 464  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 465  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 466  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 467  *
 468  **/
 469 typedef int fna_vres_get_remaining_budget_t
 470    (const frsh_resource_id_t resource_id,
 471     const fna_vres_id_t vres,
 472     struct timespec *remaining_budget);
 473
 474 /**
 475  * fna_vres_get_budget_and_period()
 476  *
 477  * This function gets the budget and period associated with the specified vres
 478  * for each period. If one of these pointers is NULL, the corresponding
 479  * information is not stored.
 480  *
 481  * @param[in] resource_id The network we are referring to (a protocol
 482  * could be able to handle several networks at the same time)
 483  * @param[in] vres The internal virtual resource id
 484  * @param[out] budget The budget associated to vres
 485  * @param[out] period  The period associated to vres
 486  *
 487  * @return
 488  *   0 if there are no errors \n
 489  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 490  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 491  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 492  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 493  *   FNA_ERR_BAD_ARGUMENT: if both pointers are NULL \n
 494  *
 495  **/
 496 typedef int fna_vres_get_budget_and_period_t
 497    (const frsh_resource_id_t resource_id,
 498     const fna_vres_id_t vres,
 499     struct timespec *budget,
 500     struct timespec *period);
 501
 502 /*@}*/
 503
 504 ///////////////////////////////////////////////////////////////////
 505 //           SPARE CAPACITY FUNCIONS
 506 ///////////////////////////////////////////////////////////////////
 507
 508 /**
 509  * @defgroup fnaspare FNA Spare Capacity
 510  * @ingroup fna
 511  *
 512  * The following functions are used to get spare capacity data
 513  *
 514  * @{
 515  **/
 516
 517 /**
 518  * fna_resource_get_capacity()
 519  *
 520  * This operation gets the spare capacity currently assigned to a importance
 521  * level. If we divide this value by UINT32_MAX we will get the network
 522  * utilization associated to the spare capacity of a importance level.
 523  *
 524  * The following is typically in stdint.h: \n
 525  *  - typedef unsigned int uint32_t;  \n
 526  *  - # define UINT32_MAX  (4294967295U)  \n
 527  *
 528  * @param[in] resource_id The network we are referring to (a protocol
 529  * could be able to handle several networks at the same time)
 530  * @param[in] importance The importance we want the capacity of
 531  * @param[out] capacity The spare capacity for that importance level
 532  *
 533  * @return
 534  *   0 if there are no errors \n
 535  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 536  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 537  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 538  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 539  *
 540  **/
 541 typedef int fna_resource_get_capacity_t
 542    (const frsh_resource_id_t resource_id,
 543     const int importance,
 544     uint32_t *capacity);
 545
 546 /**
 547  * fna_resource_get_total_weight()
 548  *
 549  * This function gets the sum of the weight parameters for all vres in a
 550  * network of an importance level.
 551  *
 552  * @param[in] resource_id The network we are referring to (a protocol
 553  * could be able to handle several networks at the same time)
 554  * @param[in] importance The importance we want the total weight of
 555  * @param[out] total_weight The total weight for that importance level
 556  *
 557  * @return
 558  *   0 if there are no errors \n
 559  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 560  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 561  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 562  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 563  *
 564  **/
 565 typedef int fna_resource_get_total_weight_t
 566    (const frsh_resource_id_t resource_id,
 567     const int importance,
 568     int *total_weight);
 569
 570 /**
 571  * fna_vres_decrease_capacity()
 572  *
 573  * This function allows to ask for less budget and period than what we
 574  * received. The request must be compatible with the rest of contract
 575  * parameters of the vres. If we want to recover the released capacity
 576  * we will need to renegotiate.
 577  *
 578  * @param[in] resource_id The network we are referring to (a protocol
 579  * could be able to handle several networks at the same time)
 580  * @param[in] vres The internal virtual resource id
 581  * @param[in] new_budget The new_budget
 582  * @param[in] new_period The new Period
 583  *
 584  * @return
 585  *   0 if there are no errors \n
 586  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 587  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 588  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 589  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 590  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 591  *   FNA_ERR_CONTRACT_REJECTED: if it is incompatible with the current
 592  *      contract \n
 593  *
 594  **/
 595 typedef int fna_vres_decrease_capacity_t
 596    (const frsh_resource_id_t resource_id,
 597     const fna_vres_id_t vres,
 598     const struct timespec new_budget,
 599     const struct timespec new_period);
 600
 601 /*@}*/
 602
 603 ///////////////////////////////////////////////////////////////////
 604 //           SEND RECEIVE OPERATIONS
 605 ///////////////////////////////////////////////////////////////////
 606
 607 /**
 608  * @defgroup fnasendrecv FNA Send and Receive
 609  * @ingroup fna
 610  *
 611  * The following functions are used to send and receive
 612  *
 613  * @{
 614  **/
 615
 616 typedef enum {
 617     FRSH_SEND_ENDPOINT_TYPE,
 618     FRSH_RECEIVE_ENDPOINT_TYPE
 619 } frsh_endpoint_type_t;
 620
 621 typedef struct fna_endpoint_data {
 622     frsh_endpoint_type_t endpoint_type; // send_endpoint or receive_endpoint
 623     fna_vres_id_t vres;                 // only for send_endpoints
 624     bool is_bound;                      // only for send_endpoints
 625     frsh_network_address_t destination; // only for send_endpoints
 626     frsh_resource_id_t resource_id;
 627     frsh_stream_id_t stream_id;
 628     frsh_protocol_info_t protocol_info;
 629     frsh_endpoint_queueing_info_t queue_info;
 630     union {
 631         frsh_send_endpoint_protocol_info_t send;
 632         frsh_receive_endpoint_protocol_info_t receive;
 633     } endpoint_protocol_info;
 634 } fna_endpoint_data_t;
 635
 636 /**
 637  * fna_send_sync()
 638  *
 639  * Similar to previous function but now the sending thread gets blocked
 640  * until the message is already sent to the network.
 641  *
 642  * @param[in] endpoint The send endpoint we are sending through. It must
 643  *    be bound to a virtual resource (resource_id is in the endpoint).
 644  * @param[in] msg The message we want to send
 645  * @param[in] size The size in bytes of the message
 646  *
 647  * @returns
 648  *   0 if there are no errors \n
 649  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 650  *   FNA_ERR_NOT_BOUND: if endpoint is not bound to a valid vres \n
 651  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 652  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 653  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 654  *   FNA_ERR_TOO_LARGE: if the message is too large for the network protocol \n
 655  *   FNA_ERR_BUFFER_FULL: if the message has been discarded because
 656  *   the queue is full (and does not have the policy FNA_QP_OLDEST) \n
 657  *
 658  **/
 659 typedef int fna_send_sync_t
 660    (const fna_endpoint_data_t *endpoint,
 661     const void *msg,
 662     const size_t size);
 663
 664 /**
 665  * fna_send_async()
 666  *
 667  * This operation sends a message stored in msg and of length size
 668  * through the given send endpoint. The operation is non-blocking and
 669  * returns immediately.
 670  *
 671  * @param[in] endpoint The send endpoint we are sending through. It must
 672  *    be bound to a virtual resource (resource_id is in the endpoint).
 673  * @param[in] msg The message we want to send
 674  * @param[in] size The size in bytes of the message
 675  *
 676  * @returns
 677  *   0 if there are no errors \n
 678  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 679  *   FNA_ERR_NOT_BOUND: if endpoint is not bound to a valid vres \n
 680  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 681  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 682  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 683  *   FNA_ERR_TOO_LARGE: if the message is too large for the network protocol \n
 684  *   FNA_ERR_BUFFER_FULL: if the message has been discarded because
 685  *   the queue is full (and does not have the policy FNA_QP_OLDEST) \n
 686  *
 687  **/
 688 typedef int fna_send_async_t
 689    (const fna_endpoint_data_t *endpoint,
 690     const void *msg,
 691     const size_t size);
 692
 693 /**
 694  * fna_receive_sync()
 695  *
 696  * This operation is used to receive messages from the network with a
 697  * blocking behavior (if there are no messages this operation blocks
 698  * the calling thread).
 699  *
 700  * When a message is available, it is copied to buffer (up to its size).
 701  * The number of bytes copied is returned in received_bytes. The rest
 702  * of the bytes of that message will be lost or not depending on the
 703  * protocol (FNA_ERR_NO_SPACE will be returned if it is).
 704  *
 705  * The function fails with FNA_ERR_NO_SPACE if the buffersize is
 706  * too small for the message received.  In this case the message is
 707  * lost.
 708  *
 709  * Messages arriving at a receiver buffer that is full will be handled
 710  * according to the queueing policy of the endpoint (overwrite oldest,
 711  * discard it,etc).
 712  *
 713  * @param[in] endpoint The receive endpoint we are receiving from.
 714  *    (resource_id is in the endpoint).
 715  * @param[out] buffer Buffer for storing the received message
 716  * @param[in] buffer_size The size in bytes of this buffer
 717  * @param[out] received_bytes The actual number of received bytes
 718  * @param[out] from Address of the sender node
 719  *
 720  * @return
 721  *   0 if there are no errors \n
 722  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 723  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 724  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 725  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 726  *   FNA_ERR_NO_SPACE: if the message size is bigger than the
 727  *      provided buffer. \n
 728  *
 729  **/
 730 typedef int fna_receive_sync_t
 731    (const fna_endpoint_data_t *endpoint,
 732     void *buffer,
 733     const size_t buffer_size,
 734     size_t *received_bytes,
 735     frsh_network_address_t *from);
 736
 737 /**
 738  * fna_receive_async()
 739  *
 740  * This operation is similar to the previous one but it works in a non
 741  * blocking (asynchronous) fashion.  If no message is available it
 742  * returns with error FNA_NO_MESSAGE.
 743  *
 744  * @param[in] endpoint The receive endpoint we are receiving from.
 745  *    (resource_id is in the endpoint).
 746  * @param[out] buffer Buffer for storing the received message
 747  * @param[in] buffer_size The size in bytes of this buffer
 748  * @param[out] received_bytes The actual number of received bytes
 749  * @param[out] from Address of the sender node
 750  *
 751  * @return
 752  *   0 if there are no errors \n
 753  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 754  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 755  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 756  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 757  *   FNA_ERR_NO_SPACE: if the message size is bigger than the
 758  *      provided buffer. \n
 759  *   FNA_NO_MESSAGE: if no messages are available in the queue. \n
 760  *
 761  **/
 762 typedef int fna_receive_async_t
 763    (const fna_endpoint_data_t *endpoint,
 764     void *buffer,
 765     const size_t buffer_size,
 766     size_t *received_bytes,
 767     frsh_network_address_t *from);
 768
 769 /**
 770  * fna_send_endpoint_get_status()
 771  *
 772  * This function tells the number of messages still pending in the
 773  * endpoint queue, whether the network is up or down with some
 774  * optional information which is protocol_dependent.
 775  *
 776  * @param[in] endpoint The send endpoint (resource_id is in the endpoint).
 777  * @param[out] number_of_pending_messages The number of pending messages
 778  * @param[out] network_status How is the network (up, down..)
 779  * @param[out] protocol_status Protocol dependent status info
 780  *
 781  * @return
 782  *   0 if there are no errors \n
 783  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 784  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 785  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 786  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 787  *
 788  **/
 789 typedef int fna_send_endpoint_get_status_t
 790    (const fna_endpoint_data_t *endpoint,
 791     int *number_of_pending_messages,
 792     frsh_endpoint_network_status_t *network_status,
 793     frsh_protocol_status_t *protocol_status);
 794
 795 /**
 796  * fna_send_endpoint_bind_t()
 797  *
 798  * This operation is a called from frsh_send_endpoint_bind and binds send
 799  * edpoint to vres.
 800  *
 801  * @param[in] endpoint the endpoint object.
 802  * @param[in] vres The internal virtual resource id
 803  *
 804  * @return
 805  *   0 if there are no errors \n
 806  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 807  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 808  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 809  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 810  **/
 811 typedef
 812 int fna_send_endpoint_bind_t(fna_endpoint_data_t *endpoint, fna_vres_id_t vres);
 813
 814 /**
 815  * fna_send_endpoint_unbind_t()
 816  *
 817  * This operation is a called from frsh_send_endpoint_bind.
 818  *
 819  * @param[in] endpoint the endpoint object.
 820  *
 821  * @return
 822  *   0 if there are no errors \n
 823  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 824  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 825  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 826  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 827  **/
 828 typedef
 829 int fna_send_endpoint_unbind_t(fna_endpoint_data_t *endpoint);
 830
 831 /**
 832  * fna_send_endpoint_create_callback()
 833  *
 834  * This operation is a called from frsh_send_endpoint_create with a
 835  * send_endpoint structure already filled.
 836  *
 837  * @param[in] endpoint the endpoint object.
 838  *
 839  * @return
 840  *   0 if there are no errors \n
 841  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 842  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 843  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 844  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 845  **/
 846 typedef int fna_send_endpoint_create_callback_t
 847    (fna_endpoint_data_t *endpoint);
 848
 849 /**
 850  * fna_receive_endpoint_create_callback()
 851  *
 852  * This operation is a called from frsh_receive_endpoint_create with a
 853  * receive_endpoint structure already filled.
 854  *
 855  * Receiving endpoints are not bound to any network vres, this is
 856  * because don't originate any traffic.
 857  *
 858  * @param[in] endpoint the endpoint object.
 859  *
 860  * @return
 861  *   0 if there are no errors \n
 862  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 863  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 864  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 865  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 866  **/
 867 typedef int fna_receive_endpoint_create_callback_t
 868    (fna_endpoint_data_t *endpoint);
 869
 870 /**
 871  * fna_endpoint_destroy()
 872  *
 873  * This operation is a called from frsh_send(receive)_endpoint_destroy.
 874  *
 875  * @param[in] endpoint the endpoint object.
 876  *
 877  * @return
 878  *   0 if there are no errors \n
 879  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 880  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 881  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 882  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 883  **/
 884 typedef int fna_endpoint_destroy_t
 885    (fna_endpoint_data_t *endpoint);
 886
 887 /**
 888  * fna_receive_endpoint_get_pending_messages
 889  *
 890  * This function tells the number of messages still pending in the
 891  * endpoint queue, whether the network is up or down and some optional
 892  * information which is protocol dependent.
 893  *
 894  * @param[in] endpoint The receive endpoint (resource_id is in the endpoint).
 895  * @param[out] number_of_pending_messages The number of pending messages
 896  * @param[out] network_status How is the network (up, down..)
 897  * @param[out] protocol_status Protocol dependent status info
 898  *
 899  * @return
 900  *   0 if there are no errors \n
 901  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 902  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 903  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 904  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 905  *
 906  **/
 907 typedef int fna_receive_endpoint_get_status_t
 908    (const fna_endpoint_data_t *endpoint,
 909     int *number_of_pending_messages,
 910     frsh_endpoint_network_status_t *network_status,
 911     frsh_protocol_status_t *protocol_status);
 912
 913 /*@}*/
 914
 915 //////////////////////////////////////////////////////////////////////
 916 //           NETWORK CONFIGURATION FUNCTIONS
 917 //////////////////////////////////////////////////////////////////////
 918
 919 /**
 920  * @defgroup frshfnaconfig FNA Network Configuration
 921  * @ingroup fna
 922  *
 923  * These functions are needed to set/get some network dependent values
 924  *
 925  * @{
 926  **/
 927
 928 /**
 929  * fna_network_get_max_message_size()
 930  *
 931  * This operation gives the maximum number of bytes that can be sent
 932  * at a time through the send function when using the network designated by
 933  * 'resource_id' and sending it to 'destination'.
 934  *
 935  * If the application needs to send bigger messages it will have to
 936  * split them.
 937  *
 938  * Some protocols, like IP, are capable of sending large messages
 939  * (and use fragmentation internally) but other protocols don't.
 940  *
 941  * @param[in] resource_id The network we want the tx time from.
 942  * @param[in] destination The destination address
 943  * @param[out] max_size The maximum number of bytes for each message
 944  *
 945  * @return
 946  *   0 if there are no errors \n
 947  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 948  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 949  *   FNA_ERR_RESOURCE_ID_INVALID: if resource id does not represent
 950  *   a network accessible from the current processing node \n
 951  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL or destination is
 952  *   invalid \n
 953  *
 954  **/
 955 typedef int fna_network_get_max_message_size_t
 956    (const frsh_resource_id_t resource_id,
 957     const frsh_network_address_t destination,
 958     size_t *max_size);
 959
 960 /**
 961  * fna_network_bytes_to_budget()
 962  *
 963  * This operation converts a number of bytes into a temporal budget for
 964  * a specific network. Network overheads are not included here but are
 965  * considered internally when negotiating a specific contract.
 966  *
 967  * @param[in] resource_id The network
 968  * @param[in] nbytes Number of bytes
 969  * @param[out] budget The network budget for nbytes
 970  *
 971  * @return
 972  *   0 if there are no errors \n
 973  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 974  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 975  *   FNA_ERR_RESOURCE_ID_INVALID: if resource id does not represent
 976  *   a network accessible from the current processing node \n
 977  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL or nbytes is less
 978  *   than zero \n
 979  *
 980  **/
 981 typedef int fna_network_bytes_to_budget_t
 982    (const frsh_resource_id_t resource_id,
 983     const size_t nbytes,
 984     frsh_rel_time_t *budget);
 985
 986 /**
 987  * fna_network_budget_to_bytes()
 988  *
 989  * This operation converts a temporal budget into a number of bytes for
 990  * a specific network. Network overheads are not included.
 991  *
 992  * @param[in] resource_id The network
 993  * @param[in] budget The network budget for nbytes
 994  * @param[out] nbytes Number of bytes
 995  *
 996  * @return
 997  *   0 if there are no errors \n
 998  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 999  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
1000  *   FNA_ERR_RESOURCE_ID_INVALID: if resource id does not represent
1001  *   a network accessible from the current processing node \n
1002  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL or budget refers to
1003  *   an invalid time value \n
1004  *
1005  **/
1006 typedef int fna_network_budget_to_bytes_t
1007    (const frsh_resource_id_t resource_id,
1008     const frsh_rel_time_t *budget,
1009     size_t *nbytes);
1010
1011 /**
1012  * fna_network_get_min_effective_budget()
1013  *
1014  * This operation gets the minimum effective budget for a network. Each message
1015  * consumes a contracted budget in "chunks" (i.e: packets) that we call
1016  * minimum effective budget.
1017  *
1018  * A negotiated contract, for N bytes in a period T, means that there is a
1019  * virtual resource that reserves for the user:
1020  *
1021  *   Ceiling ((N bytes) / budget_to_bytes (min_effective_budget)) "CHUNKS"
1022  *
1023  * Note that if the user decides not to send these N bytes at once but, say,
1024  * one byte at a time, it will consume one "CHUNK" at a time and the reserved
1025  * budget will become exhausted before sending all the bytes.
1026  *
1027  * @param[in] resource_id The network
1028  * @param[out] budget The network budget
1029  *
1030  * @return
1031  *   0 if there are no errors \n
1032  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
1033  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
1034  *   FNA_ERR_RESOURCE_ID_INVALID: if resource id does not represent
1035  *   a network accessible from the current processing node \n
1036  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
1037  *
1038  **/
1039 typedef int fna_network_get_min_effective_budget_t
1040    (const frsh_resource_id_t resource_id,
1041     frsh_rel_time_t *budget);
1042
1043 /*@}*/
1044
1045 typedef struct {
1046     fna_init_t *fna_init;
1047     fna_group_change_mode_sync_t *fna_group_change_mode_sync;
1048     fna_contract_negotiate_t *fna_contract_negotiate;
1049     fna_contract_renegotiate_sync_t *fna_contract_renegotiate_sync;
1050     fna_contract_renegotiate_async_t *fna_contract_renegotiate_async;
1051     fna_vres_get_renegotiation_status_t *fna_vres_get_renegotiation_status;
1052     fna_vres_destroy_t *fna_vres_destroy;
1053     fna_vres_get_contract_t *fna_vres_get_contract;
1054     fna_vres_get_usage_t *fna_vres_get_usage;
1055     fna_vres_get_remaining_budget_t *fna_vres_get_remaining_budget;
1056     fna_vres_get_budget_and_period_t *fna_vres_get_budget_and_period;
1057     fna_resource_get_capacity_t *fna_resource_get_capacity;
1058     fna_resource_get_total_weight_t *fna_resource_get_total_weight;
1059     fna_vres_decrease_capacity_t *fna_vres_decrease_capacity;
1060     fna_send_sync_t *fna_send_sync;
1061     fna_send_async_t *fna_send_async;
1062     fna_receive_sync_t *fna_receive_sync;
1063     fna_receive_async_t *fna_receive_async;
1064     fna_send_endpoint_get_status_t *fna_send_endpoint_get_status;
1065     fna_send_endpoint_bind_t *fna_send_endpoint_bind;
1066     fna_send_endpoint_unbind_t *fna_send_endpoint_unbind;
1067     fna_endpoint_destroy_t *fna_endpoint_destroy;
1068     fna_send_endpoint_create_callback_t *fna_send_endpoint_created;
1069     fna_receive_endpoint_create_callback_t *fna_receive_endpoint_created;
1070     fna_receive_endpoint_get_status_t *fna_receive_endpoint_get_status;
1071     fna_network_get_max_message_size_t *fna_network_get_max_message_size;
1072     fna_network_bytes_to_budget_t *fna_network_bytes_to_budget;
1073     fna_network_budget_to_bytes_t *fna_network_budget_to_bytes;
1074     fna_network_get_min_effective_budget_t *fna_network_get_min_eff_budget;
1075 } fna_operations_t;
1076
1077 #endif // _FNA_H_
1078