Overload Directory & System Files

Example Path: examples/OverloadDirectory

Overload Directory Example

Overview

The overload directory lets a project replace any NetBurner system file with a local copy. The replacement applies to that project only. The installed SDK is never edited, so other projects are unaffected.

To overload a system file, mirror the file's path relative to the NNDK root inside the project's overload directory. The build system searches overload before $(NNDK_ROOT), so the local copy takes precedence:

System file	Project overload copy
<nburn>/nbrtos/source/timezones.cpp	<project root>/overload/nbrtos/source/timezones.cpp
<nburn>/nbrtos/include/predef-overload.h	<project root>/overload/nbrtos/include/predef-overload.h
<nburn>/libraries/include/crypto/platform/user_settings-overload.h	<project root>/overload/libraries/include/crypto/platform/user_settings-overload.h

For every system file except the configuration hook headers described below, the file you place in overload is a copy of the real system file, which you then edit.

This example overloads predef-overload.h to define the macro NBRTOS_STACKCHECK, which the SDK ships commented out. Turning on RTOS stack-integrity checking during development is a common reason to change system configuration.

Overloading System Configuration

nbrtos/include/predef.h holds the base system configuration as #define statements. It is a large header that changes between NNDK releases, so copying the whole file into overload and maintaining it can be complex and error prone.

The SDK avoids that. The last line of predef.h is:

#include <predef-overload.h>

The SDK ships nbrtos/include/predef-overload.h as an empty file. It exists only so a project can replace it. Put your configuration changes there and nothing else:

// <project root>/overload/nbrtos/include/predef-overload.h
#define NBRTOS_STACKCHECK     (1)

Because predef.h includes it last, your definitions get the final word over the SDK defaults, and an SDK upgrade cannot silently revert them.

Note

If the predef-overload.h hook did not exist, you would have to copy the whole predef.h to <project root>/overload/nbrtos/include/predef.h and edit it there. That is what earlier releases required, and it is still what you do for every other system file.

constants.h provides the same convenience through two hooks: constants-overload.h, included near the top of constants.h, and constants-overload-undefs.h, included after the header guard closes.

The wolfSSL settings in each platform libraries/include/crypto/platform/<PLATFORM>/user_settings.h have a hook of their own, user_settings-overload.h, included after all of the settings. Switches such as the crypto profiles take effect after it, so they work from the hook too. The TLS Key Logging example uses it to turn on NB_TLS_KEYLOG.

Include Order and Feature Sub-Options

Warning

predef.h evaluates its own conditional blocks before it includes predef-overload.h on the last line. A macro you define in predef-overload.h therefore cannot switch on an #ifdef block that appears earlier in predef.h.

If a feature has sub-options that predef.h sets inside #ifdef FEATURE, define those sub-options yourself in predef-overload.h. The On-board Cert Generation example shows the case: it must define AUTO_CERT_GEN_CHECK by hand, because predef.h had already skipped its #ifdef ENABLE_AUTOCERT_REGEN block by the time the overload was read.

constants.h behaves the opposite way. It includes constants-overload.h before its #ifndef X / #define X default blocks, so a plain #define there simply wins.

Overloading Any Other System File

The same directory mirroring works for source files. To change the names in the system timezone table, copy the real system file:

<nburn>/nbrtos/source/timezones.cpp

to:

<project root>/overload/nbrtos/source/timezones.cpp

then edit the copy. The build uses the project's timezones.cpp instead of the SDK's. The same applies to any header, any .cpp, and any web asset under the NNDK root.

Application Description

The application shows the effect of the overload:

• Initializes the network stack
• Enables system diagnostics
• Waits for an active network connection
• Prompts over serial to press any key to display per-task stack usage
• Calls OSDumpTCBStacks(), which the system library only builds when NBRTOS_STACKCHECK is defined
• Serves a web page that shows the same per-task stack usage live in a browser

Web Interface

Browse to the device's IP address. 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. 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 predef-overload.h defines NBRTOS_STACKCHECK. That is the overload's effect made visible. The page uses a self-contained stylesheet (plain CSS, no framework or CDN).

Files in This Example

src/main.cpp

Initializes the system, waits for the network, starts the web server, and runs an interactive serial loop that calls OSDumpTCBStacks().

overload/nbrtos/include/predef-overload.h

The project's copy of the configuration hook header. It contains one definition:

#define NBRTOS_STACKCHECK (1)

This enables run-time stack-integrity checking in the NetBurner system library, along with the stack and task diagnostic dump functions.

Setup Instructions for NBEclipse Projects

Command line builds need no makefile change. The build system picks up the overload directory by name. NBEclipse projects need the overload include directory added to the compiler include paths:

1. Right-click the project in the "Project Explorer"
2. Select "Properties"
3. Navigate to C/C++ Build -> Settings
4. Select GNU C++ Compiler -> Includes
5. Add the overload include folder to the "Include paths" list
6. For C code: add the same folder to GNU C Compiler -> Includes
7. Ensure the overload path sits above the paths beginning with "$(NNDK_ROOT)/"
8. Use the up and down arrow buttons to reposition it if necessary
9. Select "Apply and Close"

This example ships an nbeclipse-rules.json file that applies step 5 automatically on import.

Building and Maintenance

Note

After you add an overload folder to the "Include paths" list, or add a new file to the overload folder, clean and rebuild the NetBurner library once. Select "Clean NetBurner System Library" under the project's "Build Targets" pull-down. From then on, editing an overloaded file rebuilds the necessary library files automatically on each project build.

Application Behavior

1. The system initializes and waits for network connectivity
2. The application name and NNDK revision are printed
3. The program loops:
   • Prompts the user to press any key
   • Displays per-task stack usage with OSDumpTCBStacks()
   • Repeats

Important Notes

• The directory must be named overload, not override
• 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 here and should be removed for production code
• This example requires NetBurner hardware to execute

Related Examples That Use the Overload Directory

This example defines one macro (NBRTOS_STACKCHECK), but the same technique switches on capabilities throughout the SDK. Each example below ships its own overload/nbrtos/include/predef-overload.h defining a different macro:

• Stack Protection — defines NBRTOS_STACKOVERFLOW / NBRTOS_STACKUNDERFLOW for real-time stack overflow and underflow protection (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

The TLS Key Logging example applies the same technique to the wolfSSL settings. It ships overload/libraries/include/crypto/platform/user_settings-overload.h, which defines NB_TLS_KEYLOG.

For the mechanism itself, see Modifying System Files with Overload and Overload Directory.