SFBHWMisc.h File Reference

Miscellaneous hardware-specific routines. More...

#include "SFBTypes.h"
#include "lpc/irq.h"

Include dependency graph for SFBHWMisc.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Defines
#define	STACK_CANARY_VALUE   0x2c50904e
	A special code stored in stackCanary, used by API_ASSERT_STACK_OK to help detect stack overflows.
#define	API_ASSERT_STACK_OK()   API_ASSERT(stackCanary==STACK_CANARY_VALUE,E_BUG_STACK_CORRUPT)
	Assert that the stackCanary variable still has its special value of STACK_CANARY_VALUE, which is unlikely to be the case if the stack has overflowed into the sketch RAM area.
Functions
void	facePrintTimestamp (u8 face)
	Print a timestamp to face.
u32	getCurrentStackSpace ()
	Estimate how much more space is currently available on the stack.
u32	getMinimumStackSpace ()
	Estimate the minimum amount of stack space that has been available at any point during the running of the current sketch so far.
Variables
volatile u32	stackCanary
	A variable placed at the end of sketch RAM usage, initialized with STACK_CANARY_VALUE, and checked by API_ASSERT_STACK_OK to help detect stack overflows.

---

Detailed Description

Miscellaneous hardware-specific routines.

Author:

David H. Ackley.

Date:

(C) 2009 All rights reserved.

Code License:

The GNU Lesser General Public License

License Note:

All code samples shown in documentation are placed into the public domain.

---

Define Documentation

#define STACK_CANARY_VALUE   0x2c50904e

A special code stored in stackCanary, used by API_ASSERT_STACK_OK to help detect stack overflows.

---

Function Documentation

void facePrintTimestamp

(

u8

face

)

Print a timestamp to face.

The output depending on the context: In host programs the date and time are printed; in boards the equivalent of seconds() is printed (along with three decimal places), so the printed timestamps will roll over after about 180 years of uptime.

u32 getCurrentStackSpace

(

)

Estimate how much more space is currently available on the stack.

Provides an estimate of the current stack depth, as of the call on this function.

See getMinimumStackSpace().

Returns:

an estimate of the number of bytes of available stack space when this function was called.

Since:

0.9.10

u32 getMinimumStackSpace

(

)

Estimate the minimum amount of stack space that has been available at any point during the running of the current sketch so far.

If this number ever gets 'too close' to zero, the sketch is risking a potential stack overflow condition.

Note that if stack space does run out, all bets are off about the resulting sketch behavior. If you are lucky, the sketch will die blinking with a E_BUG_STACK_CORRUPT code, but that is by no means assured. It might instead die with E_HW_UNDEF, or E_HW_DABT, or E_HW_PABT, or some other blink code, or it may just hang rather than dying, etc. etc. etc.

How close to zero is 'too close'? Well, that's somewhat up to you, the nature of your sketch, and your tolerance for risk. Be aware that the invocations of interrupt handlers do tie up space on the same system stack that regular functions use, and that is true both for user-written interrupt handlers -- e.g., as used with hardware timers -- as well as the core software interrupt handlers that deal with serial I/O and the main timer.

If you feel you've managed to run your sketch through pretty much all the worst (meaning: busiest, most heavily loaded, most complex execution path of the most complicated functions) you can reasonably expect, and getMinimumStackSpace() is still returning a number in the 100's or more, you may probably be okay. With a number in the 1000's you might probably feel pretty comforable.

But, it all depends on the sketch! For example, this sketch:

   void hugeFunction() {
     u32 buf[10000];   // buf is too big to fit in RAM..
     for (u32 i = 0; i < 10000; ++i) buf[i] = 0;
     println(buf[1]);  // keeps compiler from optimizing stuff away..
   }
   void setup() { }
   void loop() {
     if (random(1000000)==0) hugeFunction();
   }

will probably be fine for hours.. but as soon as hugeFunction is actually called -- with its hopelessly oversized array -- bad things will ensue.

Returns:

an estimate of the minimum number of bytes of stack space that have been available at any time during the current running of this sketch.

Since:

0.9.10

---

Variable Documentation

volatile u32 stackCanary

A variable placed at the end of sketch RAM usage, initialized with STACK_CANARY_VALUE, and checked by API_ASSERT_STACK_OK to help detect stack overflows.