Init Framework API Reference

This section documents the Initialization Framework API.

Overview

The Nexus Init Framework provides a compile-time automatic initialization system similar to Linux initcall. Initialization functions are registered at compile time using linker sections and executed in level order at system startup.

Initialization Levels

The framework defines six initialization levels that execute in order:

  1. BOARD - Board-level initialization (clock, power)

  2. PREV - Pre-initialization (memory, debug)

  3. BSP - BSP initialization (peripheral configuration)

  4. DRIVER - Driver initialization

  5. COMPONENT - Component initialization (middleware)

  6. APP - Application initialization

Core Functions

nx_status_t nx_init_run(void)

Execute all registered initialization functions.

This function iterates through all registered initialization functions in level order and executes them. If a function returns non-zero, the error is recorded but execution continues with remaining functions.

Returns:

NX_OK if all succeeded, NX_ERR_GENERIC if any failed

nx_status_t nx_init_get_stats(nx_init_stats_t *stats)

Get initialization statistics.

Returns statistics about initialization execution including total count, success count, failure count, and last error.

Parameters:

stats – [out] Pointer to statistics structure

Returns:

NX_OK on success, NX_ERR_NULL_PTR if stats is NULL

bool nx_init_is_complete(void)

Check if all initializations completed successfully.

This function checks if all initialization functions executed successfully (no failures recorded).

Returns:

true if all succeeded, false if any failed

Type Definitions

typedef int (*nx_init_fn_t)(void)

Initialization function type.

Return:

0 on success, non-zero error code on failure

enum nx_init_level_t

Initialization level enumeration.

Defines the order in which initialization functions are executed. Lower levels execute before higher levels. Level 0 and 7 are reserved for internal boundary markers.

Values:

enumerator NX_INIT_LEVEL_BOARD

Board-level init (clock, power)

enumerator NX_INIT_LEVEL_PREV

Pre-initialization (memory, debug)

enumerator NX_INIT_LEVEL_BSP

BSP initialization (peripheral config)

enumerator NX_INIT_LEVEL_DRIVER

Driver initialization

enumerator NX_INIT_LEVEL_COMPONENT

Component init (middleware)

enumerator NX_INIT_LEVEL_APP

Application initialization

enumerator NX_INIT_LEVEL_MAX

Maximum level (boundary marker)

struct nx_init_stats_s

Initialization statistics structure.

Public Members

uint16_t total_count

Total number of init functions

uint16_t success_count

Number of successful initializations

uint16_t fail_count

Number of failed initializations

int last_error

Last error code returned

Export Macros

Use these macros to register initialization functions at compile time:

NX_INIT_BOARD_EXPORT(fn)

Export board-level initialization function.

Board-level initialization runs first (level 1). Use for clock configuration, power management, etc.

Parameters:

  • fn – [in] Function pointer

NX_INIT_PREV_EXPORT(fn)

Export pre-initialization function.

Pre-initialization runs at level 2. Use for memory initialization, debug setup, etc.

Parameters:

  • fn – [in] Function pointer

NX_INIT_BSP_EXPORT(fn)

Export BSP initialization function.

BSP initialization runs at level 3. Use for peripheral configuration, pin muxing, etc.

Parameters:

  • fn – [in] Function pointer

NX_INIT_DRIVER_EXPORT(fn)

Export driver initialization function.

Driver initialization runs at level 4. Use for device driver initialization.

Parameters:

  • fn – [in] Function pointer

NX_INIT_COMPONENT_EXPORT(fn)

Export component initialization function.

Component initialization runs at level 5. Use for middleware and component initialization.

Parameters:

  • fn – [in] Function pointer

NX_INIT_APP_EXPORT(fn)

Export application initialization function.

Application initialization runs last (level 6). Use for application-specific initialization.

Parameters:

  • fn – [in] Function pointer

Usage Example

#include "nx_init.h"

/* Board-level initialization function */
static int board_clock_init(void) {
    /* Configure system clock */
    return 0;  /* Success */
}

/* Register the function to run at BOARD level */
NX_INIT_BOARD_EXPORT(board_clock_init);

/* Driver initialization function */
static int uart_driver_init(void) {
    /* Initialize UART driver */
    return 0;  /* Success */
}

/* Register the function to run at DRIVER level */
NX_INIT_DRIVER_EXPORT(uart_driver_init);

/* In main() */
int main(void) {
    nx_status_t status;

    /* Run all registered initialization functions */
    status = nx_init_run();
    if (status != NX_OK) {
        /* Handle initialization failure */
    }

    /* Check if all initializations succeeded */
    if (!nx_init_is_complete()) {
        /* Some initializations failed */
        nx_init_stats_t stats;
        nx_init_get_stats(&stats);
        /* Log or handle the failure */
    }

    /* Application code */
    while (1) {
        /* ... */
    }
}

Thread Safety

The Init Framework is not thread-safe. All initialization functions should be called during system startup before any threads are created. The nx_init_run() function should only be called once from the main thread.

Notes

  • Initialization functions execute in level order (BOARD → PREV → BSP → DRIVER → COMPONENT → APP)

  • Within the same level, execution order is undefined

  • If an initialization function fails (returns non-zero), execution continues with remaining functions

  • Use nx_init_get_stats() to check for failures after nx_init_run()

  • Initialization functions should be lightweight and avoid blocking operations

See Also