NetBurner 3.5.8
PDF Version
Stack Protection

Example Path: examples/StackProtection

Stack Protection Example

This example demonstrates the NetBurner RTOS's run-time stack overflow / underflow protection. It intentionally triggers stack violations in a controlled way so you can watch the protection mechanism catch them, and it serves a web page that shows live per-task stack usage.

Overview

When stack protection is enabled, the RTOS watches each task's stack at run time and faults the task the instant a read or write crosses its boundary — instead of letting it silently corrupt adjacent memory. This example turns that protection on, prints the current stack range, and offers two destructive demos (over the serial menu) that deliberately overflow the stack so the protector fires.

Enabling Stack Protection

The protection features are switched on through the project's overload copy of predef.h (overload/nbrtos/include/predef-overload.h), so they apply to this project only without editing the shared SDK header:

#define NBRTOS_STACKCHECK (1)
#define NBRTOS_STACKOVERFLOW (1)
#define NBRTOS_STACKUNDERFLOW (1) // ARM only -- see below
  • NBRTOS_STACKCHECK enables run-time stack tracking and the OSDumpTCBStacks() diagnostic.
  • NBRTOS_STACKOVERFLOW faults on a write/read past the bottom of the stack (an overflow).
  • NBRTOS_STACKUNDERFLOW faults on a write/read past the top of the stack (an underflow).

With these set, the build system adds the -fstack-check compiler flag and init() calls EnableOSStackProtector() automatically — no manual steps are required.

ARM vs. Coldfire

  • ARM Cortex-M parts can watch two memory ranges, so they monitor overflow and underflow at the same time.
  • Coldfire parts can watch only one range, so they must pick overflow or underflow (typically overflow).

The overload header selects the right combination for the target automatically, so the same project builds correctly on either architecture.

Note
If you add the overload folder to an NBEclipse project's "Include paths", you must clean and rebuild the NetBurner system library once ("Clean NetBurner System Library" under the project's "Build Targets"). After that, changes to the overloaded predef.h rebuild the necessary library files automatically on each project build.

Application Structure

  • bufferOverflow() — writes past the end of a local array, marching further into the stack on each pass until it crosses the guarded boundary.
  • callStackOverflow() — recurses without ever returning, so reserved stack grows without bound.
  • ShowStackUsage() — the CPPCALL handler that renders the live stack table for the web page.
  • UserMain() — initializes the system, starts the web server, prints the stack range, and runs the interactive serial menu.

Serial Menu

Connect to the device's serial debug port (115200 baud). The menu offers:

  1. Buffer Overflow — triggers an overflow by writing past the end of a buffer.
  2. Call Stack Overflow — triggers an overflow through unbounded recursion.

Each demo deliberately faults the offending task — exactly what you want instead of silent memory corruption. Because tripping the protector faults the task, these demos run over serial, not the web page.

Web Interface

The example also serves a small web page (browse to the device's IP address) that displays per-task stack usage live in a browser. The page's <!--CPPCALL ShowStackUsage --> tag hands the HTTP socket to a function in main.cpp, which briefly redirects its stdout to that socket and calls the same OSDumpTCBStacks() used over serial — so the browser shows exactly what the device prints. A Refresh** button (and optional 2-second auto-refresh) re-fetches the table.

The Min Free column — each task's stack high-water mark — appears only because the overloaded predef.h defines NBRTOS_STACKCHECK, and it's a handy way to right-size a task's stack. The page also documents the protection macros and the destructive serial demos. It uses a self-contained stylesheet (plain CSS, no framework or CDN).

Important Notes

  • OSDumpTCBStacks() is only available when NBRTOS_STACKCHECK is defined; an incorrect overload include path produces an "OSDumpTCBStacks was not declared" build error.
  • System diagnostics are enabled in this example and should be removed for production code.
  • This example intentionally creates stack overflow conditions for educational purposes. Do not use these techniques in production code — they exist only to demonstrate the protection mechanism.
  • This example requires NetBurner hardware to execute.

Related Examples

Stack protection is switched on with the same overload-directory technique used throughout the SDK to enable features that are off by default. Each of these examples ships its own overload/nbrtos/include/predef-overload.h defining a different macro:

  • Overload Directory — introduces the overload technique itself and shows a live stack-usage table (the closest cousin to this example)
  • Profiler — defines NBRTOS_TIME to enable per-task run-time profiling
  • Multihome — defines MULTIHOME to run multiple IP interfaces on one device
  • Telnet Command — defines NB_SSH_SUPPORTED to add SSH to the command processor
  • Simple SNMP — defines ENABLE_SNMP to enable the SNMP agent