LPCOpen Platform  v1.03
LPCOpen Platform for NXP LPC Microcontrollers
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
cpu_core.h
Go to the documentation of this file.
1 /*
2 *********************************************************************************************************
3 * uC/CPU
4 * CPU CONFIGURATION & PORT LAYER
5 *
6 * (c) Copyright 2004-2011; Micrium, Inc.; Weston, FL
7 *
8 * All rights reserved. Protected by international copyright laws.
9 *
10 * uC/CPU 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 * CORE CPU MODULE
26 *
27 * Filename : cpu_core.h
28 * Version : V1.28.00
29 * Programmer(s) : SR
30 * ITJ
31 *********************************************************************************************************
32 */
33 
34 
35 /*
36 *********************************************************************************************************
37 * MODULE
38 *********************************************************************************************************
39 */
40 
41 #ifndef CPU_CORE_MODULE_PRESENT
42 #define CPU_CORE_MODULE_PRESENT
43 
44 
45 /*$PAGE*/
46 /*
47 *********************************************************************************************************
48 * CORE CPU MODULE VERSION NUMBER
49 *
50 * Note(s) : (1) (a) The core CPU module software version is denoted as follows :
51 *
52 * Vx.yy.zz
53 *
54 * where
55 * V denotes 'Version' label
56 * x denotes major software version revision number
57 * yy denotes minor software version revision number
58 * zz denotes sub-minor software version revision number
59 *
60 * (b) The software version label #define is formatted as follows :
61 *
62 * ver = x.yyzz * 100 * 100
63 *
64 * where
65 * ver denotes software version number scaled as an integer value
66 * x.yyzz denotes software version number, where the unscaled integer
67 * portion denotes the major version number & the unscaled
68 * fractional portion denotes the (concatenated) minor
69 * version numbers
70 *********************************************************************************************************
71 */
72 
73 #define CPU_CORE_VERSION 12800u /* See Note #1. */
74 
75 
76 /*
77 *********************************************************************************************************
78 * EXTERNS
79 *********************************************************************************************************
80 */
81 
82 #ifdef CPU_CORE_MODULE
83 #define CPU_CORE_EXT
84 #else
85 #define CPU_CORE_EXT extern
86 #endif
87 
88 
89 /*
90 *********************************************************************************************************
91 * INCLUDE FILES
92 *
93 * Note(s) : (1) CPU-configuration software files are located in the following directories :
94 *
95 * (a) <Your Product Application>\cpu_cfg.h
96 *
97 * (b) (1) <CPU-Compiler Directory>\cpu_*.*
98 * (2) <CPU-Compiler Directory><cpu><compiler>\cpu*.*
99 *
100 * where
101 * <Your Product Application> directory path for Your Product's Application
102 * <CPU-Compiler Directory> directory path for common CPU-compiler software
103 * <cpu> directory name for specific processor (CPU)
104 * <compiler> directory name for specific compiler
105 *
106 * (2) NO compiler-supplied standard library functions SHOULD be used.
107 *
108 * (a) Standard library functions are implemented in the custom library module(s) :
109 *
110 * <Custom Library Directory>\lib_*.*
111 *
112 * where
113 * <Custom Library Directory> directory path for custom library software
114 *
115 * (3) Compiler MUST be configured to include as additional include path directories :
116 *
117 * (a) '<Your Product Application>\' directory See Note #1a
118 *
119 * (b) (1) '<CPU-Compiler Directory>\' directory See Note #1b1
120 * (2) '<CPU-Compiler Directory><cpu><compiler>\' directory See Note #1b2
121 *
122 * (c) '<Custom Library Directory>\' directory See Note #2a
123 *********************************************************************************************************
124 */
125 
126 #include <cpu.h>
127 #include <lib_def.h>
128 #include <cpu_cfg.h>
129 
130 #include <lib_mem.h>
131 #include <lib_str.h>
132 
133 
134 /*$PAGE*/
135 /*
136 *********************************************************************************************************
137 * CPU CONFIGURATION
138 *
139 * Note(s) : (1) The following pre-processor directives correctly configure CPU parameters. DO NOT MODIFY.
140 *
141 * (2) CPU timestamp timer feature is required for :
142 *
143 * (a) CPU timestamps
144 * (b) CPU interrupts disabled time measurement
145 *
146 * See also 'cpu_cfg.h CPU TIMESTAMP CONFIGURATION Note #1'
147 * & 'cpu_cfg.h CPU INTERRUPTS DISABLED TIME MEASUREMENT CONFIGURATION Note #1'.
148 *********************************************************************************************************
149 */
150 
151 #ifdef CPU_CFG_TS_EN
152 #undef CPU_CFG_TS_EN
153 #endif
154 
155 
156 #if ((CPU_CFG_TS_32_EN == DEF_ENABLED) || \
157  (CPU_CFG_TS_64_EN == DEF_ENABLED))
158 #define CPU_CFG_TS_EN DEF_ENABLED
159 #else
160 #define CPU_CFG_TS_EN DEF_DISABLED
161 #endif
162 
163 #if ((CPU_CFG_TS_EN == DEF_ENABLED) || \
164 (defined(CPU_CFG_INT_DIS_MEAS_EN)))
165 #define CPU_CFG_TS_TMR_EN DEF_ENABLED
166 #else
167 #define CPU_CFG_TS_TMR_EN DEF_DISABLED
168 #endif
169 
170 
171 /*
172 *********************************************************************************************************
173 * DEFINES
174 *********************************************************************************************************
175 */
176 
177 #define CPU_TIME_MEAS_NBR_MIN 1
178 #define CPU_TIME_MEAS_NBR_MAX 128
179 
180 
181 /*
182 *********************************************************************************************************
183 * CPU ERROR CODES
184 *********************************************************************************************************
185 */
186 
187 #define CPU_ERR_NONE 0u
188 #define CPU_ERR_NULL_PTR 10u
189 
190 #define CPU_ERR_NAME_SIZE 1000u
191 
192 #define CPU_ERR_TS_FREQ_INVALID 2000u
193 
194 
195 /*$PAGE*/
196 /*
197 *********************************************************************************************************
198 * DATA TYPES
199 *********************************************************************************************************
200 */
201 
202 /*
203 *********************************************************************************************************
204 * CPU ERROR CODES DATA TYPE
205 *********************************************************************************************************
206 */
207 
208 typedef CPU_INT16U CPU_ERR;
209 
210 
211 /*
212 *********************************************************************************************************
213 * CPU TIMESTAMP DATA TYPES
214 *
215 * Note(s) : (1) CPU timestamp timer data type defined to the binary-multiple of 8-bit octets as configured
216 * by 'CPU_CFG_TS_TMR_SIZE' (see 'cpu_cfg.h CPU TIMESTAMP CONFIGURATION Note #2').
217 *********************************************************************************************************
218 */
219 
220 typedef CPU_INT32U CPU_TS32;
221 typedef CPU_INT64U CPU_TS64;
222 
223 typedef CPU_TS32 CPU_TS; /* Req'd for backwards-compatibility. */
224 
225 
226 #if (CPU_CFG_TS_TMR_EN == DEF_ENABLED) /* CPU ts tmr defined to cfg'd word size (see Note #1). */
227 #if (CPU_CFG_TS_TMR_SIZE == CPU_WORD_SIZE_08)
228 typedef CPU_INT08U CPU_TS_TMR;
229 #elif (CPU_CFG_TS_TMR_SIZE == CPU_WORD_SIZE_16)
230 typedef CPU_INT16U CPU_TS_TMR;
231 #elif (CPU_CFG_TS_TMR_SIZE == CPU_WORD_SIZE_64)
232 typedef CPU_INT64U CPU_TS_TMR;
233 #else /* CPU ts tmr dflt size = 32-bits. */
234 typedef CPU_INT32U CPU_TS_TMR;
235 #endif
236 #endif
237 
238 
239 /*
240 *********************************************************************************************************
241 * CPU TIMESTAMP TIMER FREQUENCY DATA TYPE
242 *********************************************************************************************************
243 */
244 
245 typedef CPU_INT32U CPU_TS_TMR_FREQ;
246 
247 
248 /*
249 *********************************************************************************************************
250 * GLOBAL VARIABLES
251 *********************************************************************************************************
252 */
253 
254 #if (CPU_CFG_NAME_EN == DEF_ENABLED)
255 CPU_CORE_EXT CPU_CHAR CPU_Name[CPU_CFG_NAME_SIZE]; /* CPU host name. */
256 #endif
257 
258 
259 #if ((CPU_CFG_TS_32_EN == DEF_ENABLED) && \
260  (CPU_CFG_TS_TMR_SIZE < CPU_WORD_SIZE_32))
261 CPU_CORE_EXT CPU_TS32 CPU_TS_32_Accum; /* 32-bit accum'd ts (in ts tmr cnts). */
262 CPU_CORE_EXT CPU_TS_TMR CPU_TS_32_TmrPrev; /* 32-bit ts prev tmr (in ts tmr cnts). */
263 #endif
264 
265 #if ((CPU_CFG_TS_64_EN == DEF_ENABLED) && \
266  (CPU_CFG_TS_TMR_SIZE < CPU_WORD_SIZE_64))
267 CPU_CORE_EXT CPU_TS64 CPU_TS_64_Accum; /* 64-bit accum'd ts (in ts tmr cnts). */
268 CPU_CORE_EXT CPU_TS_TMR CPU_TS_64_TmrPrev; /* 64-bit ts prev tmr (in ts tmr cnts). */
269 #endif
270 
271 #if (CPU_CFG_TS_TMR_EN == DEF_ENABLED)
272 CPU_CORE_EXT CPU_TS_TMR_FREQ CPU_TS_TmrFreq_Hz; /* CPU ts tmr freq (in Hz). */
273 #endif
274 
275 
276 #ifdef CPU_CFG_INT_DIS_MEAS_EN
277 CPU_CORE_EXT CPU_INT16U CPU_IntDisMeasCtr; /* Nbr tot ints dis'd ctr. */
278 CPU_CORE_EXT CPU_INT16U CPU_IntDisNestCtr; /* Nbr nested ints dis'd ctr. */
279  /* Ints dis'd time (in ts tmr cnts) : ... */
280 CPU_CORE_EXT CPU_TS_TMR CPU_IntDisMeasStart_cnts; /* ... start time. */
281 CPU_CORE_EXT CPU_TS_TMR CPU_IntDisMeasStop_cnts; /* ... stop time. */
282 CPU_CORE_EXT CPU_TS_TMR CPU_IntDisMeasOvrhd_cnts; /* ... time meas ovrhd. */
283 CPU_CORE_EXT CPU_TS_TMR CPU_IntDisMeasMaxCur_cnts; /* ... resetable max time dis'd. */
284 CPU_CORE_EXT CPU_TS_TMR CPU_IntDisMeasMax_cnts; /* ... non-resetable max time dis'd. */
285 #endif
286 
287 
288 /*$PAGE*/
289 /*
290 *********************************************************************************************************
291 * MACRO'S
292 *********************************************************************************************************
293 */
294 
295 /*
296 *********************************************************************************************************
297 * CPU_SW_EXCEPTION()
298 *
299 * Description : Trap unrecoverable software exception.
300 *
301 * Argument(s) : err_rtn_val Error type &/or value of the calling function to return (see Note #2b).
302 *
303 * Return(s) : none.
304 *
305 * Caller(s) : various.
306 *
307 * Note(s) : (1) CPU_SW_EXCEPTION() deadlocks the current code execution -- whether multi-tasked/
308 * -processed/-threaded or single-threaded -- when the current code execution cannot
309 * gracefully recover or report a fault or exception condition.
310 *
311 * Example CPU_SW_EXCEPTION() call :
312 *
313 * void Fnct (CPU_ERR *p_err)
314 * {
315 * :
316 *
317 * if (p_err == (CPU_ERR *)0) { If 'p_err' NULL, cannot return error ...
318 * CPU_SW_EXCEPTION(;); ... so trap invalid argument exception.
319 * }
320 *
321 * :
322 * }
323 *
324 * See also 'cpu_core.c CPU_SW_Exception() Note #1'.
325 *
326 * (2) (a) CPU_SW_EXCEPTION() MAY be developer-implemented to output &/or handle any error or
327 * exception conditions; but since CPU_SW_EXCEPTION() is intended to trap unrecoverable
328 * software conditions, it is recommended that developer-implemented versions prevent
329 * execution of any code following calls to CPU_SW_EXCEPTION() by deadlocking the code
330 * (see Note #1).
331 *
332 * Example CPU_SW_EXCEPTION() :
333 *
334 * #define CPU_SW_EXCEPTION(err_rtn_val) do { \
335 * Log(__FILE__, __LINE__); \
336 * CPU_SW_Exception(); \
337 * } while (0)
338 *
339 * (b) (1) However, if execution of code following calls to CPU_SW_EXCEPTION() is required
340 * (e.g. for automated testing); it is recommended that the last statement in
341 * developer-implemented versions be to return from the current function to prevent
342 * possible software exception(s) in the current function from triggering CPU &/or
343 * hardware exception(s).
344 *
345 * Example CPU_SW_EXCEPTION() :
346 *
347 * #define CPU_SW_EXCEPTION(err_rtn_val) do { \
348 * Log(__FILE__, __LINE__); \
349 * return err_rtn_val; \
350 * } while (0)
351 *
352 * (A) Note that 'err_rtn_val' in the return statement MUST NOT be enclosed in
353 * parentheses. This allows CPU_SW_EXCEPTION() to return from functions that
354 * return 'void', i.e. NO return type or value (see also Note #2b2A).
355 *$PAGE*
356 * (2) In order for CPU_SW_EXCEPTION() to return from functions with various return
357 * types/values, each caller function MUST pass an appropriate error return type
358 * & value to CPU_SW_EXCEPTION().
359 *
360 * (A) Note that CPU_SW_EXCEPTION() MUST NOT be passed any return type or value
361 * for functions that return 'void', i.e. NO return type or value; but SHOULD
362 * instead be passed a single semicolon. This prevents possible compiler
363 * warnings that CPU_SW_EXCEPTION() is passed too few arguments. However,
364 * the compiler may warn that CPU_SW_EXCEPTION() does NOT prevent creating
365 * null statements on lines with NO other code statements.
366 *
367 * Example CPU_SW_EXCEPTION() calls :
368 *
369 * void Fnct (CPU_ERR *p_err)
370 * {
371 * :
372 *
373 * if (p_err == (CPU_ERR *)0) {
374 * CPU_SW_EXCEPTION(;); Exception macro returns NO value
375 * } (see Note #2b2A)
376 *
377 * :
378 * }
379 *
380 * CPU_BOOLEAN Fnct (CPU_ERR *p_err)
381 * {
382 * :
383 *
384 * if (p_err == (CPU_ERR *)0) {
385 * CPU_SW_EXCEPTION(DEF_FAIL); Exception macro returns 'DEF_FAIL'
386 * }
387 *
388 * :
389 * }
390 *
391 * OBJ *Fnct (CPU_ERR *p_err)
392 * {
393 * :
394 *
395 * if (p_err == (CPU_ERR *)0) {
396 * CPU_SW_EXCEPTION((OBJ *)0); Exception macro returns NULL 'OBJ *'
397 * }
398 *
399 * :
400 * }
401 *
402 *********************************************************************************************************
403 */
404 
405 #ifndef CPU_SW_EXCEPTION /* See Note #2. */
406 #define CPU_SW_EXCEPTION(err_rtn_val) do { \
407  CPU_SW_Exception(); \
408  } while (0)
409 #endif
410 
411 
412 /*$PAGE*/
413 /*
414 *********************************************************************************************************
415 * CPU_TYPE_CREATE()
416 *
417 * Description : Creates a generic type value.
418 *
419 * Argument(s) : char_1 1st ASCII character to create generic type value.
420 *
421 * char_2 2nd ASCII character to create generic type value.
422 *
423 * char_3 3rd ASCII character to create generic type value.
424 *
425 * char_4 4th ASCII character to create generic type value.
426 *
427 * Return(s) : 32-bit generic type value.
428 *
429 * Caller(s) : various.
430 *
431 * Note(s) : (1) (a) Generic type values should be #define'd with large, non-trivial values to trap
432 * & discard invalid/corrupted objects based on type value.
433 *
434 * In other words, by assigning large, non-trivial values to valid objects' type
435 * fields; the likelihood that an object with an unassigned &/or corrupted type
436 * field will contain a value is highly improbable & therefore the object itself
437 * will be trapped as invalid.
438 *
439 * (b) (1) CPU_TYPE_CREATE() creates a 32-bit type value from four values.
440 *
441 * (2) Ideally, generic type values SHOULD be created from 'CPU_CHAR' characters to
442 * represent ASCII string abbreviations of the specific object types. Memory
443 * displays of object type values will display the specific object types with
444 * their chosen ASCII names.
445 *
446 * Examples :
447 *
448 * #define FILE_TYPE CPU_TYPE_CREATE('F', 'I', 'L', 'E')
449 * #define BUF_TYPE CPU_TYPE_CREATE('B', 'U', 'F', ' ')
450 *********************************************************************************************************
451 */
452 
453 #if (CPU_CFG_ENDIAN_TYPE == CPU_ENDIAN_TYPE_BIG)
454 #define CPU_TYPE_CREATE(char_1, char_2, char_3, char_4) (((CPU_INT32U)((CPU_INT08U)(char_1)) << (3u * DEF_OCTET_NBR_BITS)) | \
455  ((CPU_INT32U)((CPU_INT08U)(char_2)) << (2u * DEF_OCTET_NBR_BITS)) | \
456  ((CPU_INT32U)((CPU_INT08U)(char_3)) << (1u * DEF_OCTET_NBR_BITS)) | \
457  ((CPU_INT32U)((CPU_INT08U)(char_4)) << (0u * DEF_OCTET_NBR_BITS)))
458 
459 #else
460 
461 #if ((CPU_CFG_DATA_SIZE == CPU_WORD_SIZE_64) || \
462  (CPU_CFG_DATA_SIZE == CPU_WORD_SIZE_32))
463 #define CPU_TYPE_CREATE(char_1, char_2, char_3, char_4) (((CPU_INT32U)((CPU_INT08U)(char_1)) << (0u * DEF_OCTET_NBR_BITS)) | \
464  ((CPU_INT32U)((CPU_INT08U)(char_2)) << (1u * DEF_OCTET_NBR_BITS)) | \
465  ((CPU_INT32U)((CPU_INT08U)(char_3)) << (2u * DEF_OCTET_NBR_BITS)) | \
466  ((CPU_INT32U)((CPU_INT08U)(char_4)) << (3u * DEF_OCTET_NBR_BITS)))
467 
468 
469 #elif (CPU_CFG_DATA_SIZE == CPU_WORD_SIZE_16)
470 #define CPU_TYPE_CREATE(char_1, char_2, char_3, char_4) (((CPU_INT32U)((CPU_INT08U)(char_1)) << (2u * DEF_OCTET_NBR_BITS)) | \
471  ((CPU_INT32U)((CPU_INT08U)(char_2)) << (3u * DEF_OCTET_NBR_BITS)) | \
472  ((CPU_INT32U)((CPU_INT08U)(char_3)) << (0u * DEF_OCTET_NBR_BITS)) | \
473  ((CPU_INT32U)((CPU_INT08U)(char_4)) << (1u * DEF_OCTET_NBR_BITS)))
474 
475 #else /* Dflt CPU_WORD_SIZE_08. */
476 #define CPU_TYPE_CREATE(char_1, char_2, char_3, char_4) (((CPU_INT32U)((CPU_INT08U)(char_1)) << (3u * DEF_OCTET_NBR_BITS)) | \
477  ((CPU_INT32U)((CPU_INT08U)(char_2)) << (2u * DEF_OCTET_NBR_BITS)) | \
478  ((CPU_INT32U)((CPU_INT08U)(char_3)) << (1u * DEF_OCTET_NBR_BITS)) | \
479  ((CPU_INT32U)((CPU_INT08U)(char_4)) << (0u * DEF_OCTET_NBR_BITS)))
480 #endif
481 #endif
482 
483 
484 /*$PAGE*/
485 /*
486 *********************************************************************************************************
487 * FUNCTION PROTOTYPES
488 *
489 * Note(s) : (1) CPU interrupts disabled time measurement functions prototyped/defined only if
490 * CPU_CFG_INT_DIS_MEAS_EN #define'd in 'cpu_cfg.h'.
491 *
492 * (2) CPU_CntLeadZeros() prototyped/defined respectively in :
493 *
494 * (a) 'cpu.h'/'cpu_a.asm', if CPU_CFG_LEAD_ZEROS_ASM_PRESENT #define'd in 'cpu.h'/
495 * 'cpu_cfg.h' to enable assembly-version function
496 *
497 * (b) 'cpu_core.h'/'cpu_core.c', if CPU_CFG_LEAD_ZEROS_ASM_PRESENT NOT #define'd in 'cpu.h'/
498 * 'cpu_cfg.h' to enable C-source-version function otherwise
499 *********************************************************************************************************
500 */
501 
502 void CPU_Init (void);
503 
504 void CPU_SW_Exception (void);
505 
506 
507 
508 #if (CPU_CFG_NAME_EN == DEF_ENABLED) /* -------------- CPU NAME FNCTS -------------- */
509 void CPU_NameClr (void);
510 
511 void CPU_NameGet ( CPU_CHAR *p_name,
512  CPU_ERR *p_err);
513 
514 void CPU_NameSet (const CPU_CHAR *p_name,
515  CPU_ERR *p_err);
516 #endif
517 
518 
519 
520  /* --------------- CPU TS FNCTS --------------- */
521 #if (CPU_CFG_TS_32_EN == DEF_ENABLED)
522 CPU_TS32 CPU_TS_Get32 (void);
523 #endif
524 
525 #if (CPU_CFG_TS_64_EN == DEF_ENABLED)
526 CPU_TS64 CPU_TS_Get64 (void);
527 #endif
528 
529 #if (CPU_CFG_TS_EN == DEF_ENABLED)
530 void CPU_TS_Update (void);
531 #endif
532 
533 
534 #if (CPU_CFG_TS_TMR_EN == DEF_ENABLED) /* ------------- CPU TS TMR FNCTS ------------- */
535 CPU_TS_TMR_FREQ CPU_TS_TmrFreqGet (CPU_ERR *p_err);
536 
537 void CPU_TS_TmrFreqSet (CPU_TS_TMR_FREQ freq_hz);
538 #endif
539 
540 
541 
542 #ifdef CPU_CFG_INT_DIS_MEAS_EN /* -------- CPU INT DIS TIME MEAS FNCTS ------- */
543  /* See Note #1. */
544 CPU_TS_TMR CPU_IntDisMeasMaxCurReset(void);
545 
546 CPU_TS_TMR CPU_IntDisMeasMaxCurGet (void);
547 
548 CPU_TS_TMR CPU_IntDisMeasMaxGet (void);
549 
550 
551 void CPU_IntDisMeasStart (void);
552 
553 void CPU_IntDisMeasStop (void);
554 #endif
555 
556 
557 
558 #ifndef CPU_CFG_LEAD_ZEROS_ASM_PRESENT /* --------- CPU CNT LEAD ZEROS FNCTS --------- */
559 CPU_DATA CPU_CntLeadZeros (CPU_DATA val); /* See Note #2. */
560 #endif
561 
562 
563 /*$PAGE*/
564 /*
565 *********************************************************************************************************
566 * FUNCTION PROTOTYPES
567 * DEFINED IN PRODUCT'S BSP
568 *********************************************************************************************************
569 */
570 
571 /*
572 *********************************************************************************************************
573 * CPU_TS_TmrInit()
574 *
575 * Description : Initialize & start CPU timestamp timer.
576 *
577 * Argument(s) : none.
578 *
579 * Return(s) : none.
580 *
581 * Caller(s) : CPU_TS_Init().
582 *
583 * This function is an INTERNAL CPU module function & MUST be implemented by application/
584 * BSP function(s) [see Note #1] but MUST NOT be called by application function(s).
585 *
586 * Note(s) : (1) CPU_TS_TmrInit() is an application/BSP function that MUST be defined by the developer
587 * if either of the following CPU features is enabled :
588 *
589 * (a) CPU timestamps
590 * (b) CPU interrupts disabled time measurements
591 *
592 * See 'cpu_cfg.h CPU TIMESTAMP CONFIGURATION Note #1'
593 * & 'cpu_cfg.h CPU INTERRUPTS DISABLED TIME MEASUREMENT CONFIGURATION Note #1a'.
594 *
595 * (2) (a) Timer count values MUST be returned via word-size-configurable 'CPU_TS_TMR'
596 * data type.
597 *
598 * (1) If timer has more bits, truncate timer values' higher-order bits greater
599 * than the configured 'CPU_TS_TMR' timestamp timer data type word size.
600 *
601 * (2) Since the timer MUST NOT have less bits than the configured 'CPU_TS_TMR'
602 * timestamp timer data type word size; 'CPU_CFG_TS_TMR_SIZE' MUST be
603 * configured so that ALL bits in 'CPU_TS_TMR' data type are significant.
604 *
605 * In other words, if timer size is not a binary-multiple of 8-bit octets
606 * (e.g. 20-bits or even 24-bits), then the next lower, binary-multiple
607 * octet word size SHOULD be configured (e.g. to 16-bits). However, the
608 * minimum supported word size for CPU timestamp timers is 8-bits.
609 *
610 * See also 'cpu_cfg.h CPU TIMESTAMP CONFIGURATION Note #2'
611 * & 'cpu_core.h CPU TIMESTAMP DATA TYPES Note #1'.
612 *
613 * (b) Timer SHOULD be an 'up' counter whose values increase with each time count.
614 *
615 * (c) When applicable, timer period SHOULD be less than the typical measured time
616 * but MUST be less than the maximum measured time; otherwise, timer resolution
617 * inadequate to measure desired times.
618 *
619 * See also 'CPU_TS_TmrRd() Note #2'.
620 *********************************************************************************************************
621 */
622 
623 #if (CPU_CFG_TS_TMR_EN == DEF_ENABLED)
624 void CPU_TS_TmrInit(void);
625 #endif
626 
627 
628 /*$PAGE*/
629 /*
630 *********************************************************************************************************
631 * CPU_TS_TmrRd()
632 *
633 * Description : Get current CPU timestamp timer count value.
634 *
635 * Argument(s) : none.
636 *
637 * Return(s) : Timestamp timer count (see Notes #2a & #2b).
638 *
639 * Caller(s) : CPU_TS_Init(),
640 * CPU_TS_Get32(),
641 * CPU_TS_Get64(),
642 * CPU_IntDisMeasStart(),
643 * CPU_IntDisMeasStop().
644 *
645 * This function is an INTERNAL CPU module function & MUST be implemented by application/
646 * BSP function(s) [see Note #1] but SHOULD NOT be called by application function(s).
647 *
648 * Note(s) : (1) CPU_TS_TmrRd() is an application/BSP function that MUST be defined by the developer
649 * if either of the following CPU features is enabled :
650 *
651 * (a) CPU timestamps
652 * (b) CPU interrupts disabled time measurements
653 *
654 * See 'cpu_cfg.h CPU TIMESTAMP CONFIGURATION Note #1'
655 * & 'cpu_cfg.h CPU INTERRUPTS DISABLED TIME MEASUREMENT CONFIGURATION Note #1a'.
656 *
657 * (2) (a) Timer count values MUST be returned via word-size-configurable 'CPU_TS_TMR'
658 * data type.
659 *
660 * (1) If timer has more bits, truncate timer values' higher-order bits greater
661 * than the configured 'CPU_TS_TMR' timestamp timer data type word size.
662 *
663 * (2) Since the timer MUST NOT have less bits than the configured 'CPU_TS_TMR'
664 * timestamp timer data type word size; 'CPU_CFG_TS_TMR_SIZE' MUST be
665 * configured so that ALL bits in 'CPU_TS_TMR' data type are significant.
666 *
667 * In other words, if timer size is not a binary-multiple of 8-bit octets
668 * (e.g. 20-bits or even 24-bits), then the next lower, binary-multiple
669 * octet word size SHOULD be configured (e.g. to 16-bits). However, the
670 * minimum supported word size for CPU timestamp timers is 8-bits.
671 *
672 * See also 'cpu_cfg.h CPU TIMESTAMP CONFIGURATION Note #2'
673 * & 'cpu_core.h CPU TIMESTAMP DATA TYPES Note #1'.
674 *
675 * (b) Timer SHOULD be an 'up' counter whose values increase with each time count.
676 *
677 * (1) If timer is a 'down' counter whose values decrease with each time count,
678 * then the returned timer value MUST be ones-complemented.
679 *
680 * (c) (1) When applicable, the amount of time measured by CPU timestamps is
681 * calculated by either of the following equations :
682 *
683 * (A) Time measured = Number timer counts * Timer period
684 *
685 * where
686 *
687 * Number timer counts Number of timer counts measured
688 * Timer period Timer's period in some units of
689 * (fractional) seconds
690 * Time measured Amount of time measured, in same
691 * units of (fractional) seconds
692 * as the Timer period
693 *
694 * Number timer counts
695 * (B) Time measured = ---------------------
696 * Timer frequency
697 *
698 * where
699 *
700 * Number timer counts Number of timer counts measured
701 * Timer frequency Timer's frequency in some units
702 * of counts per second
703 * Time measured Amount of time measured, in seconds
704 *
705 * (2) Timer period SHOULD be less than the typical measured time but MUST be less
706 * than the maximum measured time; otherwise, timer resolution inadequate to
707 * measure desired times.
708 *********************************************************************************************************
709 */
710 
711 #if (CPU_CFG_TS_TMR_EN == DEF_ENABLED)
712 CPU_TS_TMR CPU_TS_TmrRd(void);
713 #endif
714 
715 
716 /*$PAGE*/
717 /*
718 *********************************************************************************************************
719 * CPU_TSxx_to_uSec()
720 *
721 * Description : Convert a 32-/64-bit CPU timestamp from timer counts to microseconds.
722 *
723 * Argument(s) : ts_cnts CPU timestamp (in timestamp timer counts [see Note #2aA]).
724 *
725 * Return(s) : Converted CPU timestamp (in microseconds [see Note #2aD]).
726 *
727 * Caller(s) : Application.
728 *
729 * This function is an (optional) CPU module application interface (API) function which
730 * MAY be implemented by application/BSP function(s) [see Note #1] & MAY be called by
731 * application function(s).
732 *
733 * Note(s) : (1) CPU_TS32_to_uSec()/CPU_TS64_to_uSec() are application/BSP functions that MAY be
734 * optionally defined by the developer when either of the following CPU features is
735 * enabled :
736 *
737 * (a) CPU timestamps
738 * (b) CPU interrupts disabled time measurements
739 *
740 * See 'cpu_cfg.h CPU TIMESTAMP CONFIGURATION Note #1'
741 * & 'cpu_cfg.h CPU INTERRUPTS DISABLED TIME MEASUREMENT CONFIGURATION Note #1a'.
742 *
743 * (2) (a) The amount of time measured by CPU timestamps is calculated by either of
744 * the following equations :
745 *
746 * 10^6 microseconds
747 * (1) Time measured = Number timer counts * ------------------- * Timer period
748 * 1 second
749 *
750 * Number timer counts 10^6 microseconds
751 * (2) Time measured = --------------------- * -------------------
752 * Timer frequency 1 second
753 *
754 * where
755 *
756 * (A) Number timer counts Number of timer counts measured
757 * (B) Timer frequency Timer's frequency in some units
758 * of counts per second
759 * (C) Timer period Timer's period in some units of
760 * (fractional) seconds
761 * (D) Time measured Amount of time measured,
762 * in microseconds
763 *
764 * (b) Timer period SHOULD be less than the typical measured time but MUST be less
765 * than the maximum measured time; otherwise, timer resolution inadequate to
766 * measure desired times.
767 *
768 * (c) Specific implementations may convert any number of CPU_TS32 or CPU_TS64 bits
769 * -- up to 32 or 64, respectively -- into microseconds.
770 *********************************************************************************************************
771 */
772 
773 #if (CPU_CFG_TS_32_EN == DEF_ENABLED)
774 CPU_INT64U CPU_TS32_to_uSec(CPU_TS32 ts_cnts);
775 #endif
776 
777 #if (CPU_CFG_TS_64_EN == DEF_ENABLED)
778 CPU_INT64U CPU_TS64_to_uSec(CPU_TS64 ts_cnts);
779 #endif
780 
781 
782 /*$PAGE*/
783 /*
784 *********************************************************************************************************
785 * CONFIGURATION ERRORS
786 *********************************************************************************************************
787 */
788 
789 #ifndef CPU_CFG_NAME_EN
790 #error "CPU_CFG_NAME_EN not #define'd in 'cpu_cfg.h'"
791 #error " [MUST be DEF_ENABLED ] "
792 #error " [ || DEF_DISABLED] "
793 
794 #elif ((CPU_CFG_NAME_EN != DEF_ENABLED ) && \
795  (CPU_CFG_NAME_EN != DEF_DISABLED))
796 #error "CPU_CFG_NAME_EN illegally #define'd in 'cpu_cfg.h'"
797 #error " [MUST be DEF_ENABLED ] "
798 #error " [ || DEF_DISABLED] "
799 
800 
801 #elif (CPU_CFG_NAME_EN == DEF_ENABLED)
802 
803 #ifndef CPU_CFG_NAME_SIZE
804 #error "CPU_CFG_NAME_SIZE not #define'd in 'cpu_cfg.h'"
805 #error " [MUST be >= 1] "
806 #error " [ && <= 255] "
807 
808 #elif ((CPU_CFG_NAME_SIZE < 1) || \
809  (CPU_CFG_NAME_SIZE > DEF_INT_08U_MAX_VAL))
810 #error "CPU_CFG_NAME_SIZE illegally #define'd in 'cpu_cfg.h'"
811 #error " [MUST be >= 1] "
812 #error " [ && <= 255] "
813 #endif
814 
815 #endif
816 
817 
818 
819 
820 #ifndef CPU_CFG_TS_32_EN
821 #error "CPU_CFG_TS_32_EN not #define'd in 'cpu_cfg.h'"
822 #error " [MUST be DEF_DISABLED] "
823 #error " [ || DEF_ENABLED ] "
824 
825 #elif ((CPU_CFG_TS_32_EN != DEF_DISABLED) && \
826  (CPU_CFG_TS_32_EN != DEF_ENABLED ))
827 #error "CPU_CFG_TS_32_EN illegally #define'd in 'cpu_cfg.h'"
828 #error " [MUST be DEF_DISABLED] "
829 #error " [ || DEF_ENABLED ] "
830 
831 #endif
832 
833 
834 #ifndef CPU_CFG_TS_64_EN
835 #error "CPU_CFG_TS_64_EN not #define'd in 'cpu_cfg.h'"
836 #error " [MUST be DEF_DISABLED] "
837 #error " [ || DEF_ENABLED ] "
838 
839 #elif ((CPU_CFG_TS_64_EN != DEF_DISABLED) && \
840  (CPU_CFG_TS_64_EN != DEF_ENABLED ))
841 #error "CPU_CFG_TS_64_EN illegally #define'd in 'cpu_cfg.h'"
842 #error " [MUST be DEF_DISABLED] "
843 #error " [ || DEF_ENABLED ] "
844 
845 #endif
846 
847  /* Correctly configured in 'cpu_core.h'; DO NOT MODIFY. */
848 #ifndef CPU_CFG_TS_EN
849 #error "CPU_CFG_TS_EN not #define'd in 'cpu_core.h'"
850 #error " [MUST be DEF_DISABLED] "
851 #error " [ || DEF_ENABLED ] "
852 
853 #elif ((CPU_CFG_TS_EN != DEF_DISABLED) && \
854  (CPU_CFG_TS_EN != DEF_ENABLED ))
855 #error "CPU_CFG_TS_EN illegally #define'd in 'cpu_core.h'"
856 #error " [MUST be DEF_DISABLED] "
857 #error " [ || DEF_ENABLED ] "
858 
859 #endif
860 
861 
862 /*$PAGE*/
863  /* Correctly configured in 'cpu_core.h'; DO NOT MODIFY. */
864 #ifndef CPU_CFG_TS_TMR_EN
865 #error "CPU_CFG_TS_TMR_EN not #define'd in 'cpu_core.h'"
866 #error " [MUST be DEF_DISABLED] "
867 #error " [ || DEF_ENABLED ] "
868 
869 #elif ((CPU_CFG_TS_TMR_EN != DEF_DISABLED) && \
870  (CPU_CFG_TS_TMR_EN != DEF_ENABLED ))
871 #error "CPU_CFG_TS_TMR_EN illegally #define'd in 'cpu_core.h'"
872 #error " [MUST be DEF_DISABLED] "
873 #error " [ || DEF_ENABLED ] "
874 
875 
876 #elif (CPU_CFG_TS_TMR_EN == DEF_ENABLED)
877 
878 #ifndef CPU_CFG_TS_TMR_SIZE
879 #error "CPU_CFG_TS_TMR_SIZE not #define'd in 'cpu_cfg.h' "
880 #error " [MUST be CPU_WORD_SIZE_08 8-bit timer]"
881 #error " [ || CPU_WORD_SIZE_16 16-bit timer]"
882 #error " [ || CPU_WORD_SIZE_32 32-bit timer]"
883 #error " [ || CPU_WORD_SIZE_64 64-bit timer]"
884 
885 #elif ((CPU_CFG_TS_TMR_SIZE != CPU_WORD_SIZE_08) && \
886  (CPU_CFG_TS_TMR_SIZE != CPU_WORD_SIZE_16) && \
887  (CPU_CFG_TS_TMR_SIZE != CPU_WORD_SIZE_32) && \
888  (CPU_CFG_TS_TMR_SIZE != CPU_WORD_SIZE_64))
889 #error "CPU_CFG_TS_TMR_SIZE illegally #define'd in 'cpu_cfg.h' "
890 #error " [MUST be CPU_WORD_SIZE_08 8-bit timer]"
891 #error " [ || CPU_WORD_SIZE_16 16-bit timer]"
892 #error " [ || CPU_WORD_SIZE_32 32-bit timer]"
893 #error " [ || CPU_WORD_SIZE_64 64-bit timer]"
894 #endif
895 
896 #endif
897 
898 
899 
900 #ifndef CPU_CFG_INT_DIS_MEAS_EN
901 #if 0 /* Optionally configured in 'cpu_cfg.h'; DO NOT MODIFY. */
902 #error "CPU_CFG_INT_DIS_MEAS_EN not #define'd in 'cpu_cfg.h'"
903 #endif
904 
905 #else
906 
907 #ifndef CPU_CFG_INT_DIS_MEAS_OVRHD_NBR
908 #error "CPU_CFG_INT_DIS_MEAS_OVRHD_NBR not #define'd in 'cpu_cfg.h' "
909 #error " [MUST be >= CPU_TIME_MEAS_NBR_MIN]"
910 #error " [ || <= CPU_TIME_MEAS_NBR_MAX]"
911 
912 #elif ((CPU_CFG_INT_DIS_MEAS_OVRHD_NBR < CPU_TIME_MEAS_NBR_MIN) || \
913  (CPU_CFG_INT_DIS_MEAS_OVRHD_NBR > CPU_TIME_MEAS_NBR_MAX))
914 #error "CPU_CFG_INT_DIS_MEAS_OVRHD_NBR illegally #define'd in 'cpu_cfg.h' "
915 #error " [MUST be >= CPU_TIME_MEAS_NBR_MIN]"
916 #error " [ || <= CPU_TIME_MEAS_NBR_MAX]"
917 
918 #endif
919 
920 #endif
921 
922 
923 
924 
925 #ifndef CPU_CFG_LEAD_ZEROS_ASM_PRESENT
926 #if 0 /* Optionally configured in 'cpu_cfg.h'; DO NOT MODIFY. */
927 #error "CPU_CFG_LEAD_ZEROS_ASM_PRESENT not #define'd in 'cpu.h'/'cpu_cfg.h'"
928 #endif
929 #endif
930 
931 
932 /*$PAGE*/
933 /*
934 *********************************************************************************************************
935 * MODULE END
936 *********************************************************************************************************
937 */
938 
939 #endif /* End of CPU core module include. */
940