System Initialization¶

NSX provides a modular system initialization API in nsx_system.h that replaces ad-hoc startup boilerplate with composable, order-aware building blocks.

Quick Start¶

#include "nsx_system.h"

int main(void) {
    // One call sets up: core runtime, caches, HP mode, ITM debug, SpotManager
    nsx_system_config_t cfg = nsx_system_development;
    nsx_system_init(&cfg);

    ns_printf("Hello from NSX\n");
}

Presets¶

Three built-in presets cover the most common scenarios:

Start from a preset and override individual fields:

nsx_system_config_t cfg = nsx_system_development;
cfg.skip_bsp_init = true;   // skip the 2-second BSP stabilization delay
cfg.debug.transport = NSX_DEBUG_UART;  // use UART instead of SWO
nsx_system_init(&cfg);

What nsx_system_init() Does¶

The init function performs six steps in a fixed, safe order:

flowchart TD
    A["1. ns_core_init()"] --> B["2. Hardware init"]
    B --> C["3. Cache enable"]
    C --> D["4. Performance mode"]
    D --> E["5. SpotManager profile"]
    E --> F["6. Debug output"]
    B -- "skip_bsp_init = false" --> B1["am_bsp_low_power_init()"]
    B -- "skip_bsp_init = true" --> B2["Minimal: CPDLP + FPU"]

Ordering matters — each step depends on the previous:

1. Core runtime — gates all other NSX API calls
2. Hardware init — enables cache power domain (CPDLP), SpotManager, FPU
3. Cache — requires CPDLP from step 2 (silently fails without it on Apollo5)
4. Performance mode — HP clock (burst mode on Apollo3, MCU mode select on Apollo4+)
5. SpotManager profile — requires SpotManager init from step 2
6. Debug output — must come after BSP init (which disables debug for low power)

Performance Modes¶

The nsx_perf_mode_e enum maps to SoC-specific clock configurations:

Debug Output¶

Two transports are supported:

After init, use ns_printf() for output — it routes through whichever backend was configured.

Fine-Grained Control¶

For full control, skip nsx_system_init() and call individual building blocks in order:

#include "nsx_system.h"

int main(void) {
    // 1. Core runtime (required first)
    ns_core_config_t core_cfg = { .api = &ns_core_V1_0_0 };
    ns_core_init(&core_cfg);

    // 2. Hardware init
    nsx_minimal_hw_init();       // fast: CPDLP + FPU, no 2s delay
    // nsx_hw_init();            // full: am_bsp_low_power_init()

    // 3. Cache (requires CPDLP from step 2)
    nsx_cache_enable();          // from nsx_mem.h

    // 4. Performance mode
    nsx_set_perf_mode(NSX_PERF_HIGH);

    // 5. Debug output
    nsx_debug_config_t dbg = { .transport = NSX_DEBUG_ITM };
    nsx_debug_init(&dbg);

    // 6. Application code...
    ns_printf("Ready\n");
}

nsx_hw_init() vs nsx_minimal_hw_init()¶

Use nsx_minimal_hw_init() when you want fast startup during development and don't need full power optimization. Use nsx_hw_init() for production deployments where power efficiency matters.

Platform Backends¶

nsx_system is split into platform-independent sequencing (nsx_system.c) and per-SoC backends that implement five functions:

The correct backend is selected automatically by CMake via NSX_SOC_FAMILY.

Common Pitfalls¶