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

        int marked_for_purge; /* Number of bytes to be deleted in next call to lb_data_purge() */

   101

        } lb_buf_t;

   102

   103

/* NOTE: lb = Linear Buffer */

   104

   105

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

   106

  if (size <= 0)

   107

    return NULL;

   108

   109

  if (max_data_start >= size)

   110

    max_data_start = size - 1;

   111

   112

  buf->data_size  = size;

   113

  buf->data_start = 0;

   114

  buf->data_end   = 0;

   115

  buf->marked_for_purge = 0;

   116

  buf->max_data_start = max_data_start;

   117

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

   118

  return buf->data;

   119

}

   120

   121

static inline void lb_done(lb_buf_t *buf) {

   122

  free(buf->data);

   123

  buf->data = NULL;

   124

}

   125

   126

static inline u8 *lb_normalize(lb_buf_t *buf) {

   127

  u8 *ptr = (u8 *)memmove(buf->data,

   128

                          buf->data + buf->data_start,

   129

                          buf->data_end - buf->data_start);

   130

  buf->data_end -= buf->data_start;

   131

  buf->data_start = 0;

   132

  return ptr;

   133

}

   134

   135

static inline u8 *lb_data(lb_buf_t *buf) {

   136

  return buf->data + buf->data_start;

   137

}

   138

   139

static inline int lb_data_count(lb_buf_t *buf) {

   140

  return buf->data_end - buf->data_start;

   141

}

   142

   143

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

   144

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

   145

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

   146

}

   147

   148

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

   149

  buf->marked_for_purge += count;

   150

}

   151

   152

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

   153

  buf->data_start += count + buf->marked_for_purge;

   154

  buf->marked_for_purge = 0;

   155

   156

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

   157

    buf->data_start = buf->data_end = 0; // no bytes in buffer, might just as well normalize it

   158

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

   159

    return lb_normalize(buf);

   160

   161

  return buf->data + buf->data_start;

   162

}

   163

   164

static inline void lb_data_purge_all(lb_buf_t *buf) {

   165

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

   166

  buf->marked_for_purge = 0;

   167

}

   168

   169

static inline u8 *lb_free(lb_buf_t *buf) {

   170

  return buf->data + buf->data_end;

   171

}

   172

   173

static inline int lb_free_count(lb_buf_t *buf) {

   174

  return buf->data_size - buf->data_end;

   175

}

   176

   177

   178

   179

   180

#endif  /* __MODBUS_DS_UTIL_H */