1

/*

     2

 * Copyright (c) 2002,2016 Mario de Sousa (msousa@fe.up.pt)

     3

 *

     4

 * This file is part of the Modbus library for Beremiz and matiec.

     5

 *

     6

 * This Modbus library is free software: you can redistribute it and/or modify

     7

 * it under the terms of the GNU Lesser General Public License as published by

     8

 * the Free Software Foundation, either version 3 of the License, or

     9

 * (at your option) any later version.

    10

 *

    11

 * This program is distributed in the hope that it will be useful, but

    12

 * WITHOUT ANY WARRANTY; without even the implied warranty of

    13

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser 

    14

 * General Public License for more details.

    15

 *

    16

 * You should have received a copy of the GNU Lesser General Public License

    17

 * along with this Modbus library.  If not, see <http://www.gnu.org/licenses/>.

    18

 *

    19

 * This code is made available on the understanding that it will not be

    20

 * used in safety-critical situations without a full and competent review.

    21

 */

    22

    23

    24

    25

 /* Data structures used by the modbus protocols... */

    26

    27

    28

#ifndef __MODBUS_DS_UTIL_H

    29

#define __MODBUS_DS_UTIL_H

    30

    31

    32

#include "mb_types.h"  /* get the data types */

    33

    34

/**************************************/

    35

/**                                  **/

    36

/** A data structure - linear buffer **/

    37

/**                                  **/

    38

/**************************************/

    39

    40

/* An unbounded FIFO data structure.

    41

 *

    42

 * The user/caller writes and reads directly from the data structure's buffer,

    43

 * which eliminates slow copying of bytes between the user's and the structure's

    44

 * local memory.

    45

 *

    46

 * The data structure stores the current data linearly in a single memory array,

    47

 * i.e. the current data is stored from start to finish from a low address

    48

 * to a high address, and does *not* circle back to the bottom of the address

    49

 * space as is usual in a circular buffer. This allows the user/caller to

    50

 * pass the structure's own byte array on to other functions such as

    51

 * read() and write() for file operations.

    52

 *

    53

 * The FIFO is implemented by allocating more memory than the maximum number

    54

 * of bytes it will ever hold, and using the extra bytes at the top of the

    55

 * array as the bottom data bytes are released. When we run out of extra bytes,

    56

 * (actually, when the number of un-used bytes at the beginning is larger than

    57

 * a configured maximum), the whole data is moved down, freeing once again the

    58

 * extra bytes at the top of the array.

    59

 *

    60

 * Remember that we can optimize the data structure so that whenever it becomes

    61

 * empty, we can reset it to start off at the bottom of the byte array, i.e. we

    62

 * can set the start = end = 0; instead of simply setting the start = end, which

    63

 * may point to any position in the array.

    64

 *

    65

 * Taking the above into consideration, it would probably be a little more efficient

    66

 * to implement it as a circular buffer with an additional linearize() function

    67

 * the user could call whenever (s)he required the data to be stored linearly.

    68

 * Nevertheless, since it has already been implemented as a linear buffer, and since

    69

 * under normal circumstances the start and end pointers will be reset to 0 quite

    70

 * often (and therefore we get no additional benefit under normal circumstances),

    71

 * we will leave it as it is for the time being...

    72

 *

    73

 *

    74

 * The user is expected to call

    75

 *   lb_init() -> to initialize the structure

    76

 *   lb_done() -> to free the data structure's memory

    77

 *

    78

 * The user can store data starting off from...

    79

 *   lb_free() -> pointer to address of free memory

    80

 *   lb_free_count() -> number of free bytes available

    81

 * and then call

    82

 *   lb_data_add()

    83

 * to add the data to the data structure

    84

 *

    85

 * Likewise, the user can read the data directly from

    86

 *   lb_data() -> pointer to address of data location

    87

 *   lb_free_count() -> number of data bytes available

    88

 * and free the data using

    89

 *   lb_data_purge()

    90

 * to remove the data from the data structure

    91

 */

    92

    93

    94

typedef struct {

    95

        u8 *data;

    96

        int data_size;      /* size of the *data buffer                   */

    97

        int data_start;     /* offset within *data were valid data starts */

    98

        int data_end;       /* offset within *data were valid data ends   */

    99

        int max_data_start; /* optimization parameter! When should it be normalised? */

   100

        } lb_buf_t;

   101

   102

/* NOTE: lb = Linear Buffer */

   103

   104

static inline u8 *lb_init(lb_buf_t *buf, int size, int max_data_start) {

   105

  if (size <= 0)

   106

    return NULL;

   107

   108

  if (max_data_start >= size)

   109

    max_data_start = size - 1;

   110

   111

  buf->data_size  = size;

   112

  buf->data_start = 0;

   113

  buf->data_end   = 0;

   114

  buf->max_data_start = max_data_start;

   115

  buf->data = (u8 *)malloc(size);

   116

  return buf->data;

   117

}

   118

   119

static inline void lb_done(lb_buf_t *buf) {

   120

  free(buf->data);

   121

  buf->data = NULL;

   122

}

   123

   124

static inline u8 *lb_normalize(lb_buf_t *buf) {

   125

  return (u8 *)memmove(buf->data,

   126

                       buf->data + buf->data_start,

   127

                       buf->data_end - buf->data_start);

   128

}

   129

   130

static inline u8 *lb_data(lb_buf_t *buf) {

   131

  return buf->data + buf->data_start;

   132

}

   133

   134

static inline int lb_data_count(lb_buf_t *buf) {

   135

  return buf->data_end - buf->data_start;

   136

}

   137

   138

static inline void lb_data_add(lb_buf_t *buf, int count) {

   139

  if ((buf->data_end += count) >= buf->data_size)

   140

    buf->data_end = buf->data_size - 1;

   141

}

   142

   143

static inline u8 *lb_data_purge(lb_buf_t *buf, int count) {

   144

  buf->data_start += count;

   145

  if (buf->data_start > buf->data_end)

   146

    buf->data_start = buf->data_end;

   147

   148

  if ((buf->data_end == buf->data_size) || (buf->data_start >= buf->max_data_start))

   149

    return lb_normalize(buf);

   150

   151

  return buf->data + buf->data_start;

   152

}

   153

   154

static inline void lb_data_purge_all(lb_buf_t *buf) {

   155

  buf->data_start = buf->data_end = 0;

   156

}

   157

   158

static inline u8 *lb_free(lb_buf_t *buf) {

   159

  return buf->data + buf->data_end;

   160

}

   161

   162

static inline int lb_free_count(lb_buf_t *buf) {

   163

  return buf->data_size - buf->data_end;

   164

}

   165

   166

   167

   168

   169

#endif  /* __MODBUS_DS_UTIL_H */