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  * See MaRTE OS license
  20  *
  21  */
  22
  23 #ifndef _MARTE_FRESCAN_H_
  24 #define _MARTE_FRESCAN_H_
  25
  26 #include <stdint.h>  // uint8_t
  27 #include <stdbool.h> // bool
  28 #include <unistd.h>  // size_t
  29
  30 typedef uint8_t frescan_network_t;
  31 typedef uint8_t frescan_node_t;
  32 typedef uint8_t frescan_channel_t;
  33 typedef uint8_t frescan_prio_t;
  34 typedef uint8_t frescan_ss_t;
  35 typedef uint32_t frescan_budget_t;
  36
  37 /**
  38  * frescan_flags_t - frescan flags
  39  *
  40  * @FRESCAN_SS: send the message using sporadic servers
  41  * @FRESCAN_FP: send the message using fixed priorities
  42  * @FRESCAN_POLL: no buffer copy, only pointer and use the ID to poll status
  43  * @FRESCAN_SYNC: no buffer copy, only pointer and block until it is sent
  44  * @FRESCAN_ASYNC: use buffer copy and return immediately
  45  */
  46
  47 typedef enum {
  48         FRESCAN_SS    = 1<<4,  // sporadic server
  49         FRESCAN_FP    = 1<<3,  // fixed priorities
  50         FRESCAN_POLL  = 1<<2,  // polling
  51         FRESCAN_SYNC  = 1<<1,  // synchronous
  52         FRESCAN_ASYNC = 1      // asynchronous
  53 } frescan_flags_t;
  54
  55 /**
  56  * frescan_send_params_t - send parameters
  57  *
  58  * @net: the network to use
  59  * @to: the node where the message shoud be sent to
  60  * @channel: the channel in 'to' where the message shoud be sent to
  61  * @flags: the flags (see frescan_flags_t)
  62  * @prio: the priority for the message if (flags & FRESCAN_FP)
  63  * @ss: the sporadic server for the message if (flags & FRESCAN_SS)
  64  */
  65
  66 typedef struct {
  67         frescan_network_t net;
  68         frescan_node_t to;
  69         frescan_channel_t channel;
  70         frescan_flags_t flags;
  71         union {
  72                 frescan_prio_t prio;
  73                 frescan_ss_t ss;
  74         };
  75 } frescan_send_params_t;
  76
  77 /**
  78  * frescan_recv_params_t - receive parameters
  79  *
  80  * @net: the network to use
  81  * @channel: the channel from which we want to extract a message
  82  * @flags: FRESCAN_SYNC/ASYNC
  83  */
  84
  85 typedef struct {
  86         frescan_network_t net;
  87         frescan_channel_t channel;
  88         frescan_flags_t flags;
  89 } frescan_recv_params_t;
  90
  91 /**
  92  * frescan_init_params_t - initialization parameters
  93  *
  94  * @net: network to initialize (minor number ie: /dev/can0 -> 0)
  95  * @node: set the local node identificator
  96  * @tx_fp_max_prio: maximum number of priorities for the fixed priority
  97  *                  transmission queues. (prio = 0 .. max_prio - 1)
  98  * @rx_num_of_channels: number of rx channels (0 .. rx_num_of_channels - 1)
  99  * @rx_channel_max_prio: array (range rx_num_of_channels) saying the number
 100  *                       of priorities for each channel. If this parameter is
 101  *                       NULL tx_fp_max_prio will be used for all queues.
 102  */
 103
 104 typedef struct {
 105         frescan_network_t net;
 106         frescan_node_t node;
 107         uint32_t tx_fp_max_prio;
 108         uint32_t rx_num_of_channels;
 109         uint32_t *rx_channel_max_prio;
 110 } frescan_init_params_t;
 111
 112 /**
 113  * frescan_init - initializes the network and the internal structures
 114  *
 115  * @params: the initialization parameters
 116  */
 117
 118 int frescan_init(frescan_init_params_t *params);
 119
 120 /**
 121  * frescan_send - send a message
 122  *
 123  * @params: the parameters needed by the protocol to send the message
 124  * @msg: the message buffer
 125  * @size: the size of the message
 126  *
 127  * This is one of the main functions of the protocol and it provides the
 128  * means to send a message through the protocol stack.
 129  */
 130
 131 int frescan_send(const frescan_send_params_t *params,
 132                  const uint8_t *msg,
 133                  const size_t size);
 134
 135 /**
 136  * frescan_recv - receive a message
 137  *
 138  * @params: the parameters needed by the protocol to receive the message
 139  * @msg: the message buffer
 140  * @size: the size of the message buffer
 141  * @recv_bytes: the number of bytes received
 142  * @from: the node that sent the message
 143  * @prio: the priority of the message
 144  *
 145  * This is one of the main functions of the protocol and it provides the
 146  * means to receive a message through the protocol stack.
 147  */
 148
 149 int frescan_recv(const frescan_recv_params_t *params,
 150                  uint8_t *msg,
 151                  const size_t size,
 152                  size_t *recv_bytes,
 153                  frescan_node_t *from,
 154                  frescan_prio_t *prio);
 155
 156 #endif // _MARTE_FRESCAN_H_