components/common/inc/rand_data.h

   1 /******************************************************************************
   2  @file rand_data.h
   3
   4  @brief TIMAC 2.0 API Pseudo-random number generator
   5
   6  Group: WCS LPC
   7  $Target Devices: Linux: AM335x, Embedded Devices: CC1310, CC1350, CC1352$
   8
   9  ******************************************************************************
  10  $License: BSD3 2016 $
  11
  12    Copyright (c) 2015, Texas Instruments Incorporated
  13    All rights reserved.
  14
  15    Redistribution and use in source and binary forms, with or without
  16    modification, are permitted provided that the following conditions
  17    are met:
  18
  19    *  Redistributions of source code must retain the above copyright
  20       notice, this list of conditions and the following disclaimer.
  21
  22    *  Redistributions in binary form must reproduce the above copyright
  23       notice, this list of conditions and the following disclaimer in the
  24       documentation and/or other materials provided with the distribution.
  25
  26    *  Neither the name of Texas Instruments Incorporated nor the names of
  27       its contributors may be used to endorse or promote products derived
  28       from this software without specific prior written permission.
  29
  30    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  31    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  32    THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  33    PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  34    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  35    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  36    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  37    OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  38    WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  39    OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  40    EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  41  ******************************************************************************
  42  $Release Name: TI-15.4Stack Linux x64 SDK$
  43  $Release Date: Sept 27, 2017 (2.04.00.13)$
  44  *****************************************************************************/
  45
  46 #if !defined(RAND_DATA_H)
  47 #define RAND_DATA_H
  48
  49 #include <stdint.h>
  50 #include <stddef.h>
  51
  52 /*
  53  * Overview
  54  * ========
  55  *
  56  * This is a data generator it is used to create random-ish
  57  * data for the purpose of testing a communcations channel.
  58  * it is not cryptographically strong, and it is not intended
  59  * to be used for that purpose.
  60  *
  61  * Rules
  62  * =====
  63  * <pre>
  64  * Rule #1   Both sides must start with the same *SEED* value.
  65  * Rule #2   The seed value is an integer, of any value.
  66  *
  67  * Rule #3 To transmit, call RANDDATA_Get() (n-times) for (n-bytes)
  68  * Rule #4 transmit and receive your data
  69  * Rule #5 Call RAND_DATA_Verify() to verify the data is correct.
  70  * </pre>
  71  * NOTE: you can have two seperate programs on two seperate computers
  72  *       on opposite sides of the world... they do not need to
  73  *       share this specific data structure to make it work.
  74  *
  75  * how does this work?
  76  * -------------------
  77  * Mathmatically it is a Linear congruential generator
  78  * https://en.wikipedia.org/wiki/Linear_congruential_generator
  79  * http://stackoverflow.com/questions/8569113/why-1103515245-is-used-in-rand
  80  */
  81
  82 /*!
  83  * @struct rand_data_one
  84  *
  85  * @brief a single random stream generator
  86  */
  87 struct rand_data_one {
  88     /*! number of random values read */
  89     uint32_t cnt;
  90     /*! next seed value */
  91     uint32_t next;
  92 };
  93
  94 /*!
  95  * @struct a pair of random stream generators, typically used as a tx/rx pair
  96  */
  97 struct rand_data_pair {
  98     /*! transmiter generator */
  99     struct rand_data_one tx;
 100     /*! receiver generator */
 101     struct rand_data_one rx;
 102 };
 103
 104 /*!
 105  * @brief Initialize a pair of data generator
 106  * @param pRDP - the pair to initialize
 107  * @param seed - used for both tx and rx
 108  */
 109 void RAND_DATA_initPair(struct rand_data_pair *pRDP, uint32_t seed);
 110
 111 /*!
 112  * @brief Initialize a single data generator
 113  * @param pRDP - the generator to initialize
 114  * @param seed - seed value for the generator
 115  */
 116 void RAND_DATA_initOne(struct rand_data_one *pRD1, uint32_t seed);
 117
 118 /*!
 119  * @brief Generate the next byte
 120  * @param pRD1 - a single random number generator
 121  *
 122  * @returns next byte from the generator.
 123  */
 124
 125 uint8_t RAND_DATA_nextByte(struct rand_data_one *pRD1);
 126
 127 /*!
 128  * @brief in a pair, return the next tx byte
 129  * @param pRDP - pointer to the pair to use
 130  * @returns byte value from the generator.
 131  */
 132 uint8_t RAND_DATA_nextTx(struct rand_data_pair *pRDP);
 133
 134 /*!
 135  * @brief in a pair, return the next rx byte
 136  * @param pRDP - pointer to the pair to use
 137  * @returns byte value from the generator.
 138  */
 139 uint8_t RAND_DATA_nextRx(struct rand_data_pair *pRDP);
 140
 141 /*!
 142  * @brief Generate a buffer full of data
 143  * @param pRD1 - a single generator to use
 144  * @param pBuf - the buffer to use to write
 145  * @param n - the number of bytes to generate
 146  */
 147 void    RAND_DATA_generateBuf(struct rand_data_one *pRD1,
 148                                uint8_t *pBuf, size_t n);
 149
 150 /*!
 151  * @brief Generate a buffer full of data
 152  * @param pRD1 - a single generator to use
 153  * @param pBuf - the buffer to use to write
 154  * @param n - the number of bytes to verify
 155  */
 156 int     RAND_DATA_verifyBuf(struct rand_data_one *pRD1,
 157                              const uint8_t *pBuf, size_t n);
 158
 159 /*!
 160  * @brief Generate (from a pair) the transmit stream to a bufer
 161  * @param pRDP - the pair to use
 162  * @param pbuf - the buffer to generate into
 163  * @param n - the number of bytes to generate
 164  *
 165  */
 166 void RAND_DATA_txGenerate(struct rand_data_pair *pRDP,
 167                            uint8_t *pBuf, size_t n);
 168
 169 /*!
 170  * @brief Generate (from a pair) the receive stream to verify
 171  * @param pRDP - the pair to use
 172  * @param pbuf - the buffer to verify
 173  * @param n - the number of bytes to verify
 174  *
 175  */
 176 int  RAND_DATA_rxVerify(struct rand_data_pair *pRDP, uint8_t *pBuf, size_t n);
 177
 178 #endif
 179
 180 /*
 181  *  ========================================
 182  *  Texas Instruments Micro Controller Style
 183  *  ========================================
 184  *  Local Variables:
 185  *  mode: c
 186  *  c-file-style: "bsd"
 187  *  tab-width: 4
 188  *  c-basic-offset: 4
 189  *  indent-tabs-mode: nil
 190  *  End:
 191  *  vim:set  filetype=c tabstop=4 shiftwidth=4 expandtab=true
 192  */
 193