src_frescan/frescan_packets.h

   1 /*!
   2  * @file frescan_packets.h
   3  *
   4  * @brief FRESCAN packets definition and pool
   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 packets definition and functions to
  16  * allocate and free them from a global pool of packets statically
  17  * preallocated.
  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_PACKETS_H_
  72 #define _MARTE_FRESCAN_PACKETS_H_
  73
  74 #include <time.h>             // struct timespec
  75 #include <stdint.h>           // uint8_t ...
  76 #include "frescan.h"          // frescan_flags_t
  77 #include <misc/linux_list.h>  // struct list_head
  78 #include <drivers/can.h>      // can_frame_t
  79
  80 /**
  81  * frescan_packet_t - a frescan packet
  82  *
  83  * This structure is very important and it is used to store a FRESCAN packet.
  84  * As we support fragmentation, a FRESCAN packet can be composed of several
  85  * CAN frames. This 'frescan_packet_t' structure is used in two main cases:
  86  *
  87  * 1.- When we are sending data. In this case, the buffer pointers store the
  88  *     real data we want to sent and we use a 'buffer_read_pointer' to know
  89  *     how many bytes of the buffer we already sent. In 'frame', we store the
  90  *     last sent frame (with the corresponding CAN id fields). We will have
  91  *     to update the fragmentation fields as long as we send more packets.
  92  *     The 'fifo_list' is used to chained frescan packets of the same priority
  93  *     or that belong to the same sporadic server. Finally, 'flags', specify
  94  *     if we are sending ASYNC or SYNC. If we are sending SYNC the buffer
  95  *     pointers are pointing to the buffer sent by the user (zero copying),
  96  *     while if we use ASYNC, a copy of the data is done to the buffer.
  97  *
  98  * 2.- When we are receiving data, we only use 'frame' and 'fifo_list' fields.
  99  *     The IRQ handler of the chip allocates a CAN frame and calls to our hook.
 100  *     We store the pointer to that frame in 'frame' and we make a chain with
 101  *     frames of the same message (using the fragmentation fields). When we
 102  *     have all of them, we move the packet list to the corresponding
 103  *     receiving channel to wait for the user to perform a receive operation
 104  *     when we will copy the data and free both the packets and the frames.
 105  *
 106  * @flags: to know if the packet is to be sent SYNC or ASYNC, FP or SERVER...
 107  * @frame: pointer to the last sent frame or the received frame
 108  * @fifo_list: list to put several packets together
 109  * @msg_list: list to put packets of the same message together
 110  * @buffer_head: pointer to first byte of the buffer that is going to be sent
 111  * @buffer_read_pointer: pointer to the part of the buffer being read
 112  * @buffer_pending_bytes: bytes waiting to be sent
 113  * @timestamp: time when the packet was enqueued (activation time)
 114  * @pool_pos: position in the packets pool to know how to free it
 115  *
 116  * NOTE: the buffers could also be used on the receiving part to support
 117  * sequential reads, instead of reading the whole message at once.
 118  *
 119  */
 120
 121 typedef struct {
 122         frescan_flags_t flags;
 123         struct can_frame_t *frame;
 124         struct list_head fifo_list;
 125         struct list_head msg_list;
 126         uint8_t *buffer_head;         // only for sending packets
 127         uint8_t *buffer_read_pointer; // only for sending packets
 128         uint32_t buffer_pending_bytes; // only for sending packets
 129         struct timespec timestamp;
 130         int pool_pos;
 131 } frescan_packet_t;
 132
 133 /**
 134  * frescan_packets_init
 135  *
 136  * Initializes a pool of packets that will be managed internally
 137  */
 138
 139 extern int frescan_packets_init();
 140
 141 /**
 142  * frescan_packets_alloc
 143  *
 144  * Allocates a frame from the pool of packets. On error it returns NULL
 145  */
 146
 147 extern frescan_packet_t *frescan_packets_alloc();
 148
 149 /**
 150  * frescan_packets_free
 151  *
 152  * Frees a frame and returns it to the pool of packets.
 153  */
 154
 155 extern int frescan_packets_free(frescan_packet_t *packet);
 156
 157 #endif // _MARTE_FRESCAN_PACKETS_H_