HAL API Reference

This section documents the Hardware Abstraction Layer (HAL) API.

Overview

The Nexus HAL uses a factory pattern for device creation and interface-based design for operations. Include hal/nx_hal.h to access all HAL functionality.

Core Functions

/* Initialize HAL subsystem */
nx_status_t nx_hal_init(void);

/* Deinitialize HAL subsystem */
nx_status_t nx_hal_deinit(void);

/* Check if HAL is initialized */
bool nx_hal_is_initialized(void);

/* Get HAL version string */
const char* nx_hal_get_version(void);

Status Codes

typedef enum {
    NX_OK = 0,           /* Success */
    NX_ERR_PARAM,        /* Invalid parameter */
    NX_ERR_STATE,        /* Invalid state */
    NX_ERR_TIMEOUT,      /* Operation timeout */
    NX_ERR_BUSY,         /* Resource busy */
    NX_ERR_NO_MEM,       /* Out of memory */
    NX_ERR_NOT_FOUND,    /* Resource not found */
    NX_ERR_NOT_SUPPORTED,/* Operation not supported */
    NX_ERR_IO,           /* I/O error */
} nx_status_t;

GPIO API

Factory Functions:

/* Get GPIO device */
nx_gpio_t* nx_factory_gpio(uint8_t port, uint8_t pin);

/* Get GPIO device with configuration */
nx_gpio_t* nx_factory_gpio_with_config(uint8_t port, uint8_t pin,
                                       const nx_gpio_config_t* cfg);

/* Release GPIO device */
void nx_factory_gpio_release(nx_gpio_t* gpio);

Configuration:

typedef enum {
    NX_GPIO_MODE_INPUT = 0,
    NX_GPIO_MODE_OUTPUT_PP,
    NX_GPIO_MODE_OUTPUT_OD,
    NX_GPIO_MODE_AF_PP,
    NX_GPIO_MODE_AF_OD,
    NX_GPIO_MODE_ANALOG,
} nx_gpio_mode_t;

typedef enum {
    NX_GPIO_PULL_NONE = 0,
    NX_GPIO_PULL_UP,
    NX_GPIO_PULL_DOWN,
} nx_gpio_pull_t;

typedef enum {
    NX_GPIO_SPEED_LOW = 0,
    NX_GPIO_SPEED_MEDIUM,
    NX_GPIO_SPEED_HIGH,
    NX_GPIO_SPEED_VERY_HIGH,
} nx_gpio_speed_t;

typedef struct {
    nx_gpio_mode_t mode;
    nx_gpio_pull_t pull;
    nx_gpio_speed_t speed;
    uint8_t af_index;
} nx_gpio_config_t;

Interface:

struct nx_gpio_s {
    /* Basic operations */
    uint8_t (*read)(nx_gpio_t* self);
    void (*write)(nx_gpio_t* self, uint8_t state);
    void (*toggle)(nx_gpio_t* self);

    /* Runtime configuration */
    nx_status_t (*set_mode)(nx_gpio_t* self, nx_gpio_mode_t mode);
    nx_status_t (*set_pull)(nx_gpio_t* self, nx_gpio_pull_t pull);
    nx_status_t (*get_config)(nx_gpio_t* self, nx_gpio_config_t* cfg);
    nx_status_t (*set_config)(nx_gpio_t* self, const nx_gpio_config_t* cfg);

    /* Interrupt configuration */
    nx_status_t (*set_exti)(nx_gpio_t* self, nx_gpio_exti_trig_t trig,
                            nx_gpio_exti_callback_t cb, void* ctx);
    nx_status_t (*clear_exti)(nx_gpio_t* self);

    /* Base interfaces */
    nx_lifecycle_t* (*get_lifecycle)(nx_gpio_t* self);
    nx_power_t* (*get_power)(nx_gpio_t* self);
};

UART API

Factory Functions:

/* Get UART device */
nx_uart_t* nx_factory_uart(uint8_t index);

/* Get UART device with configuration */
nx_uart_t* nx_factory_uart_with_config(uint8_t index,
                                       const nx_uart_config_t* cfg);

/* Release UART device */
void nx_factory_uart_release(nx_uart_t* uart);

Configuration:

typedef struct {
    uint32_t baudrate;
    uint8_t word_length;   /* 8 or 9 */
    uint8_t stop_bits;     /* 1 or 2 */
    uint8_t parity;        /* 0=none, 1=odd, 2=even */
    uint8_t flow_control;  /* 0=none, 1=rts, 2=cts, 3=rts_cts */
    bool dma_tx_enable;
    bool dma_rx_enable;
    size_t tx_buf_size;
    size_t rx_buf_size;
} nx_uart_config_t;

Interface:

struct nx_uart_s {
    /* Operation interfaces */
    nx_tx_async_t* (*get_tx_async)(nx_uart_t* self);
    nx_rx_async_t* (*get_rx_async)(nx_uart_t* self);
    nx_tx_sync_t* (*get_tx_sync)(nx_uart_t* self);
    nx_rx_sync_t* (*get_rx_sync)(nx_uart_t* self);

    /* Runtime configuration */
    nx_status_t (*set_baudrate)(nx_uart_t* self, uint32_t baudrate);
    nx_status_t (*get_config)(nx_uart_t* self, nx_uart_config_t* cfg);
    nx_status_t (*set_config)(nx_uart_t* self, const nx_uart_config_t* cfg);

    /* Base interfaces */
    nx_lifecycle_t* (*get_lifecycle)(nx_uart_t* self);
    nx_power_t* (*get_power)(nx_uart_t* self);
    nx_diagnostic_t* (*get_diagnostic)(nx_uart_t* self);

    /* Diagnostics */
    nx_status_t (*get_stats)(nx_uart_t* self, nx_uart_stats_t* stats);
    nx_status_t (*clear_errors)(nx_uart_t* self);
};

TX/RX Interfaces:

/* Synchronous TX */
struct nx_tx_sync_s {
    nx_status_t (*send)(nx_tx_sync_t* self, const uint8_t* data,
                        size_t len, uint32_t timeout_ms);
};

/* Synchronous RX */
struct nx_rx_sync_s {
    nx_status_t (*receive)(nx_rx_sync_t* self, uint8_t* data,
                           size_t len, uint32_t timeout_ms);
};

/* Asynchronous TX */
struct nx_tx_async_s {
    nx_status_t (*send)(nx_tx_async_t* self, const uint8_t* data, size_t len);
    size_t (*get_free_space)(nx_tx_async_t* self);
    bool (*is_busy)(nx_tx_async_t* self);
};

/* Asynchronous RX */
struct nx_rx_async_s {
    size_t (*read)(nx_rx_async_t* self, uint8_t* data, size_t max_len);
    size_t (*available)(nx_rx_async_t* self);
    nx_status_t (*set_callback)(nx_rx_async_t* self, void (*cb)(void*), void* ctx);
};

SPI API

Factory Functions:

nx_spi_t* nx_factory_spi(uint8_t index);
nx_spi_t* nx_factory_spi_with_config(uint8_t index, const nx_spi_config_t* cfg);
void nx_factory_spi_release(nx_spi_t* spi);

I2C API

Factory Functions:

nx_i2c_t* nx_factory_i2c(uint8_t index);
nx_i2c_t* nx_factory_i2c_with_config(uint8_t index, const nx_i2c_config_t* cfg);
void nx_factory_i2c_release(nx_i2c_t* i2c);

Timer API

Factory Functions:

nx_timer_t* nx_factory_timer(uint8_t index);
nx_timer_t* nx_factory_timer_with_config(uint8_t index, const nx_timer_config_t* cfg);
void nx_factory_timer_release(nx_timer_t* timer);

ADC API

Factory Functions:

nx_adc_t* nx_factory_adc(uint8_t index);
nx_adc_t* nx_factory_adc_with_config(uint8_t index, const nx_adc_config_t* cfg);
void nx_factory_adc_release(nx_adc_t* adc);

Device Enumeration

typedef struct {
    const char* name;
    const char* type;
    nx_device_state_t state;
    uint8_t ref_count;
} nx_device_info_t;

/* Enumerate all devices */
size_t nx_factory_enumerate(nx_device_info_t* list, size_t max_count);

Base Interfaces

Lifecycle Interface:

struct nx_lifecycle_s {
    nx_status_t (*init)(nx_lifecycle_t* self);
    nx_status_t (*deinit)(nx_lifecycle_t* self);
    nx_status_t (*suspend)(nx_lifecycle_t* self);
    nx_status_t (*resume)(nx_lifecycle_t* self);
    nx_device_state_t (*get_state)(nx_lifecycle_t* self);
};

Power Interface:

typedef enum {
    NX_POWER_MODE_NORMAL = 0,
    NX_POWER_MODE_SLEEP,
    NX_POWER_MODE_DEEP_SLEEP,
} nx_power_mode_t;

struct nx_power_s {
    nx_status_t (*set_mode)(nx_power_t* self, nx_power_mode_t mode);
    nx_power_mode_t (*get_mode)(nx_power_t* self);
};

Diagnostic Interface:

struct nx_diagnostic_s {
    nx_status_t (*self_test)(nx_diagnostic_t* self);
    nx_status_t (*get_error_count)(nx_diagnostic_t* self, uint32_t* count);
    nx_status_t (*clear_errors)(nx_diagnostic_t* self);
};