src_frescan/frescan.h

   1 /*!
   2  * @file frescan.h
   3  *
   4  * @brief interface of the FRESCAN protocol
   5  *
   6  * @version 0.01
   7  *
   8  * @date 20-Feb-2008
   9  *
  10  * @author
  11  *      Daniel Sangorrin
  12  *
  13  * @comments
  14  *
  15  * This file contains the interface to the FRESCAN protocol
  16  *
  17  * @license
  18  *
  19  * -----------------------------------------------------------------------
  20  *  Copyright (C) 2006 - 2008 FRESCOR consortium partners:
  21  *
  22  *    Universidad de Cantabria,              SPAIN
  23  *    University of York,                    UK
  24  *    Scuola Superiore Sant'Anna,            ITALY
  25  *    Kaiserslautern University,             GERMANY
  26  *    Univ. Politécnica  Valencia,           SPAIN
  27  *    Czech Technical University in Prague,  CZECH REPUBLIC
  28  *    ENEA                                   SWEDEN
  29  *    Thales Communication S.A.              FRANCE
  30  *    Visual Tools S.A.                      SPAIN
  31  *    Rapita Systems Ltd                     UK
  32  *    Evidence                               ITALY
  33  *
  34  *    See http://www.frescor.org for a link to partners' websites
  35  *
  36  *           FRESCOR project (FP6/2005/IST/5-034026) is funded
  37  *        in part by the European Union Sixth Framework Programme
  38  *        The European Union is not liable of any use that may be
  39  *        made of this code.
  40  *
  41  *  This file is part of FRESCAN
  42  *
  43  *  FRESCAN is free software; you can  redistribute it and/or  modify
  44  *  it under the terms of  the GNU General Public License as published by
  45  *  the Free Software Foundation;  either  version 2, or (at  your option)
  46  *  any later version.
  47  *
  48  *  FRESCAN  is distributed  in  the hope  that  it  will  be useful,  but
  49  *  WITHOUT  ANY  WARRANTY;     without  even the   implied   warranty  of
  50  *  MERCHANTABILITY  or  FITNESS FOR  A  PARTICULAR PURPOSE. See  the  GNU
  51  *  General Public License for more details.
  52  *
  53  *  You should have  received a  copy of  the  GNU  General Public License
  54  *  distributed  with  FRESCAN;  see file COPYING.   If not,  write to the
  55  *  Free Software  Foundation,  59 Temple Place  -  Suite 330,  Boston, MA
  56  *  02111-1307, USA.
  57  *
  58  * As a special exception, including FRESCAN header files in a file,
  59  * instantiating FRESCAN generics or templates, or linking other files
  60  * with FRESCAN objects to produce an executable application, does not
  61  * by itself cause the resulting executable application to be covered
  62  * by the GNU General Public License. This exception does not
  63  * however invalidate any other reasons why the executable file might be
  64  * covered by the GNU Public License.
  65  * -----------------------------------------------------------------------
  66  *
  67  */
  68
  69 #ifndef _MARTE_FRESCAN_H_
  70 #define _MARTE_FRESCAN_H_
  71
  72 #include <stdint.h>  // uint8_t
  73 #include <stdbool.h> // bool
  74 #include <unistd.h>  // size_t
  75
  76 typedef uint8_t frescan_network_t;
  77 typedef uint8_t frescan_node_t;
  78 typedef uint8_t frescan_channel_t;
  79 typedef uint8_t frescan_prio_t;
  80 typedef uint8_t frescan_ss_t;
  81 typedef uint32_t frescan_budget_t;
  82
  83 /**
  84  * frescan_flags_t - frescan flags
  85  *
  86  * @FRESCAN_SS: send the message using sporadic servers
  87  * @FRESCAN_FP: send the message using fixed priorities
  88  * @FRESCAN_POLL: no buffer copy, only pointer and use the ID to poll status
  89  * @FRESCAN_SYNC: no buffer copy, only pointer and block until it is sent
  90  * @FRESCAN_ASYNC: use buffer copy and return immediately
  91  */
  92
  93 typedef enum {
  94         FRESCAN_SS    = 1<<4,  // sporadic server
  95         FRESCAN_FP    = 1<<3,  // fixed priorities
  96         FRESCAN_POLL  = 1<<2,  // polling
  97         FRESCAN_SYNC  = 1<<1,  // synchronous
  98         FRESCAN_ASYNC = 1      // asynchronous
  99 } frescan_flags_t;
 100
 101 /**
 102  * frescan_send_params_t - send parameters
 103  *
 104  * @net: the network to use
 105  * @to: the node where the message shoud be sent to
 106  * @channel: the channel in 'to' where the message shoud be sent to
 107  * @flags: the flags (see frescan_flags_t)
 108  * @prio: the priority for the message if (flags & FRESCAN_FP)
 109  * @ss: the sporadic server for the message if (flags & FRESCAN_SS)
 110  */
 111
 112 typedef struct {
 113         frescan_network_t net;
 114         frescan_node_t to;
 115         frescan_channel_t channel;
 116         frescan_flags_t flags;
 117         union {
 118                 frescan_prio_t prio;
 119                 frescan_ss_t ss;
 120         };
 121 } frescan_send_params_t;
 122
 123 /**
 124  * frescan_recv_params_t - receive parameters
 125  *
 126  * @net: the network to use
 127  * @channel: the channel from which we want to extract a message
 128  * @flags: FRESCAN_SYNC/ASYNC
 129  */
 130
 131 typedef struct {
 132         frescan_network_t net;
 133         frescan_channel_t channel;
 134         frescan_flags_t flags;
 135 } frescan_recv_params_t;
 136
 137 /**
 138  * frescan_init_params_t - initialization parameters
 139  *
 140  * @net: network to initialize (minor number ie: /dev/can0 -> 0)
 141  * @node: set the local node identificator
 142  * @tx_fp_max_prio: maximum number of priorities for the fixed priority
 143  *                  transmission queues. (prio = 0 .. max_prio - 1)
 144  * @rx_num_of_channels: number of rx channels (0 .. rx_num_of_channels - 1)
 145  * @rx_channel_max_prio: array (range rx_num_of_channels) saying the number
 146  *                       of priorities for each channel. If this parameter is
 147  *                       NULL tx_fp_max_prio will be used for all queues.
 148  */
 149
 150 typedef struct {
 151         frescan_network_t net;
 152         frescan_node_t node;
 153         uint32_t tx_fp_max_prio;
 154         uint32_t rx_num_of_channels;
 155         uint32_t *rx_channel_max_prio;
 156 } frescan_init_params_t;
 157
 158 /**
 159  * frescan_init - initializes the network and the internal structures
 160  *
 161  * @params: the initialization parameters
 162  */
 163
 164 int frescan_init(frescan_init_params_t *params);
 165
 166 /**
 167  * frescan_send - send a message
 168  *
 169  * @params: the parameters needed by the protocol to send the message
 170  * @msg: the message buffer
 171  * @size: the size of the message
 172  *
 173  * This is one of the main functions of the protocol and it provides the
 174  * means to send a message through the protocol stack.
 175  */
 176
 177 int frescan_send(const frescan_send_params_t *params,
 178                  const uint8_t *msg,
 179                  const size_t size);
 180
 181 /**
 182  * frescan_recv - receive a message
 183  *
 184  * @params: the parameters needed by the protocol to receive the message
 185  * @msg: the message buffer
 186  * @size: the size of the message buffer
 187  * @recv_bytes: the number of bytes received
 188  * @from: the node that sent the message
 189  * @prio: the priority of the message
 190  *
 191  * This is one of the main functions of the protocol and it provides the
 192  * means to receive a message through the protocol stack.
 193  */
 194
 195 int frescan_recv(const frescan_recv_params_t *params,
 196                  uint8_t *msg,
 197                  const size_t size,
 198                  size_t *recv_bytes,
 199                  frescan_node_t *from,
 200                  frescan_prio_t *prio);
 201
 202 #endif // _MARTE_FRESCAN_H_