src_frescan/frescan_bwres_frsh_fna.c

   1 /*!
   2  * @file frescan_bwres_frsh_fna.h
   3  *
   4  * @brief FRESCAN bandwidth reservation layer: FRSH FNA public functions
   5  *
   6  * This module contains FNA functions that need to be public mainly
   7  * for mapping between network types and FNA or FRSH types.
   8  *
   9  * @version 0.01
  10  *
  11  * @date 1-Apr-2008
  12  *
  13  * @author Daniel Sangorrin <daniel.sangorrin@unican.es>
  14  *
  15  * @license
  16  *
  17  * -----------------------------------------------------------------------
  18  *  Copyright (C) 2006 - 2008 FRESCOR consortium partners:
  19  *
  20  *    Universidad de Cantabria,              SPAIN
  21  *    University of York,                    UK
  22  *    Scuola Superiore Sant'Anna,            ITALY
  23  *    Kaiserslautern University,             GERMANY
  24  *    Univ. Politécnica  Valencia,           SPAIN
  25  *    Czech Technical University in Prague,  CZECH REPUBLIC
  26  *    ENEA                                   SWEDEN
  27  *    Thales Communication S.A.              FRANCE
  28  *    Visual Tools S.A.                      SPAIN
  29  *    Rapita Systems Ltd                     UK
  30  *    Evidence                               ITALY
  31  *
  32  *    See http://www.frescor.org for a link to partners' websites
  33  *
  34  *           FRESCOR project (FP6/2005/IST/5-034026) is funded
  35  *        in part by the European Union Sixth Framework Programme
  36  *        The European Union is not liable of any use that may be
  37  *        made of this code.
  38  *
  39  *  This file is part of FRESCAN
  40  *
  41  *  FRESCAN is free software; you can  redistribute it and/or  modify
  42  *  it under the terms of  the GNU General Public License as published by
  43  *  the Free Software Foundation;  either  version 2, or (at  your option)
  44  *  any later version.
  45  *
  46  *  FRESCAN  is distributed  in  the hope  that  it  will  be useful,  but
  47  *  WITHOUT  ANY  WARRANTY;     without  even the   implied   warranty  of
  48  *  MERCHANTABILITY  or  FITNESS FOR  A  PARTICULAR PURPOSE. See  the  GNU
  49  *  General Public License for more details.
  50  *
  51  *  You should have  received a  copy of  the  GNU  General Public License
  52  *  distributed  with  FRESCAN;  see file COPYING.   If not,  write to the
  53  *  Free Software  Foundation,  59 Temple Place  -  Suite 330,  Boston, MA
  54  *  02111-1307, USA.
  55  *
  56  * As a special exception, including FRESCAN header files in a file,
  57  * instantiating FRESCAN generics or templates, or linking other files
  58  * with FRESCAN objects to produce an executable application, does not
  59  * by itself cause the resulting executable application to be covered
  60  * by the GNU General Public License. This exception does not
  61  * however invalidate any other reasons why the executable file might be
  62  * covered by the GNU Public License.
  63  * -----------------------------------------------------------------------
  64  *
  65  */
  66
  67 #include "frsh_fna.h"
  68 #include "frescan.h"
  69 #include "frescan_debug.h"
  70
  71 //////////////////////////////////////////////////////////////////////
  72 //           MAPPING FUNCTIONS
  73 //////////////////////////////////////////////////////////////////////
  74
  75 /**
  76  * frsh_XXXX_map_network_address()
  77  *
  78  * To map a XXXX protocol network address into a FRSH address.
  79  * The protocol must keep this mapping consistent. Instead of using a function
  80  * a hardwired mapping could be used.
  81  *
  82  * @param[in] resource_id The network we are referring to (a protocol
  83  * could be able to handle several networks at the same time)
  84  * @param[in] in_address The network address we want to map to a frsh address
  85  * @param[out] out_address The FRSH abstract network address
  86  *
  87  * @return
  88  *   FNA_NO_ERROR: in this case it also means contract accepted \n
  89  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
  90  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
  91  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
  92  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
  93  *
  94  **/
  95 int frsh_frescan_map_network_address
  96       (const frsh_resource_id_t resource_id,
  97        const frescan_node_t in_address,
  98        frsh_network_address_t *out_address)
  99 {
 100     if (out_address == NULL) return -1;
 101     *out_address = in_address;
 102     return 0;
 103 }
 104
 105 /**
 106  * frsh_XXXX_map_stream_id()
 107  *
 108  * To map a XXXX protocol network stream, port, channel... into a FRSH stream.
 109  * The protocol must keep this mapping consistent. Instead of using a function
 110  * a hardwired mapping could be used.
 111  *
 112  * @param[in] resource_id The network we are referring to (a protocol
 113  * could be able to handle several networks at the same time)
 114  * @param[in] in_stream The network stream we want to map to a FRSH stream
 115  * @param[out] out_stream The FRSH abstract network stream
 116  *
 117  * @return
 118  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 119  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 120  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 121  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 122  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 123  *
 124  **/
 125 int frsh_frescan_map_stream_id
 126       (const frsh_resource_id_t resource_id,
 127        const frescan_channel_t in_stream,
 128        frsh_stream_id_t *out_stream)
 129 {
 130     if (out_stream == NULL) return -1;
 131     *out_stream = in_stream;
 132     return 0;
 133 }
 134
 135 ///////////////////////////////////////////////////////////////////
 136 //           NEGOTIATION SERVICE PARAMETERS
 137 ///////////////////////////////////////////////////////////////////
 138
 139 /**
 140  * frsh_XXXX_negotiation_messages__vres_renegotiate()
 141  *
 142  * This function allows the application to change the minimum period
 143  * of the negotiation messages sent through the network. It is similar
 144  * to the service thread but for the network messages. We do not provide
 145  * budget here because the size of the negotiation messages is fixed.
 146  *
 147  * This change is similar to a renegotiation so a schedulability test
 148  * must be done to see if the change can be accepted or not.
 149  *
 150  * @param[in] resource_id The network we are referring to (a protocol
 151  * could be able to handle several networks at the same time)
 152  * @param[in] period The new period for negotiation messages
 153  * @param[out] accepted If the change has been accepted or not
 154  *
 155  * @return
 156  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 157  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 158  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 159  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 160  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 161  *
 162  **/
 163
 164 int frsh_frescan_negotiation_messages_vres_renegotiate
 165       (const frsh_resource_id_t resource_id,
 166        const struct timespec *period)
 167 {
 168         FRESCAN_ERROR("not implemented\n");
 169         return -1;
 170 }
 171
 172 /**
 173  * frsh_XXXX_negotiation_messages_vres_get_period()
 174  *
 175  * This function gets the minimum period of the negotiation messages
 176  * sent through the network.
 177  *
 178  * @param[in] resource_id The network we are referring to (a protocol
 179  * could be able to handle several networks at the same time)
 180  * @param[out] period The period for negotiation messages
 181  *
 182  * @return
 183  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 184  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 185  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 186  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 187  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 188  *
 189  **/
 190 int frsh_frescan_negotiation_messages_vres_get_period
 191       (const frsh_resource_id_t resource_id,
 192        struct timespec *period)
 193 {
 194         FRESCAN_ERROR("not implemented\n");
 195         return -1;
 196 }
 197
 198 /**
 199  * frsh_XXXX_service_thread_vres_renegotiate()
 200  *
 201  * This function allows the application to change the period and
 202  * budget of the service thread that makes the negotiations and
 203  * schedulability tests in a network.
 204  *
 205  * The service thread starts with a default budget and period that
 206  * should be configurable
 207  *
 208  * @param[in] resource_id The network we are referring to (a protocol
 209  * could be able to handle several networks at the same time)
 210  * @param[in] budget The new budget for the service thread
 211  * @param[in] period The new period for the service thread
 212  * @param[out] accepted If the negotiation has been accepted or not
 213  *
 214  * @return
 215  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 216  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 217  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 218  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 219  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 220  *
 221  **/
 222 int frsh_frescan_service_thread_vres_renegotiate
 223    (const frsh_resource_id_t resource_id,
 224     const struct timespec *budget,
 225     const struct timespec *period,
 226     bool *accepted)
 227 {
 228         FRESCAN_ERROR("not implemented\n");
 229         return -1;
 230 }
 231
 232 /**
 233  * frsh_XXXX_service_thread_vres_get_budget_and_period()
 234  *
 235  * This function gets the budget and period of a service thread.
 236  *
 237  * @param[in] resource_id The network we are referring to (a protocol
 238  * could be able to handle several networks at the same time)
 239  * @param[out] budget The budget of the service thread
 240  * @param[out] period The period of the service thread
 241  *
 242  * @return
 243  *   FNA_NO_ERROR: in this case it also means contract accepted \n
 244  *   FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
 245  *   FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
 246  *   FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
 247  *   FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
 248  *
 249  **/
 250 int frsh_frescan_service_thread_vres_get_budget_and_period
 251       (const frsh_resource_id_t resource_id,
 252        struct timespec *budget,
 253        struct timespec *period)
 254 {
 255         FRESCAN_ERROR("not implemented\n");
 256         return -1;
 257 }