src/fna/src_frescan/frescan_servers.h

   1 /*!
   2  * @file frescan_servers.h
   3  *
   4  * @brief FRESCAN sporadic servers
   5  *
   6  * @version 0.01
   7  *
   8  * @date 27-Feb-2008
   9  *
  10  * @author
  11  *      Daniel Sangorrin
  12  *
  13  * @comments
  14  *
  15  * This file contains the FRESCAN sporadic servers that allow to isolate
  16  * different streams of data by assigning them a budget and replenishment
  17  * period.
  18  *
  19  * @license
  20  *
  21 //----------------------------------------------------------------------
  22 //  Copyright (C) 2006 - 2009 by the FRESCOR consortium:
  23 //
  24 //    Universidad de Cantabria,              SPAIN
  25 //    University of York,                    UK
  26 //    Scuola Superiore Sant'Anna,            ITALY
  27 //    Kaiserslautern University,             GERMANY
  28 //    Univ. Politecnica  Valencia,           SPAIN
  29 //    Czech Technical University in Prague,  CZECH REPUBLIC
  30 //    ENEA                                   SWEDEN
  31 //    Thales Communication S.A.              FRANCE
  32 //    Visual Tools S.A.                      SPAIN
  33 //    Rapita Systems Ltd                     UK
  34 //    Evidence                               ITALY
  35 //
  36 //    See http://www.frescor.org
  37 //
  38 //        The FRESCOR project (FP6/2005/IST/5-034026) is funded
  39 //        in part by the European Union Sixth Framework Programme
  40 //        The European Union is not liable of any use that may be
  41 //        made of this code.
  42 //
  43 //
  44 //  based on previous work (FSF) done in the FIRST project
  45 //
  46 //   Copyright (C) 2005  Mälardalen University, SWEDEN
  47 //                       Scuola Superiore S.Anna, ITALY
  48 //                       Universidad de Cantabria, SPAIN
  49 //                       University of York, UK
  50 //
  51 // This file is part of FNA (Frescor Network Adaptation)
  52 //
  53 // FNA is free software; you can redistribute it and/or modify it
  54 // under terms of the GNU General Public License as published by the
  55 // Free Software Foundation; either version 2, or (at your option) any
  56 // later version.  FNA is distributed in the hope that it will be
  57 // useful, but WITHOUT ANY WARRANTY; without even the implied warranty
  58 // of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  59 // General Public License for more details. You should have received a
  60 // copy of the GNU General Public License along with FNA; see file
  61 // COPYING. If not, write to the Free Software Foundation, 675 Mass Ave,
  62 // Cambridge, MA 02139, USA.
  63 //
  64 // As a special exception, including FNA header files in a file,
  65 // instantiating FNA generics or templates, or linking other files
  66 // with FNA objects to produce an executable application, does not
  67 // by itself cause the resulting executable application to be covered
  68 // by the GNU General Public License. This exception does not
  69 // however invalidate any other reasons why the executable file might be
  70 // covered by the GNU Public License.
  71 // -----------------------------------------------------------------------
  72  *
  73  */
  74
  75 #ifndef _MARTE_FRESCAN_SERVERS_H_
  76 #define _MARTE_FRESCAN_SERVERS_H_
  77
  78 #include "frescan_types.h"
  79
  80 /**
  81  * frescan_servers_init() - initialize server structures
  82  *
  83  * @net: the network instance
  84  */
  85
  86 extern int frescan_servers_init(frescan_network_t net);
  87
  88 /**
  89  * frescan_servers_create() - create a sporadic server
  90  *
  91  * @net: the network instance
  92  * @params: the parameters for the server
  93  * @id: the identificator for the server as a return value
  94  *
  95  */
  96
  97 extern int frescan_servers_create(frescan_network_t net,
  98                                   const frescan_server_params_t *params,
  99                                   frescan_ss_t *id);
 100
 101 /**
 102  * frescan_servers_set_perceived() - update a sporadic server perceived data
 103  *
 104  * @net: the network instance
 105  * @params: the parameters for the server
 106  * @id: the identificator for the server
 107  *
 108  */
 109
 110 extern int frescan_servers_set_perceived(frescan_network_t net,
 111                                          const frescan_server_params_t *params,
 112                                          frescan_ss_t id);
 113
 114 /**
 115  * frescan_servers_commit_perceived() - commit sporadic server perceived data
 116  *
 117  * @net: the network instance
 118  * @params: the parameters for the server
 119  * @id: the identificator for the server
 120  *
 121  */
 122
 123 extern int frescan_servers_commit_perceived(frescan_network_t net,
 124                                             frescan_ss_t id);
 125
 126 /**
 127  * frescan_servers_update() - update a sporadic server data
 128  *
 129  * It is similar to call 'frescan_servers_set_perceived' and then
 130  * 'frescan_servers_commit_perceived'
 131  *
 132  * @net: the network instance
 133  * @params: the parameters for the server
 134  * @id: the identificator for the server
 135  *
 136  */
 137
 138 extern int frescan_servers_update(frescan_network_t net,
 139                                   const frescan_server_params_t *params,
 140                                   frescan_ss_t id);
 141
 142 /**
 143  * frescan_servers_destroy() - delete a sporadic server
 144  *
 145  * @net: the network instance
 146  * @id: the identificator for the server
 147  *
 148  */
 149
 150 extern int frescan_servers_destroy(frescan_network_t net, frescan_ss_t id);
 151
 152 /**
 153  * frescan_servers_get_data() - get a sporadic server data
 154  *
 155  * @net: the network instance
 156  * @params: the parameters of the server
 157  * @id: the identificator for the server
 158  *
 159  */
 160
 161 extern  int frescan_servers_get_data(frescan_network_t net,
 162                                      frescan_server_params_t *params,
 163                                      frescan_ss_t id);
 164
 165 /**
 166  * frescan_servers_get_current_budget() - get the current sporadic server budget
 167  *
 168  * @net: the network instance
 169  * @id: the identificator for the server
 170  * @current_budget: the current budget of the server
 171  *
 172  */
 173
 174 extern int frescan_servers_get_current_budget(frescan_network_t net,
 175                                               frescan_ss_t id,
 176                                               frescan_budget_t *current_budget);
 177
 178 /**
 179  * frescan_servers_get_highest_prio() - get the server with highest priority
 180  *
 181  * @net: the network instance
 182  * @id: the identificator for the server
 183  * @prio: the priority of that server
 184  *
 185  * If "id" is returned with a value of FRESCAN_MX_IDS,
 186  * there are no active servers.
 187  * NOTE: id=FRESCAN_MX_IDS is the identifier for fixed priority messages
 188  *
 189  */
 190
 191 extern int frescan_servers_get_highest_prio(frescan_network_t net,
 192                                             frescan_ss_t *id,
 193                                             frescan_prio_t *prio);
 194
 195 /**
 196  * frescan_servers_frame_sent() - hook to control the server budget and prio
 197  *
 198  * @net: the network instance
 199  * @id: the identificator for the server
 200  * @packet: the packet sent (with its timestamp)
 201  *
 202  * This function is called when a frame has been effectively sent through the
 203  * CAN bus and that frame is associated to a certain server. The function
 204  * decreases the capacity of the server and sets the priority to background
 205  * in case the budget is exhausted.
 206  *
 207  * NOTE: the replenishment operation is programmed using the corresponding
 208  * function at frescan_servers_replenishments module
 209  */
 210
 211 extern int frescan_servers_frame_sent(frescan_network_t net,
 212                                       frescan_ss_t id,
 213                                       frescan_packet_t *packet);
 214
 215 #endif // _MARTE_FRESCAN_SERVERS_H_