LPCOpen Platform  v1.03
LPCOpen Platform for NXP LPC Microcontrollers
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
lib_math.c
Go to the documentation of this file.
1 /*
2 *********************************************************************************************************
3 * uC/LIB
4 * CUSTOM LIBRARY MODULES
5 *
6 * (c) Copyright 2004-2011; Micrium, Inc.; Weston, FL
7 *
8 * All rights reserved. Protected by international copyright laws.
9 *
10 * uC/LIB is provided in source form to registered licensees ONLY. It is
11 * illegal to distribute this source code to any third party unless you receive
12 * written permission by an authorized Micrium representative. Knowledge of
13 * the source code may NOT be used to develop a similar product.
14 *
15 * Please help us continue to provide the Embedded community with the finest
16 * software available. Your honesty is greatly appreciated.
17 *
18 * You can contact us at www.micrium.com.
19 *********************************************************************************************************
20 */
21 
22 /*
23 *********************************************************************************************************
24 *
25 * MATHEMATIC OPERATIONS
26 *
27 * Filename : lib_math.c
28 * Version : V1.35.00
29 * Programmer(s) : SR
30 * ITJ
31 *********************************************************************************************************
32 * Note(s) : (1) NO compiler-supplied standard library functions are used in library or product software.
33 *
34 * (a) ALL standard library functions are implemented in the custom library modules :
35 *
36 * (1) <Custom Library Directory>\lib_*.*
37 *
38 * (2) <Custom Library Directory>\Ports<cpu><compiler>\lib*_a.*
39 *
40 * where
41 * <Custom Library Directory> directory path for custom library software
42 * <cpu> directory name for specific processor (CPU)
43 * <compiler> directory name for specific compiler
44 *
45 * (b) Product-specific library functions are implemented in individual products.
46 *
47 *********************************************************************************************************
48 * Notice(s) : (1) The Institute of Electrical and Electronics Engineers and The Open Group, have given
49 * us permission to reprint portions of their documentation. Portions of this text are
50 * reprinted and reproduced in electronic form from the IEEE Std 1003.1, 2004 Edition,
51 * Standard for Information Technology -- Portable Operating System Interface (POSIX),
52 * The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute
53 * of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any
54 * discrepancy between these versions and the original IEEE and The Open Group Standard,
55 * the original IEEE and The Open Group Standard is the referee document. The original
56 * Standard can be obtained online at http://www.opengroup.org/unix/online.html.
57 *********************************************************************************************************
58 */
59 
60 
61 /*
62 *********************************************************************************************************
63 * INCLUDE FILES
64 *********************************************************************************************************
65 */
66 
67 #define LIB_MATH_MODULE
68 #include <lib_math.h>
69 
70 
71 /*$PAGE*/
72 /*
73 *********************************************************************************************************
74 * LOCAL DEFINES
75 *********************************************************************************************************
76 */
77 
78 
79 /*
80 *********************************************************************************************************
81 * LOCAL CONSTANTS
82 *********************************************************************************************************
83 */
84 
85 
86 /*
87 *********************************************************************************************************
88 * LOCAL DATA TYPES
89 *********************************************************************************************************
90 */
91 
92 
93 /*
94 *********************************************************************************************************
95 * LOCAL TABLES
96 *********************************************************************************************************
97 */
98 
99 
100 /*
101 *********************************************************************************************************
102 * LOCAL GLOBAL VARIABLES
103 *********************************************************************************************************
104 */
105 
106 RAND_NBR Math_RandSeedCur; /* Cur rand nbr seed. */
107 
108 
109 /*
110 *********************************************************************************************************
111 * LOCAL FUNCTION PROTOTYPES
112 *********************************************************************************************************
113 */
114 
115 
116 /*
117 *********************************************************************************************************
118 * LOCAL CONFIGURATION ERRORS
119 *********************************************************************************************************
120 */
121 
122 
123 /*$PAGE*/
124 /*
125 *********************************************************************************************************
126 * Math_Init()
127 *
128 * Description : (1) Initialize Mathematic Module :
129 *
130 * (a) Initialize random number seed value
131 *
132 *
133 * Argument(s) : none.
134 *
135 * Return(s) : none.
136 *
137 * Caller(s) : Application.
138 *
139 * Note(s) : (2) IEEE Std 1003.1, 2004 Edition, Section 'rand() : DESCRIPTION' states that "if rand()
140 * is called before any calls to srand() are made, the same sequence shall be generated
141 * as when srand() is first called with a seed value of 1".
142 *********************************************************************************************************
143 */
144 
145 void Math_Init (void)
146 {
147  Math_RandSetSeed((RAND_NBR)RAND_SEED_INIT_VAL); /* See Note #2. */
148 }
149 
150 
151 /*$PAGE*/
152 /*
153 *********************************************************************************************************
154 * Math_RandSetSeed()
155 *
156 * Description : Set the current pseudo-random number generator seed.
157 *
158 * Argument(s) : seed Initial (or current) value to set for the pseudo-random number sequence.
159 *
160 * Return(s) : none.
161 *
162 * Caller(s) : Application.
163 *
164 * Note(s) : (1) IEEE Std 1003.1, 2004 Edition, Section 'rand() : DESCRIPTION' states that "srand()
165 * ... uses the argument as a seed for a new sequence of pseudo-random numbers to be
166 * returned by subsequent calls to rand()".
167 *
168 * (2) 'Math_RandSeedCur' MUST always be accessed exclusively in critical sections.
169 *
170 * See also 'Math_Rand() Note #1b'.
171 *********************************************************************************************************
172 */
173 
174 void Math_RandSetSeed (RAND_NBR seed)
175 {
176  CPU_SR_ALLOC();
177 
178 
179  CPU_CRITICAL_ENTER();
180  Math_RandSeedCur = seed;
181  CPU_CRITICAL_EXIT();
182 }
183 
184 
185 /*$PAGE*/
186 /*
187 *********************************************************************************************************
188 * Math_Rand()
189 *
190 * Description : Calculate the next pseudo-random number.
191 *
192 * Argument(s) : none.
193 *
194 * Return(s) : Next pseudo-random number in the sequence after 'Math_RandSeedCur'.
195 *
196 * Caller(s) : Application.
197 *
198 * Note(s) : (1) (a) The pseudo-random number generator is implemented as a Linear Congruential
199 * Generator (LCG).
200 *
201 * (b) The pseudo-random number generated is in the range [0, RAND_LCG_PARAM_M].
202 *
203 * See also 'Math_RandSeed() Note #1'.
204 *
205 * (2) (a) IEEE Std 1003.1, 2004 Edition, Section 'rand() : DESCRIPTION' states that "rand()
206 * ... need not be reentrant ... [and] is not required to be thread-safe".
207 *
208 * (b) However, in order to implement Math_Rand() as re-entrant; 'Math_RandSeedCur' MUST
209 * always be accessed & updated exclusively in critical sections.
210 *
211 * See also 'Math_RandSeed() Note #2'.
212 *********************************************************************************************************
213 */
214 
215 RAND_NBR Math_Rand (void)
216 {
217  RAND_NBR seed;
218  RAND_NBR rand_nbr;
219  CPU_SR_ALLOC();
220 
221 
222  CPU_CRITICAL_ENTER();
223  seed = Math_RandSeedCur;
224  rand_nbr = Math_RandSeed(seed);
225  Math_RandSeedCur = rand_nbr;
226  CPU_CRITICAL_EXIT();
227 
228  return (rand_nbr);
229 }
230 
231 
232 /*$PAGE*/
233 /*
234 *********************************************************************************************************
235 * Math_RandSeed()
236 *
237 * Description : Calculate the next pseudo-random number.
238 *
239 * Argument(s) : seed Initial (or current) value for the pseudo-random number sequence.
240 *
241 * Return(s) : Next pseudo-random number in the sequence after 'seed'.
242 *
243 * Caller(s) : Math_Rand(),
244 * Application.
245 *
246 * Note(s) : (1) (a) BSD/ANSI-C implements rand() as a Linear Congruential Generator (LCG) :
247 *
248 * (A) random_number = [(a * random_number ) + b] modulo m
249 * n + 1 n
250 *
251 * where
252 * (1) (a) random_number Next random number to generate
253 * n+1
254 * (b) random_number Previous random number generated
255 * n
256 *
257 * (2) a = RAND_LCG_PARAM_A LCG multiplier
258 * (3) b = RAND_LCG_PARAM_B LCG incrementor
259 * (4) m = RAND_LCG_PARAM_M + 1 LCG modulus
260 *
261 * (b) The pseudo-random number generated is in the range [0, RAND_LCG_PARAM_M].
262 *
263  See also 'lib_math.h RANDOM NUMBER DEFINES Note #1b'.
264 *
265 * (2) (a) IEEE Std 1003.1, 2004 Edition, Section 'rand() : DESCRIPTION' states that "rand()
266 * ... need not be reentrant ... [and] is not required to be thread-safe".
267 *
268 * (b) However, Math_RandSeed() is re-entrant since it calculates the next random number
269 * using ONLY local variables.
270 *********************************************************************************************************
271 */
272 
273 RAND_NBR Math_RandSeed (RAND_NBR seed)
274 {
275  RAND_NBR rand_nbr;
276 
277 
278  rand_nbr = (((RAND_NBR)RAND_LCG_PARAM_A * seed) + (RAND_NBR)RAND_LCG_PARAM_B) % ((RAND_NBR)RAND_LCG_PARAM_M + 1u);
279 
280  return (rand_nbr);
281 }
282