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 - 2008 FRESCOR consortium partners:
  23  *
  24  *    Universidad de Cantabria,              SPAIN
  25  *    University of York,                    UK
  26  *    Scuola Superiore Sant'Anna,            ITALY
  27  *    Kaiserslautern University,             GERMANY
  28  *    Univ. Politécnica  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 for a link to partners' websites
  37  *
  38  *           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  *  This file is part of FRESCAN
  44  *
  45  *  FRESCAN is free software; you can  redistribute it and/or  modify
  46  *  it under the terms of  the GNU General Public License as published by
  47  *  the Free Software Foundation;  either  version 2, or (at  your option)
  48  *  any later version.
  49  *
  50  *  FRESCAN  is distributed  in  the hope  that  it  will  be useful,  but
  51  *  WITHOUT  ANY  WARRANTY;     without  even the   implied   warranty  of
  52  *  MERCHANTABILITY  or  FITNESS FOR  A  PARTICULAR PURPOSE. See  the  GNU
  53  *  General Public License for more details.
  54  *
  55  *  You should have  received a  copy of  the  GNU  General Public License
  56  *  distributed  with  FRESCAN;  see file COPYING.   If not,  write to the
  57  *  Free Software  Foundation,  59 Temple Place  -  Suite 330,  Boston, MA
  58  *  02111-1307, USA.
  59  *
  60  * As a special exception, including FRESCAN header files in a file,
  61  * instantiating FRESCAN generics or templates, or linking other files
  62  * with FRESCAN objects to produce an executable application, does not
  63  * by itself cause the resulting executable application to be covered
  64  * by the GNU General Public License. This exception does not
  65  * however invalidate any other reasons why the executable file might be
  66  * covered by the GNU Public License.
  67  * -----------------------------------------------------------------------
  68  *
  69  */
  70
  71 #ifndef _MARTE_FRESCAN_SERVERS_H_
  72 #define _MARTE_FRESCAN_SERVERS_H_
  73
  74 #include "frescan.h"         // frescan_prio_t, frescan_ss_t
  75 #include "frescan_packets.h" // frescan_packet_t
  76 #include "frescan_data.h"
  77
  78 /**
  79  * frescan_servers_init() - initialize server structures
  80  *
  81  * @net: the network instance
  82  */
  83
  84 extern int frescan_servers_init(frescan_network_t net);
  85
  86 /**
  87  * frescan_servers_create() - create a sporadic server
  88  *
  89  * @net: the network instance
  90  * @params: the parameters for the server
  91  * @id: the identificator for the server as a return value
  92  *
  93  */
  94
  95 extern int frescan_servers_create(frescan_network_t net,
  96                                   const frescan_server_params_t *params,
  97                                   frescan_ss_t *id);
  98
  99 /**
 100  * frescan_servers_set_perceived() - update a sporadic server perceived data
 101  *
 102  * @net: the network instance
 103  * @params: the parameters for the server
 104  * @id: the identificator for the server
 105  *
 106  */
 107
 108 extern int frescan_servers_set_perceived(frescan_network_t net,
 109                                          const frescan_server_params_t *params,
 110                                          frescan_ss_t id);
 111
 112 /**
 113  * frescan_servers_commit_perceived() - commit sporadic server perceived data
 114  *
 115  * @net: the network instance
 116  * @params: the parameters for the server
 117  * @id: the identificator for the server
 118  *
 119  */
 120
 121 extern int frescan_servers_commit_perceived(frescan_network_t net,
 122                                             frescan_ss_t id);
 123
 124 /**
 125  * frescan_servers_update() - update a sporadic server data
 126  *
 127  * It is similar to call 'frescan_servers_set_perceived' and then
 128  * 'frescan_servers_commit_perceived'
 129  *
 130  * @net: the network instance
 131  * @params: the parameters for the server
 132  * @id: the identificator for the server
 133  *
 134  */
 135
 136 extern int frescan_servers_update(frescan_network_t net,
 137                                   const frescan_server_params_t *params,
 138                                   frescan_ss_t id);
 139
 140 /**
 141  * frescan_servers_destroy() - delete a sporadic server
 142  *
 143  * @net: the network instance
 144  * @id: the identificator for the server
 145  *
 146  */
 147
 148 extern int frescan_servers_destroy(frescan_network_t net, frescan_ss_t id);
 149
 150 /**
 151  * frescan_servers_get_data() - get a sporadic server data
 152  *
 153  * @net: the network instance
 154  * @params: the parameters of the server
 155  * @id: the identificator for the server
 156  *
 157  */
 158
 159 extern  int frescan_servers_get_data(frescan_network_t net,
 160                                      frescan_server_params_t *params,
 161                                      frescan_ss_t id);
 162
 163 /**
 164  * frescan_servers_get_current_budget() - get the current sporadic server budget
 165  *
 166  * @net: the network instance
 167  * @id: the identificator for the server
 168  * @current_budget: the current budget of the server
 169  *
 170  */
 171
 172 extern int frescan_servers_get_current_budget(frescan_network_t net,
 173                                               frescan_ss_t id,
 174                                               frescan_budget_t *current_budget);
 175
 176 /**
 177  * frescan_servers_get_highest_prio() - get the server with highest priority
 178  *
 179  * @net: the network instance
 180  * @id: the identificator for the server
 181  * @prio: the priority of that server
 182  *
 183  * If "id" is returned with a value of FRESCAN_MX_IDS,
 184  * there are no active servers.
 185  * NOTE: id=FRESCAN_MX_IDS is the identifier for fixed priority messages
 186  *
 187  */
 188
 189 extern int frescan_servers_get_highest_prio(frescan_network_t net,
 190                                             frescan_ss_t *id,
 191                                             frescan_prio_t *prio);
 192
 193 /**
 194  * frescan_servers_frame_sent() - hook to control the server budget and prio
 195  *
 196  * @net: the network instance
 197  * @id: the identificator for the server
 198  * @packet: the packet sent (with its timestamp)
 199  *
 200  * This function is called when a frame has been effectively sent through the
 201  * CAN bus and that frame is associated to a certain server. The function
 202  * decreases the capacity of the server and sets the priority to background
 203  * in case the budget is exhausted.
 204  *
 205  * NOTE: the replenishment operation is programmed using the corresponding
 206  * function at frescan_servers_replenishments module
 207  */
 208
 209 extern int frescan_servers_frame_sent(frescan_network_t net,
 210                                       frescan_ss_t id,
 211                                       frescan_packet_t *packet);
 212
 213 #endif // _MARTE_FRESCAN_SERVERS_H_