PIC24 Support Libraries
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
all_generic.h
Go to the documentation of this file.
1 /*
2  * "Copyright (c) 2008 Robert B. Reese, Bryan A. Jones, J. W. Bruce ("AUTHORS")"
3  * All rights reserved.
4  * (R. Reese, reese_AT_ece.msstate.edu, Mississippi State University)
5  * (B. A. Jones, bjones_AT_ece.msstate.edu, Mississippi State University)
6  * (J. W. Bruce, jwbruce_AT_ece.msstate.edu, Mississippi State University)
7  *
8  * Permission to use, copy, modify, and distribute this software and its
9  * documentation for any purpose, without fee, and without written agreement is
10  * hereby granted, provided that the above copyright notice, the following
11  * two paragraphs and the authors appear in all copies of this software.
12  *
13  * IN NO EVENT SHALL THE "AUTHORS" BE LIABLE TO ANY PARTY FOR
14  * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT
15  * OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE "AUTHORS"
16  * HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
17  *
18  * THE "AUTHORS" SPECIFICALLY DISCLAIMS ANY WARRANTIES,
19  * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
20  * AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS
21  * ON AN "AS IS" BASIS, AND THE "AUTHORS" HAS NO OBLIGATION TO
22  * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS."
23  *
24  * Please maintain this header in its entirety when copying/modifying
25  * these files.
26  *
27  *
28  */
29 
30 // Documentation for this file. If the \file tag isn't present,
31 // this file won't be documented.
32 /** \file
33  * \brief Embedded Systems Operating System (ESOS)
34  * Definitions to make ESOS code more generic and portable.
35  * \note This file is to be included in ESOS builds on all platforms.
36 */
37 
38 #ifndef __ALL_GENERIC_H
39 #define __ALL_GENERIC_H
40 
41 
42 #ifdef __linux
43 //#warning Compiling for 32-bit Linux
44 #include "pc_generic.h"
45 #define HELLO_MSG "\n" __FILE__ ", built on " __DATE__ " at " __TIME__ "\n"
46 #else
47 //#warning Compiling for Microchip PIC24 microcontrollers
48 #include "pic24_generic.h"
49 #endif
50 
51 
52 /**
53  * Union structure to hold an uint8 (byte) to provide access to
54  * 8-bit data with different "viewpoints" (or casts, if you will).
55  * \note Works on machines that store their data little-endian.
56  * If you use big-endian, the members will have to be reordered!
57  * \note Prefix for all UINT8 structs is <em>U8_</em>
58  */
59 typedef union _UINT8 {
60  /** uint8 viewed as an uint8 */
62  /** uint8 viewed as an uint8 */
64  struct {
65  /** bit 0 (the LSb) of the uint8 */
66 unsigned b0:
67  1;
68  /** bit 1 of the uint8 */
69 unsigned b1:
70  1;
71  /** bit 2 of the uint8 */
72 unsigned b2:
73  1;
74  /** bit 3 of the uint8 */
75 unsigned b3:
76  1;
77  /** bit 4 of the uint8 */
78 unsigned b4:
79  1;
80  /** bit 5 of the uint8 */
81 unsigned b5:
82  1;
83  /** bit 6 of the uint8 */
84 unsigned b6:
85  1;
86  /** bit 7 (MSb) of the uint8 */
87 unsigned b7:
88  1;
89  };
90 } UINT8;
91 
92 /**
93  * Union structure to hold uint16s to provide access to
94  * 16-bit data with different "viewpoints" (or casts, if you will).
95  * \note Works on machines that store their
96  * data little-endian. If you use big-endian, the members will
97  * have to be reordered!
98  * \note Prefix for all UINT16 structs is <em>U16_</em>
99  * \code
100  * uint8 u8_a, u8_b;
101  * UINT16 U16_y;
102  *
103  * U16_y._uint16 = 0xF00D;
104  * u8_b = U16_y.u8Bytes[0]; // u8_b equals 0x0D
105  * u8_a = U16_y.u8MSb; // u8_a equals 0xF0
106  * while (U16_y.b7); // falls through since bit 7 is 0 (FALSE)
107  * \endcode
108  */
109 typedef union _UINT16 {
110  /** uint16 viewed as an uint16 */
112  /** uint16 viewed as an uint16 */
114  struct {
115  /** LSB (uint8) of the uint16 */
117  /** MSB (uint8) of the uint16 */
119  };
120  struct {
121  /** The uint16 viewed as an array of two (2) uint8s */
122  uint8 u8Bytes[2];
123  };
124  struct {
125  /** bit 0 (the LSb) of the uint16 */
126 unsigned b0:
127  1;
128  /** bit 1 of the uint16 */
129 unsigned b1:
130  1;
131  /** bit 2 of the uint16 */
132 unsigned b2:
133  1;
134  /** bit 3 of the uint16 */
135 unsigned b3:
136  1;
137  /** bit 4 of the uint16 */
138 unsigned b4:
139  1;
140  /** bit 5 of the uint16 */
141 unsigned b5:
142  1;
143  /** bit 6 of the uint16 */
144 unsigned b6:
145  1;
146  /** bit 7 of the uint16 */
147 unsigned b7:
148  1;
149  /** bit 8 of the uint16 */
150 unsigned b8:
151  1;
152  /** bit 9 of the uint16 */
153 unsigned b9:
154  1;
155  /** bit 10 of the uint16 */
156 unsigned b10:
157  1;
158  /** bit 11 of the uint16 */
159 unsigned b11:
160  1;
161  /** bit 12 of the uint16 */
162 unsigned b12:
163  1;
164  /** bit 13 of the uint16 */
165 unsigned b13:
166  1;
167  /** bit 14 of the uint16 */
168 unsigned b14:
169  1;
170  /** bit 15 (the MSb) of the uint16 */
171 unsigned b15:
172  1;
173  };
174 } UINT16;
175 
176 /**
177  * Returns the Least-Significant-Byte (LSB)
178  * \param a UINT16 structure holding a 16-bit value
179  * \returns LSB of the 16-bit value in the UINT16 struct
180  * \hideinitializer
181  */
182 #define LSB(a) ((a).u8Bytes[0])
183 /**
184  * Returns the Most-Significant-Byte (MSB)
185  * \param a UINT16 structure holding a 16-bit value
186  * \returns MSB of the 16-bit value in the UINT16 struct
187  * \hideinitializer
188  */
189 #define MSB(a) ((a).u8Bytes[1])
190 
191 /**
192  * Union structure to hold an uint32 to provide access to
193  * 32-bit data with different "viewpoints" (or casts, if you will).
194  * \note Works on machines that store their
195  * data little-endian. If you use big-endian, the members will
196  * have to be reordered!
197  * \note Prefix for all UINT32 structs is <em>U32_</em>
198  * \code
199  * UINT32 U32_x;
200  * uint16 u16_a;
201  * uint8 u8_b;
202  * UINT16 U16_y;
203  *
204  * U32_x._uint32 = 0xDEADBEEF;
205  * u16_a = U32_x.u16LoWord; // u16_a equals 0xBEEF
206  * u8_b = U32_x.u8Bytes[0]; // u8_b equals 0xEF
207  * u16_a = U32_x.u16Words[1]; // u16_a equals 0xDEAD
208  * U16_y._uint16 = U32_x.u16LoWord; // where's the "BEEF"?
209  * u8_b = U16_y.uMSb; // u8_b equals 0xBE
210  * while (U32_x.b31); // infinite loop
211  * \endcode
212  */
213 typedef union _UINT32 {
214  /** uint32 viewed as an uint32 */
216  /** uint32 viewed as an uint32 */
218  struct {
219  /** The LSB of the least-signficant uint16 in the 32-bit data */
221  /** The MSB of the least-signficant uint16 in the 32-bit data */
223  /** The LSB of the most-signficant uint16 in the 32-bit data */
225  /** The MSB of the most-signficant uint16 in the 32-bit data */
227  };
228  struct {
229  /** The least-significant uint16 in the 32-bit data */
231  /** The most-significant uint16 in the 32-bit data */
233  };
234  struct {
235  /** The uint32 viewed as an array of two (2) uint16s */
236  uint16 u16Words[2];
237  };
238  struct {
239  /** The uint32 viewed as an array of four (4) uint8s */
240  uint8 u8Bytes[4];
241  };
242  struct {
243 unsigned b0:
244  1;
245  /** bit 1 (the LSb) of the uint32 */
246 unsigned b1:
247  1;
248  /** bit 2 of the uint32 */
249 unsigned b2:
250  1;
251  /** bit 3 of the uint32 */
252 unsigned b3:
253  1;
254  /** bit 4 of the uint32 */
255 unsigned b4:
256  1;
257  /** bit 5 of the uint32 */
258 unsigned b5:
259  1;
260  /** bit 6 of the uint32 */
261 unsigned b6:
262  1;
263  /** bit 7 of the uint32 */
264 unsigned b7:
265  1;
266  /** bit 8 of the uint32 */
267 unsigned b8:
268  1;
269  /** bit 9 of the uint32 */
270 unsigned b9:
271  1;
272  /** bit 10 of the uint32 */
273 unsigned b10:
274  1;
275  /** bit 11 of the uint32 */
276 unsigned b11:
277  1;
278  /** bit 12 of the uint32 */
279 unsigned b12:
280  1;
281  /** bit 13 of the uint32 */
282 unsigned b13:
283  1;
284  /** bit 14 of the uint32 */
285 unsigned b14:
286  1;
287  /** bit 15 of the uint32 */
288 unsigned b15:
289  1;
290  /** bit 16 of the uint32 */
291 unsigned b16:
292  1;
293  /** bit 17 of the uint32 */
294 unsigned b17:
295  1;
296  /** bit 18 of the uint32 */
297 unsigned b18:
298  1;
299  /** bit 19 of the uint32 */
300 unsigned b19:
301  1;
302  /** bit 20 of the uint32 */
303 unsigned b20:
304  1;
305  /** bit 21 of the uint32 */
306 unsigned b21:
307  1;
308  /** bit 22 of the uint32 */
309 unsigned b22:
310  1;
311  /** bit 23 of the uint32 */
312 unsigned b23:
313  1;
314  /** bit 24 of the uint32 */
315 unsigned b24:
316  1;
317  /** bit 25 of the uint32 */
318 unsigned b25:
319  1;
320  /** bit 26 of the uint32 */
321 unsigned b26:
322  1;
323  /** bit 27 of the uint32 */
324 unsigned b27:
325  1;
326  /** bit 28 of the uint32 */
327 unsigned b28:
328  1;
329  /** bit 29 of the uint32 */
330 unsigned b29:
331  1;
332  /** bit 30 of the uint32 */
333 unsigned b30:
334  1;
335  /** bit 31 (MSb) of the uint32 */
336 unsigned b31:
337  1;
338  };
339 } UINT32;
340 
341 // Now, some macros to help navigate these structures.....
342 /**
343  * Returns the Least-Significant-WORD (uint16) of a UINT32 structure
344  * \param a UINT32 structure holding a 32-bit value
345  * \returns LSW of the 32-bit value in the UINT32 struct
346  * \hideinitializer
347  */
348 #define LOWER_WORD(a) ((a).u16Words[0])
349 /**
350  * Returns the Most-Significant-WORD (uint16) of a UINT32 structure
351  * \param a UINT32 structure holding a 32-bit value
352  * \returns MSW of the 32-bit value in the UINT32 struct
353  * \hideinitializer
354  */
355 #define UPPER_WORD(a) ((a).u16Words[1])
356 /**
357  * Returns the Least-Significant-BYTE (uint8) of a UINT32 structure
358  * \param a UINT32 structure holding a 32-bit value
359  * \returns Byte 0 (LSB) of the 32-bit value in the UINT32 struct
360  * \hideinitializer
361  */
362 #define LOWER_LSB(a) ((a).u8Bytes[0])
363 /**
364  * Returns the 2nd most least-Significant-BYTE (uint8) of a UINT32 structure
365  * \param a UINT32 structure holding a 32-bit value
366  * \returns Byte 1 of the 32-bit value in the UINT32 struct
367  * \hideinitializer
368  */
369 #define LOWER_MSB(a) ((a).u8Bytes[1])
370 /**
371  * Returns the 3nd most least-Significant-BYTE (uint8) of a UINT32 structure
372  * \param a UINT32 structure holding a 32-bit value
373  * \returns Byte 2 of the 32-bit value in the UINT32 struct
374  * \hideinitializer
375  */
376 #define UPPER_LSB(a) ((a).u8Bytes[2])
377 /**
378  * Returns the Most-Significant-BYTE (uint8) of a UINT32 structure
379  * \param a UINT32 structure holding a 32-bit value
380  * \returns Byte 3 (MSB) of the 32-bit value in the UINT32 struct
381  * \hideinitializer
382  */
383 #define UPPER_MSB(a) ((a).u8Bytes[3])
384 
385 /**
386  * A single bit quantity. Takes on the value TRUE or FALSE.
387  * \hideinitializer
388  */
389 typedef enum _BOOL {
390  /** False, not true, off, zero */
391  FALSE = 0,
392  /** True, not false, on, one */
394 } BOOL;
395 
396 /** another way to say \ref TRUE */
397 #define OK TRUE
398 /** another way to say \ref FALSE */
399 #define FAIL FALSE
400 /** An uninitialized pointer */
401 #define NULLPTR 0
402 /** An unitialized index value */
403 #define NULLIDX 0xFF
404 /** Mask to represent bit 0 (the LSb) */
405 #define BIT0 0x01
406 /** Mask to represent bit 1 */
407 #define BIT1 0x02
408 /** Mask to represent bit 2 */
409 #define BIT2 0x04
410 /** Mask to represent bit 3 */
411 #define BIT3 0x08
412 /** Mask to represent bit 4 */
413 #define BIT4 0x10
414 /** Mask to represent bit 5 */
415 #define BIT5 0x20
416 /** Mask to represent bit 6 */
417 #define BIT6 0x40
418 /** Mask to represent bit 7 (the MSb of a uint8) */
419 #define BIT7 0x80
420 /** Mask to represent bit 8 (the LSb of the most-significant byte in an uint8)*/
421 #define BIT8 0x0100
422 /** Mask to represent bit 9 */
423 #define BIT9 0x0200
424 /** Mask to represent bit 10 */
425 #define BIT10 0x0400
426 /** Mask to represent bit 11 */
427 #define BIT11 0x0800
428 /** Mask to represent bit 12 */
429 #define BIT12 0x1000
430 /** Mask to represent bit 13 */
431 #define BIT13 0x2000
432 /** Mask to represent bit 14 */
433 #define BIT14 0x4000
434 /** Mask to represent bit 15 (the MSb of an uint16) */
435 #define BIT15 0x8000
436 
437 /**
438  * Sets the bits of a variable according to a mask
439  * \param var variable containing the bits to "set"
440  * \param mask varable with <em>ONE</em>s in the locations where you want to <em>set</em> bits
441  * \hideinitializer
442  */
443 #define BIT_SET_MASK(var, mask) ((var) |= (mask))
444 /**
445  * Clear the bits of a variable according to a mask
446  * \param var variable containing the bits to "clear"
447  * \param mask varable with <em>ONE</em>s in the locations where you want to <em>clear</em> bits
448  * \hideinitializer
449  */
450 #define BIT_CLEAR_MASK(var, mask) ((var) &= (~(mask)))
451 /**
452  * Toggle the bits of a variable according to a mask
453  * \param var variable containing the bits to "toggle"
454  * \param mask varable with <em>ONE</em>s in the locations where you want to <em>toggle</em> bits
455  * \hideinitializer
456  */
457 #define BIT_TOGGLE_MASK(var, mask) ((var) ^= (mask))
458 /**
459  * Determine if one or more bits are set in a variable
460  * \param var variable containing the bits to test
461  * \param mask varable with <em>ONE</em>s in the locations where you want to check for <em>set</em> bits
462  * \retval TRUE if one or more of the mask bits are set in the variable
463  * \retval FALSE if none of the mask bits are set
464  * \note Does <em>NOT</em> test to see if you variable has ALL mask bits set
465  * \hideinitializer
466  */
467 #define IS_BIT_SET_MASK(var, mask) (((var) & (mask)))
468 /**
469  * Determine if one or more bits are cleared in a variable
470  * \param var variable containing the bits to test
471  * \param mask varable with <em>ONE</em>s in the locations where you want to check for <em>cleared</em> bits
472  * \retval TRUE if one or more of the mask bits are cleared in the variable
473  * \retval FALSE if none of the mask bits are cleared
474  * \note Does <em>NOT</em> test to see if you variable has ALL mask bits cleared
475  * \hideinitializer
476  */
477 #define IS_BIT_CLEAR_MASK(var, mask) ((~(var) & (mask)))
478 
479 /**
480  * Sets a single bit in a variable
481  * \param var variable
482  * \param bitnum Number (0-?) of the bit that should be <em>set</em>
483  * \hideinitializer
484  */
485 #define BIT_SET(var, bitnum) ((var) |= (1 << (bitnum)))
486 /**
487  * Clears a single bit in a variable
488  * \param var variable
489  * \param bitnum Number (0-?) of the bit that should be <em>cleared</em>
490  * \hideinitializer
491  */
492 #define BIT_CLEAR(var, bitnum) ((var) &= (~(1 << (bitnum))))
493 /**
494  * Toggle a single bit in a variable
495  * \param var variable
496  * \param bitnum Number (0-?) of the bit that should be <em>toggleed</em>
497  * \hideinitializer
498  */
499 #define BIT_TOGGLE(var, bitnum) ((var) ^= (1 << (bitnum)))
500 /**
501  * Determine if a bit is set in a variable
502  * \param var variable containing the bits to test
503  * \param bitnum Number (0-?) of the bit to test for being <em>set</em>
504  * \retval TRUE if the bit is set
505  * \retval FALSE otherwise
506  * \hideinitializer
507  */
508 #define IS_BIT_SET(var, bitnum) ((var) & (1 << (bitnum)))
509 /**
510  * Determine if a bit is cleared in a variable
511  * \param var variable containing the bits to test
512  * \param bitnum Number (0-?) of the bit to test for being <em>cleared</em>
513  * \retval TRUE if the bit is clear
514  * \retval FALSE otherwise
515  * \hideinitializer
516  */
517 #define IS_BIT_CLEAR(var, bitnum) (~(var) & ((1 << (bitnum))))
518 
519 #endif //ALL_GENERIC_H