src_rtep/rtep_fna_c.c

   1 // -----------------------------------------------------------------------
   2 //  Copyright (C) 2006 - 2007 FRESCOR consortium partners:
   3 //
   4 //    Universidad de Cantabria,              SPAIN
   5 //    University of York,                    UK
   6 //    Scuola Superiore Sant'Anna,            ITALY
   7 //    Kaiserslautern University,             GERMANY
   8 //    Univ. Politécnica  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 for a link to partners' websites
  17 //
  18 //           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 //   FSF API web pages: http://marte.unican.es/fsf/docs
  32 //                      http://shark.sssup.it/contrib/first/docs/
  33 //
  34 //  This file is part of FRSH API
  35 //
  36 //  FRSH API is free software; you can  redistribute it and/or  modify
  37 //  it under the terms of  the GNU General Public License as published by
  38 //  the Free Software Foundation;  either  version 2, or (at  your option)
  39 //  any later version.
  40 //
  41 //  FRSH API  is distributed  in  the hope  that  it  will  be useful,  but
  42 //  WITHOUT  ANY  WARRANTY;     without  even the   implied   warranty  of
  43 //  MERCHANTABILITY  or  FITNESS FOR  A  PARTICULAR PURPOSE. See  the  GNU
  44 //  General Public License for more details.
  45 //
  46 //  You should have  received a  copy of  the  GNU  General Public License
  47 //  distributed  with  FRSH API;  see file COPYING.   If not,  write to the
  48 //  Free Software  Foundation,  59 Temple Place  -  Suite 330,  Boston, MA
  49 //  02111-1307, USA.
  50 //
  51 //  As a special exception, if you include this header file into source
  52 //  files to be compiled, this header file does not by itself cause
  53 //  the resulting executable to be covered by the GNU General Public
  54 //  License.  This exception does not however invalidate any other
  55 //  reasons why the executable file might be covered by the GNU General
  56 //  Public License.
  57 // -----------------------------------------------------------------------
  58
  59 //==============================================
  60 //  ******** ****     **     **
  61 //  **///// /**/**   /**    ****
  62 //  **      /**//**  /**   **//**
  63 //  ******* /** //** /**  **  //**
  64 //  **////  /**  //**/** **********
  65 //  **      /**   //****/**//////**
  66 //  **      /**    //***/**     /**
  67 //  /       //      /// //      //
  68 //
  69 // FNA(Frescor Network Adaptation layer), pronounced "efe ene a"
  70 //==============================================================
  71
  72 #ifndef _RTEP_FNA_H_
  73 #define _RTEP_FNA_H_
  74
  75 #include "fna.h"
  76 #include "rtep.h" // for rtep_adainit, rtep_valid_multicast_id, ..
  77 #include "rtep_bandwith_reservation.h" // for rtep_bwres_*
  78 #include <malloc.h> // for malloc and free
  79
  80 //////////////////////////////////////////////////////////////////////
  81 //           INITIALIZATION
  82 //////////////////////////////////////////////////////////////////////
  83
  84 /**
  85  * fna_init()
  86  *
  87  * This function will be hooked to the frsh_init function and it is
  88  * intented to initialize the protocol and its structures.
  89  *
  90  * @param[in]  resource_id The network we are referring to (a protocol
  91  * could be able to handle several networks at the same time)
  92  *
  93  * @return
  94  *   0 if there are no errors \n
  95  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
  96  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
  97  *   FNA_ERR_ALREADY_INITIALIZED:
  98  *      if the function has already been called before (with success) \n
  99  *
 100  **/
 101 int fna_init(const frsh_resource_id_t resource_id)
 102 {
 103    rtep_adainit(); // init Ada bindings
 104    return rtep_bwres_init();
 105 }
 106
 107 ///////////////////////////////////////////////////////////////////
 108 //           VIRTUAL RESOURCES
 109 ///////////////////////////////////////////////////////////////////
 110
 111 /**
 112  * fna_contract_negotiate()
 113  *
 114  * The operation negotiates a contract and if accepted it will return
 115  * a fna_vres_id_t. It will also check that the given contract_id is unique
 116  * within the network.
 117  *
 118  * If the on-line admission test is enabled, it determines whether the
 119  * contract can be admitted or not based on the current contracts
 120  * established in the network. Then it creates the vres and
 121  * recalculates all necessary parameters for the contracts already
 122  * present in the system.
 123  *
 124  * This is a potentially blocking operation, it returns when the
 125  * system has either rejected the contract, or admitted it and made it
 126  * effective.
 127  *
 128  * @param[in] resource_id The network we are referring to (a protocol
 129  * could be able to handle several networks at the same time)
 130  * @param[in] contract  The contract parameters to negotiate
 131  * @param[out] vres The internal virtual resource id
 132  *
 133  * @return
 134  *   0 if there are no errors (in this case it also means contract accepted) \n
 135  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 136  *   FNA_ERR_TOO_MANY_VRES: if there is no space for more vres \n
 137  *   FNA_ERR_CONTRACT_ID_ALREADY_EXISTS: contract_id is not unique \n
 138  *   FNA_ERR_CONTRACT_REJECTED: if the contract is not accepted \n
 139  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 140  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 141  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 142  *
 143  **/
 144 int fna_contract_negotiate
 145       (const frsh_resource_id_t resource_id,
 146        const frsh_contract_t *contract,
 147        fna_vres_id_t *vres)
 148 {
 149    rtep_bwres_contract_t rtep_contract;
 150    rtep_bwres_vres_t *rtep_vres;
 151    int accepted;
 152
 153    // convert FRSH contract to RTEP BWRES contract
 154    rtep_contract.period_max = contract->period_max;
 155    rtep_contract.deadline = contract->deadline;
 156    rtep_contract.prio = contract->preemption_level;
 157    // in RTEP BWRES, budget is given in number of packets. We do a little trick
 158    // in the function bytes_to_network_budget to use a the field tv_sec from the
 159    // timespec in frsh_contract to store the budget in bytes directly
 160    rtep_contract.budget_min = contract->budget_min.tv_sec;
 161
 162    // create an internal vres. The fna vres id is a pointer to void which
 163    // we transform internally to a pointer to a vres structure
 164    rtep_vres = (rtep_bwres_vres_t *)malloc(sizeof(rtep_bwres_vres_t));
 165
 166    // negotiate the contract
 167    accepted = rtep_bwres_contract_negotiate (&rtep_contract, rtep_vres);
 168
 169    // vres is a pointer to void *, so we change void * for the new *rtep_vres
 170    if (accepted == 0){
 171       *vres = (void *)rtep_vres;
 172    }else{
 173       free(rtep_vres);
 174    }
 175
 176    return accepted;
 177 }
 178
 179 /**
 180  * fna_contract_renegotiate_sync()
 181  *
 182  * The operation renegotiates a contract for an existing vres. If
 183  * the on-line admission test is enabled it determines whether the
 184  * contract can be admitted or not based on the current contracts
 185  * established in the system. If it cannot be admitted, the old
 186  * contract remains in effect and an error is returned. If it can be
 187  * admitted, it recalculates all necessary parameters for the
 188  * contracts already present in the system and returns zero. This is a
 189  * potentially blocking operation; it returns when the system has
 190  * either rejected the new contract, or admitted it and made it
 191  * effective.
 192  *
 193  * @param[in] resource_id The network we are referring to (a protocol
 194  * could be able to handle several networks at the same time)
 195  * @param[in] vres The internal virtual resource id to renegotiate
 196  * @param[in] new_contract The new contract
 197  *
 198  *  @return
 199  *   0 if there are no errors (in this case it also means contract accepted) \n
 200  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 201  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 202  *   FNA_ERR_CONTRACT_ID_ALREADY_EXISTS: contract_id is not unique \n
 203  *   FNA_ERR_CONTRACT_REJECTED: if the contract is not accepted \n
 204  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 205  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 206  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 207  *
 208  **/
 209 int fna_contract_renegotiate_sync
 210       (const frsh_resource_id_t resource_id,
 211        const fna_vres_id_t vres,
 212        const frsh_contract_t *new_contract)
 213 {
 214    return 0;
 215 }
 216
 217 /**
 218  * fna_contract_renegotiate_async()
 219  *
 220  * The operation enqueues a renegotiate operation for an existing
 221  * vres, and returns immediately. The renegotiate operation is
 222  * performed asynchronously, as soon as it is practical; meanwhile the
 223  * system operation will continue normally. When the renegotiation is
 224  * made, if the on-line admission test is enabled it determines
 225  * whether the contract can be admitted or not based on the current
 226  * contracts established in the system. If it cannot be admitted, the
 227  * old contract remains in effect. If it can be admitted, it
 228  * recalculates all necessary parameters for the contracts already
 229  * present in the system.
 230  *
 231  * When the operation is completed, notification is made to the
 232  * caller, if requested, via a signal. The status of the operation (in
 233  * progress, admitted, rejected) can be checked with the
 234  * frsh_vres_get_renegotiation_status() operation.  The argument
 235  * sig_notify can be FRSH_NULL_SIGNAL (no notification), or any FRSH
 236  * signal value and in this case signal_info is to be sent with the signal.
 237  *
 238  * @param[in] resource_id The network we are referring to (a protocol
 239  * could be able to handle several networks at the same time)
 240  * @param[in] vres The internal virtual resource id to renegotiate
 241  * @param[in] new_contract The new contract
 242  * @param[in] signal_to_notify  Signal number to use to notify vres of
 243  * the negotiation result. If FRSH_NULL_SIGNAL,  no signal will be raised.
 244  * @param[in] signal_info: Associated info that will come with the signal.
 245  * This parameter will be ignored if signal_to_notify == FRSH_NULL_SIGNAL.
 246  *
 247  * @return
 248  *   0 if there are no errors \n
 249  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 250  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 251  *   FNA_ERR_CONTRACT_ID_ALREADY_EXISTS: contract_id is not unique \n
 252  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 253  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 254  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL, or sig_notify is neither
 255  *      NULL nor a valid POSIX signal \n
 256  *
 257  **/
 258 int fna_contract_renegotiate_async
 259       (const frsh_resource_id_t resource_id,
 260        const fna_vres_id_t vres,
 261        const frsh_contract_t *new_contract,
 262        frsh_signal_t signal_to_notify,
 263        frsh_signal_info_t signal_info)
 264 {
 265    return 0;
 266 }
 267
 268 /**
 269  * fna_vres_get_renegotiation_status()
 270  *
 271  * The operation reports on the status of the last renegotiation
 272  * operation enqueued for the specified vres. It is callable even
 273  * after notification of the completion of such operation, if
 274  * requested.
 275  *
 276  * If the vres is not and has not been involved in any of the
 277  * frsh_contract_renegotiate_async() or frsh_group_change_mode_async()
 278  * operations, the status returned is FNA_NOT_REQUESTED
 279  *
 280  * @param[in] resource_id The network we are referring to (a protocol
 281  * could be able to handle several networks at the same time)
 282  * @param[in] vres The internal virtual resource id we want the status from
 283  * @param[in] renegotiation_status The status of the last renegotiation on
 284  * vres (FRSH_RS_IN_PROGRESS, FRSH_RS_REJECTED, FRSH_RS_ADMITTED,
 285  * FRSH_RS_NOT_REQUESTED)
 286  *
 287  * @return
 288  *   0 if there are no errors \n
 289  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 290  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 291  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 292  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 293  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 294  *
 295  **/
 296 int fna_vres_get_renegotiation_status
 297       (const frsh_resource_id_t resource_id,
 298        const fna_vres_id_t vres,
 299        frsh_renegotiation_status_t *renegotiation_status)
 300 {
 301    return 0;
 302 }
 303
 304 /**
 305  * fna_vres_destroy()
 306  *
 307  * The operation eliminates the specified vres
 308  * and recalculates all necessary parameters for the contracts
 309  * remaining in the system. This is a potentially blocking operation;
 310  * it returns when the system has made the changes effective.
 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 destroy
 315  *
 316  * @return
 317  *   0 if there are no errors \n
 318  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 319  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 320  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 321  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 322  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 323  *
 324  **/
 325 int fna_vres_destroy
 326       (const frsh_resource_id_t resource_id,
 327        const fna_vres_id_t vres)
 328 {
 329    return 0;
 330 }
 331
 332 /**
 333  * fna_vres_get_contract()
 334  *
 335  * This operation stores the contract parameters currently associated
 336  * with the specified vres in the variable pointed to by
 337  * contract. It returns an error if the vres_id is not recognised.
 338  *
 339  * @param[in] resource_id The network we are referring to (a protocol
 340  * could be able to handle several networks at the same time)
 341  * @param[in] vres The internal virtual resource id
 342  * @param[out] contract  The contract parameters that we want
 343  *
 344  * @return
 345  *   0 if there are no errors \n
 346  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 347  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 348  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 349  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 350  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 351  *
 352  **/
 353 int fna_vres_get_contract
 354       (const frsh_resource_id_t resource_id,
 355        const fna_vres_id_t vres,
 356        frsh_contract_t *contract)
 357 {
 358    return 0;
 359 }
 360
 361 /**
 362  * fna_vres_get_usage()
 363  *
 364  * This function gets the execution time spent by all messages that have been
 365  * sent through the specified vres.
 366  *
 367  * @param[in] resource_id The network we are referring to (a protocol
 368  * could be able to handle several networks at the same time)
 369  * @param[in] vres The internal virtual resource id
 370  * @param[out] usage  Execution time spent by this vres
 371  *
 372  * @return
 373  *   0 if there are no errors \n
 374  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 375  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 376  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 377  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 378  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 379  *
 380  **/
 381 int fna_vres_get_usage
 382       (const frsh_resource_id_t resource_id,
 383        const fna_vres_id_t vres,
 384        struct timespec *usage)
 385 {
 386    return 0;
 387 }
 388
 389 /**
 390  * fna_vres_get_remaining_budget()
 391  *
 392  * This function stores in the variable pointed to by budget the
 393  * remaining execution-time budget associated with the specified
 394  * vres in the present period.
 395  *
 396  * @param[in] resource_id The network we are referring to (a protocol
 397  * could be able to handle several networks at the same time)
 398  * @param[in] vres The internal virtual resource id
 399  * @param[out] remaining_budget  The remaining budget for this period
 400  *
 401  *  @return
 402  *   0 if there are no errors \n
 403  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 404  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 405  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 406  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 407  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 408  *
 409  **/
 410 int fna_vres_get_remaining_budget
 411       (const frsh_resource_id_t resource_id,
 412        const fna_vres_id_t vres,
 413        struct timespec *remaining_budget)
 414 {
 415    return 0;
 416 }
 417
 418 /**
 419  * fna_vres_get_budget_and_period()
 420  *
 421  * This function gets the budget and period associated with the specified vres
 422  * for each period. If one of these pointers is NULL, the corresponding
 423  * information is not stored.
 424  *
 425  * @param[in] resource_id The network we are referring to (a protocol
 426  * could be able to handle several networks at the same time)
 427  * @param[in] vres The internal virtual resource id
 428  * @param[out] budget The budget associated to vres
 429  * @param[out] period  The period associated to vres
 430  *
 431  * @return
 432  *   0 if there are no errors \n
 433  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 434  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 435  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 436  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 437  *   FNA_ERR_BAD_ARGUMENT: if both pointers are NULL \n
 438  *
 439  **/
 440 int fna_vres_get_budget_and_period
 441       (const frsh_resource_id_t resource_id,
 442        const fna_vres_id_t vres,
 443        struct timespec *budget,
 444        struct timespec *period)
 445 {
 446    return 0;
 447 }
 448
 449 /*@}*/
 450
 451 ///////////////////////////////////////////////////////////////////
 452 //           SPARE CAPACITY FUNCIONS
 453 ///////////////////////////////////////////////////////////////////
 454
 455 /**
 456  * @defgroup fnaspare FNA Spare Capacity
 457  * @ingroup fna
 458  *
 459  * The following functions are used to get spare capacity data
 460  *
 461  * @{
 462  **/
 463
 464 /**
 465  * fna_resource_get_capacity()
 466  *
 467  * This operation gets the spare capacity currently assigned to a importance
 468  * level. If we divide this value by UINT32_MAX we will get the network
 469  * utilization associated to the spare capacity of a importance level.
 470  *
 471  * The following is typically in stdint.h: \n
 472  *  - typedef unsigned int uint32_t;  \n
 473  *  - # define UINT32_MAX  (4294967295U)  \n
 474  *
 475  * @param[in] resource_id The network we are referring to (a protocol
 476  * could be able to handle several networks at the same time)
 477  * @param[in] importance The importance we want the capacity of
 478  * @param[out] capacity The spare capacity for that importance level
 479  *
 480  * @return
 481  *   0 if there are no errors \n
 482  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 483  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 484  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 485  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 486  *
 487  **/
 488 int fna_resource_get_capacity
 489       (const frsh_resource_id_t resource_id,
 490        const int importance,
 491        uint32_t *capacity)
 492 {
 493    return 0;
 494 }
 495
 496 /**
 497  * fna_resource_get_total_weight()
 498  *
 499  * This function gets the sum of the weight parameters for all vres in a
 500  * network of an importance level.
 501  *
 502  * @param[in] resource_id The network we are referring to (a protocol
 503  * could be able to handle several networks at the same time)
 504  * @param[in] importance The importance we want the total weight of
 505  * @param[out] total_weight The total weight for that importance level
 506  *
 507  * @return
 508  *   0 if there are no errors \n
 509  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 510  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 511  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 512  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 513  *
 514  **/
 515 int fna_resource_get_total_weight
 516       (const frsh_resource_id_t resource_id,
 517        const int importance,
 518        int *total_weight)
 519 {
 520    return 0;
 521 }
 522
 523 /**
 524  * fna_vres_decrease_capacity()
 525  *
 526  * This function allows to ask for less budget and period than what we
 527  * received. The request must be compatible with the rest of contract
 528  * parameters of the vres. If we want to recover the released capacity
 529  * we will need to renegotiate.
 530  *
 531  * @param[in] resource_id The network we are referring to (a protocol
 532  * could be able to handle several networks at the same time)
 533  * @param[in] vres The internal virtual resource id
 534  * @param[in] new_budget The new_budget
 535  * @param[in] new_period The new Period
 536  *
 537  * @return
 538  *   0 if there are no errors \n
 539  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 540  *   FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
 541  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 542  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 543  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 544  *   FNA_ERR_CONTRACT_REJECTED: if it is incompatible with the current
 545  *      contract \n
 546  *
 547  **/
 548 int fna_vres_decrease_capacity
 549       (const frsh_resource_id_t resource_id,
 550        const fna_vres_id_t vres,
 551        const struct timespec new_budget,
 552        const struct timespec new_period)
 553 {
 554    return 0;
 555 }
 556
 557 ///////////////////////////////////////////////////////////////////
 558 //           SEND RECEIVE OPERATIONS
 559 ///////////////////////////////////////////////////////////////////
 560
 561 /**
 562  * fna_send_sync()
 563  *
 564  * Similar to previous function but now the sending thread gets blocked
 565  * until the message is already sent to the network.
 566  *
 567  * @param[in] endpoint The send endpoint we are sending through. It must
 568  *    be bound to a virtual resource (resource_id is in the endpoint).
 569  * @param[in] msg The message we want to send
 570  * @param[in] size The size in bytes of the message
 571  *
 572  * @returns
 573  *   0 if there are no errors \n
 574  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 575  *   FNA_ERR_NOT_BOUND: if endpoint is not bound to a valid vres \n
 576  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 577  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 578  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 579  *   FNA_ERR_TOO_LARGE: if the message is too large for the network protocol \n
 580  *   FNA_ERR_BUFFER_FULL: if the message has been discarded because
 581  *   the queue is full (and does not have the policy FNA_QP_OLDEST) \n
 582  *
 583  **/
 584 int fna_send_sync
 585    (const fna_send_endpoint_t *endpoint,
 586     const void *msg,
 587     const size_t size)
 588 {
 589    return 0;
 590 }
 591
 592 /**
 593  * fna_send_async()
 594  *
 595  * This operation sends a message stored in msg and of length size
 596  * through the given send endpoint. The operation is non-blocking and
 597  * returns immediately.
 598  *
 599  * @param[in] endpoint The send endpoint we are sending through. It must
 600  *    be bound to a virtual resource (resource_id is in the endpoint).
 601  * @param[in] msg The message we want to send
 602  * @param[in] size The size in bytes of the message
 603  *
 604  * @returns
 605  *   0 if there are no errors \n
 606  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 607  *   FNA_ERR_NOT_BOUND: if endpoint is not bound to a valid vres \n
 608  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 609  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 610  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 611  *   FNA_ERR_TOO_LARGE: if the message is too large for the network protocol \n
 612  *   FNA_ERR_BUFFER_FULL: if the message has been discarded because
 613  *   the queue is full (and does not have the policy FNA_QP_OLDEST) \n
 614  *
 615  **/
 616 int fna_send_async
 617    (const fna_send_endpoint_t *endpoint,
 618     const void *msg,
 619     const size_t size)
 620 {
 621    return 0;
 622 }
 623
 624 /**
 625  * fna_receive_sync()
 626  *
 627  * This operation is used to receive messages from the network with a
 628  * blocking behavior (if there are no messages this operation blocks
 629  * the calling thread).
 630  *
 631  * When a message is available, it is copied to buffer (up to its size).
 632  * The number of bytes copied is returned in received_bytes. The rest
 633  * of the bytes of that message will be lost or not depending on the
 634  * protocol (FNA_ERR_NO_SPACE will be returned if it is).
 635  *
 636  * The function fails with FNA_ERR_NO_SPACE if the buffersize is
 637  * too small for the message received.  In this case the message is
 638  * lost.
 639  *
 640  * Messages arriving at a receiver buffer that is full will be handled
 641  * according to the queueing policy of the endpoint (overwrite oldest,
 642  * discard it,etc).
 643  *
 644  * @param[in] endpoint The receive endpoint we are receiving from.
 645  *    (resource_id is in the endpoint).
 646  * @param[out] buffer Buffer for storing the received message
 647  * @param[in] buffer_size The size in bytes of this buffer
 648  * @param[out] received_bytes The actual number of received bytes
 649  * @param[out] from Address of the sender node
 650  *
 651  * @return
 652  *   0 if there are no errors \n
 653  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 654  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 655  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 656  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 657  *   FNA_ERR_NO_SPACE: if the message size is bigger than the
 658  *      provided buffer. \n
 659  *
 660  **/
 661 int fna_receive_sync
 662       (const frsh_receive_endpoint_t *endpoint,
 663        void *buffer,
 664        const size_t buffer_size,
 665        size_t *received_bytes,
 666        frsh_network_address_t *from)
 667 {
 668    return 0;
 669 }
 670
 671 /**
 672  * fna_receive_async()
 673  *
 674  * This operation is similar to the previous one but it works in a non
 675  * blocking (asynchronous) fashion.  If no message is available it
 676  * returns with error FNA_NO_MESSAGE.
 677  *
 678  * @param[in] endpoint The receive endpoint we are receiving from.
 679  *    (resource_id is in the endpoint).
 680  * @param[out] buffer Buffer for storing the received message
 681  * @param[in] buffer_size The size in bytes of this buffer
 682  * @param[out] received_bytes The actual number of received bytes
 683  * @param[out] from Address of the sender node
 684  *
 685  * @return
 686  *   0 if there are no errors \n
 687  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 688  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 689  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 690  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 691  *   FNA_ERR_NO_SPACE: if the message size is bigger than the
 692  *      provided buffer. \n
 693  *   FNA_NO_MESSAGE: if no messages are available in the queue. \n
 694  *
 695  **/
 696 int fna_receive_async
 697       (const frsh_receive_endpoint_t *endpoint,
 698        void *buffer,
 699        const size_t buffer_size,
 700        size_t *received_bytes,
 701        frsh_network_address_t *from)
 702 {
 703    return 0;
 704 }
 705
 706 /**
 707  * fna_send_endpoint_get_status()
 708  *
 709  * This function tells the number of messages still pending in the
 710  * endpoint queue, whether the network is up or down with some
 711  * optional information which is protocol_dependent.
 712  *
 713  * @param[in] endpoint The send endpoint (resource_id is in the endpoint).
 714  * @param[out] number_of_pending_messages The number of pending messages
 715  * @param[out] network_status How is the network (up, down..)
 716  * @param[out] protocol_status Protocol dependent status info
 717  *
 718  * @return
 719  *   0 if there are no errors \n
 720  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 721  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 722  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 723  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 724  *
 725  **/
 726 int fna_send_endpoint_get_status
 727    (const fna_send_endpoint_t *endpoint,
 728     int *number_of_pending_messages,
 729     frsh_endpoint_network_status *network_status,
 730     frsh_protocol_status_t *protocol_status)
 731 {
 732    return 0;
 733 }
 734
 735 /**
 736  * fna_receive_endpoint_create_callback()
 737  *
 738  * This operation is a called from frsh_receive_endpoint_create with a
 739  * receive_endpoint structure already filled.
 740  *
 741  * Receiving endpoints are not bound to any network vres, this is
 742  * because don't originate any traffic.
 743  *
 744  * @param[in] endpoint the endpoint object.
 745  *
 746  * @return
 747  *   0 if there are no errors \n
 748  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 749  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 750  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 751  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 752  **/
 753 int fna_receive_endpoint_create_callback
 754       (const frsh_receive_endpoint_t *endpoint)
 755 {
 756    return 0;
 757 }
 758
 759 /**
 760  * fna_receive_endpoint_get_pending_messages
 761  *
 762  * This function tells the number of messages still pending in the
 763  * endpoint queue, whether the network is up or down and some optional
 764  * information which is protocol dependent.
 765  *
 766  * @param[in] endpoint The receive endpoint (resource_id is in the endpoint).
 767  * @param[out] number_of_pending_messages The number of pending messages
 768  * @param[out] network_status How is the network (up, down..)
 769  * @param[out] protocol_status Protocol dependent status info
 770  *
 771  * @return
 772  *   0 if there are no errors \n
 773  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 774  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 775  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 776  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 777  *
 778  **/
 779 int fna_receive_endpoint_get_status
 780       (const frsh_receive_endpoint_t *endpoint,
 781        int *number_of_pending_messages,
 782        frsh_endpoint_network_status *network_status,
 783        frsh_protocol_status_t *protocol_status)
 784 {
 785    return 0;
 786 }
 787
 788 //////////////////////////////////////////////////////////////////////
 789 //           NETWORK CONFIGURATION FUNCTIONS
 790 //////////////////////////////////////////////////////////////////////
 791
 792 /**
 793  * fna_network_get_max_message_size()
 794  *
 795  * This operation gives the maximum number of bytes that can be sent
 796  * at a time through the send function when using the network designated by
 797  * 'resource_id' and sending it to 'destination'.
 798  *
 799  * If the application needs to send bigger messages it will have to
 800  * split them.
 801  *
 802  * Some protocols, like IP, are capable of sending large messages
 803  * (and use fragmentation internally) but other protocols don't.
 804  *
 805  * @param[in] resource_id The network we want the tx time from.
 806  * @param[in] destination The destination address
 807  * @param[out] max_size The maximum number of bytes for each message
 808  *
 809  * @return
 810  *   0 if there are no errors \n
 811  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 812  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 813  *   FNA_ERR_RESOURCE_ID_INVALID: if resource id does not represent
 814  *   a network accessible from the current processing node \n
 815  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL or destination is
 816  *   invalid \n
 817  *
 818  **/
 819 int fna_network_get_max_message_size
 820       (const frsh_resource_id_t resource_id,
 821        const frsh_network_address_t destination,
 822        size_t *max_size)
 823 {
 824    int is_multicast;
 825
 826    if (max_size == NULL) {
 827       return -1;
 828    }
 829
 830    is_multicast = rtep_valid_multicast_id ((rtep_station_id_t) destination);
 831    if (is_multicast) {
 832       *max_size = MULTICAST_MTU;
 833    } else {
 834       *max_size = MAX_RTEP_MTU;
 835    }
 836    return 0;
 837 }
 838
 839 /**
 840  * fna_network_bytes_to_budget()
 841  *
 842  * This operation converts a number of bytes into a temporal budget for
 843  * a specific network. Network overheads are not included here but are
 844  * considered internally when negotiating a specific contract.
 845  *
 846  * @param[in] resource_id The network
 847  * @param[in] nbytes Number of bytes
 848  * @param[out] budget The network budget for nbytes
 849  *
 850  * @return
 851  *   0 if there are no errors \n
 852  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 853  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 854  *   FNA_ERR_RESOURCE_ID_INVALID: if resource id does not represent
 855  *   a network accessible from the current processing node \n
 856  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL or nbytes is less
 857  *   than zero \n
 858  *
 859  **/
 860 int fna_network_bytes_to_budget
 861       (const frsh_resource_id_t resource_id,
 862        const size_t nbytes,
 863        struct timespec *budget)
 864 {
 865    int number_of_packets;
 866
 867    if (budget == NULL || nbytes < 0) {
 868       return -1;
 869    }
 870
 871    // we measure the budget in number of RTEP packets of maximum size
 872    number_of_packets = nbytes / MAX_RTEP_MTU + 1;
 873    // we store the budget in number of packets instead of in time. We
 874    // use a field in the timespec structure.
 875    budget->tv_sec = number_of_packets;
 876
 877    return 0;
 878 }
 879
 880 /**
 881  * fna_network_budget_to_bytes()
 882  *
 883  * This operation converts a temporal budget into a number of bytes for
 884  * a specific network. Network overheads are not included.
 885  *
 886  * @param[in] resource_id The network
 887  * @param[in] budget The network budget for nbytes
 888  * @param[out] nbytes Number of bytes
 889  *
 890  * @return
 891  *   0 if there are no errors \n
 892  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 893  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 894  *   FNA_ERR_RESOURCE_ID_INVALID: if resource id does not represent
 895  *   a network accessible from the current processing node \n
 896  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL or budget refers to
 897  *   an invalid time value \n
 898  *
 899  **/
 900 int fna_network_budget_to_bytes
 901       (const frsh_resource_id_t resource_id,
 902        const struct timespec *budget,
 903        size_t *nbytes)
 904 {
 905    int number_of_packets;
 906
 907    if (budget == NULL || nbytes == NULL) {
 908       return -1;
 909    }
 910    number_of_packets = budget->tv_sec;
 911    *nbytes = number_of_packets * MAX_RTEP_MTU;
 912    return 0;
 913 }
 914
 915 /**
 916  * fna_network_get_min_effective_budget()
 917  *
 918  * This operation gets the minimum effective budget for a network. Each message
 919  * consumes a contracted budget in "chunks" (i.e: packets) that we call
 920  * minimum effective budget.
 921  *
 922  * A negotiated contract, for N bytes in a period T, means that there is a
 923  * virtual resource that reserves for the user:
 924  *
 925  *   Ceiling ((N bytes) / budget_to_bytes (min_effective_budget)) "CHUNKS"
 926  *
 927  * Note that if the user decides not to send these N bytes at once but, say,
 928  * one byte at a time, it will consume one "CHUNK" at a time and the reserved
 929  * budget will become exhausted before sending all the bytes.
 930  *
 931  * @param[in] resource_id The network
 932  * @param[out] budget The network budget
 933  *
 934  * @return
 935  *   0 if there are no errors \n
 936  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 937  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 938  *   FNA_ERR_RESOURCE_ID_INVALID: if resource id does not represent
 939  *   a network accessible from the current processing node \n
 940  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 941  *
 942  **/
 943 int fna_network_get_min_effective_budget
 944       (const frsh_resource_id_t resource_id,
 945        struct timespec *budget)
 946 {
 947    if (budget == NULL) {
 948       return -1;
 949    }
 950    budget->tv_sec = 1;
 951    return 0;
 952 }
 953
 954 #endif // _RTEP_FNA_H_
 955