Overload Directory & System Files

Example Path: examples/OverloadDirectory

Additional instructions if the overload directory is used in an NBEclipse project:

NetBurner Overload Directory Example

Overview

This example demonstrates how to use the NetBurner overload directory feature to override system files in a project-specific manner. The overload directory allows developers to modify system configuration files without affecting other projects or the original NNDK installation.

The Overload Directory Example is a basic demonstration of the overload directory in a project. The overload directory is used to override any system file by including local copies of system source files or headers. This allows the user to make changes to system files exclusively for a project. The overload directory provides an alternative to modifying the original system files, which would affect all projects.

To use this feature, the file to be overloaded should be placed in the overload directory under a directory structure that matches the file's location relative to the NNDK install directory.

This example application utilizes the overload directory to override predef.h (a NetBurner configuration header file). The overloaded predef.h defines the macro NBRTOS_STACKCHECK, which is commented out (not defined) by default. Enabling RTOS stack-integrity checking during development is a common, real-world reason to override predef.h.

To overload the predef.h header, the directory structure is replicated inside the overload directory. For example, predef.h is located in the following directory in the NNDK install:

    `/nburn/nbrtos/include/predef.h`

Therefore, the directory structure is replicated inside the overload directory with the following structure:

    `<project root>/overload/nbrtos/include/predef.h`

Note

Upon adding a overload folder to the "Include paths" list or adding a new file to the specified overload folder, the user will need to clean and rebuild the NetBurner Library. This can be done by selecting "Clean NetBurner System Library" under the "Build Targets" pull-down in the project. From that point on, modifying predef.h (or any overloaded source/header) will automatically rebuild the necessary files in the NetBurner Library when the project builds.

Application Description

The Overload Directory Example is a simple NetBurner application that showcases the overload directory functionality by:

• Initializing the network stack
• Enabling system diagnostics
• Waiting for an active network connection
• Continuously prompting the user to press any key to display per-task stack usage
• Using the OSDumpTCBStacks() function, which is only available when the NBRTOS_STACKCHECK macro is defined
• Serving a web page that shows the same per-task stack usage live in a browser

Web Interface

The example also serves a small web page (browse to the device's IP address) that displays the same per-task stack-usage table 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; this is the overload's effect made visible. The page uses a self-contained stylesheet (plain CSS, no framework or CDN).

Key Features

Overload Directory Functionality

The overload directory provides a mechanism to override any system file by including local copies of system source files or headers. This approach offers several advantages:

• Project-specific modifications: Changes only affect the current project
• Preserves original system files: No modification of the original NNDK installation
• Maintainable: Easy to track and manage project-specific customizations

Example Implementation

This project demonstrates overloading the predef.h system header file to define the NBRTOS_STACKCHECK macro, which enables run-time stack-integrity checking and the OSDumpTCBStacks() diagnostic function.

Directory Structure

The overload directory must replicate the directory structure of the file being overridden relative to the NNDK install directory.

Original System File Location

/nburn/nbrtos/include/predef.h

Overloaded File Location

<project root>/overload/nbrtos/include/predef.h

Files in This Example

main.cpp

The main application file that:

• Initializes the NetBurner system
• Waits for network connectivity
• Provides an interactive loop for displaying per-task stack usage
• Calls OSDumpTCBStacks() function (available due to overloaded predef.h)

predef-overload.h

Contains the overloaded configuration that defines:

#define NBRTOS_STACKCHECK (1)

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

ReadMe.txt

The original documentation explaining the overload directory concept and usage instructions.

Setup Instructions for NBEclipse Projects

If using this example in an NBEclipse project, additional configuration is required:

1. Right-click on 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: Also add the overloaded folder to GNU C Compiler -> Includes
7. Ensure the overload directory path is positioned above paths beginning with "$(NNDK_ROOT)/"
8. Use up/down arrow buttons to reposition if necessary
9. Select "Apply and close"

Building and Maintenance

Initial Setup

After adding an overload folder to the "Include paths" list or adding new files to the overload folder:

1. Clean and rebuild the NetBurner Library
2. Select "Clean NetBurner System Library" under the "Build Targets" pull-down

Ongoing Development

Once properly configured, modifying overloaded files (like predef.h) will automatically rebuild the necessary NetBurner Library files when the project builds.

Application Behavior

When running the application:

1. The system initializes and waits for network connectivity
2. Application name and NNDK revision information are displayed
3. The program enters an interactive loop:
   • Prompts user to press any key
   • Displays current per-task stack usage using OSDumpTCBStacks()
   • Repeats indefinitely

Important Notes

• The OSDumpTCBStacks() function is only available when NBRTOS_STACKCHECK is defined in predef.h
• Improper include path configuration will result in "OSDumpTCBStacks was not declared" build errors
• System diagnostics are enabled in this example and should be removed for production code
• This example requires NetBurner hardware to execute

Related Examples That Use the Overload Directory

This example overloads predef.h to enable one feature (NBRTOS_STACKCHECK), but the same technique is used throughout the SDK to switch on capabilities that are off by default. Each of these examples 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/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