硬件抽象层 (HAL)

概述

Nexus HAL 为不同 MCU 平台的硬件外设提供统一的面向对象接口。它使用工厂模式创建设备实例，并采用基于接口的设计进行操作。

主要特性：

  • 工厂模式用于设备创建和生命周期管理

  • 基于接口的设计，跨外设提供一致的 API

  • 引用计数实现安全的资源管理

  • 支持同步和异步操作

  • 电源管理和诊断接口

架构

HAL 分为以下几层：

+------------------+
|   Application    |
+------------------+
       |
+------------------+
|   nx_factory     |  Device creation and management
+------------------+
       |
+------------------+
|   Interfaces     |  nx_gpio_t, nx_uart_t, nx_spi_t, etc.
+------------------+
       |
+------------------+
|   Platform HAL   |  STM32F4, Native, etc.
+------------------+

支持的外设

模块

接口

描述

GPIO

nx_gpio_t

通用输入输出

UART

nx_uart_t

串行通信

SPI

nx_spi_t

SPI 总线

I2C

nx_i2c_t

I2C 总线

定时器

nx_timer_t

硬件定时器

ADC

nx_adc_t

模拟输入

快速开始

Include the main header:

#include "hal/nx_hal.h"

Initialize and use:

int main(void)
{
    /* Initialize HAL */
    nx_hal_init();

    /* Get a GPIO device */
    nx_gpio_t* led = nx_factory_gpio(0, 5);  /* Port A, Pin 5 */
    if (led) {
        led->write(led, 1);  /* Turn on */
        nx_factory_gpio_release(led);
    }

    /* Cleanup */
    nx_hal_deinit();
    return 0;
}

GPIO 模块

Get GPIO with default configuration:

nx_gpio_t* gpio = nx_factory_gpio(port, pin);

Get GPIO with custom configuration:

nx_gpio_config_t cfg = {
    .mode  = NX_GPIO_MODE_OUTPUT_PP,
    .pull  = NX_GPIO_PULL_NONE,
    .speed = NX_GPIO_SPEED_LOW,
};

nx_gpio_t* led = nx_factory_gpio_with_config(0, 5, &cfg);

Operations:

/* Write */
led->write(led, 1);  /* High */
led->write(led, 0);  /* Low */

/* Read */
uint8_t state = led->read(led);

/* Toggle */
led->toggle(led);

/* Runtime configuration */
led->set_mode(led, NX_GPIO_MODE_INPUT);
led->set_pull(led, NX_GPIO_PULL_UP);

/* Release when done */
nx_factory_gpio_release(led);

External interrupt:

void button_callback(void* ctx)
{
    /* Handle button press */
}

nx_gpio_t* btn = nx_factory_gpio(0, 0);
btn->set_mode(btn, NX_GPIO_MODE_INPUT);
btn->set_exti(btn, NX_GPIO_EXTI_FALLING, button_callback, NULL);

UART 模块

Get UART with default configuration:

nx_uart_t* uart = nx_factory_uart(0);

Get UART with custom configuration:

nx_uart_config_t cfg = {
    .baudrate     = 115200,
    .word_length  = 8,
    .stop_bits    = 1,
    .parity       = 0,  /* None */
    .flow_control = 0,  /* None */
};

nx_uart_t* uart = nx_factory_uart_with_config(0, &cfg);

Synchronous operations:

nx_tx_sync_t* tx = uart->get_tx_sync(uart);
nx_rx_sync_t* rx = uart->get_rx_sync(uart);

/* Transmit with timeout */
const char* msg = "Hello, Nexus!";
tx->send(tx, (uint8_t*)msg, strlen(msg), 1000);

/* Receive with timeout */
uint8_t buf[64];
rx->receive(rx, buf, sizeof(buf), 1000);

Asynchronous operations:

nx_tx_async_t* tx = uart->get_tx_async(uart);
nx_rx_async_t* rx = uart->get_rx_async(uart);

/* Non-blocking send */
tx->send(tx, data, len);

/* Check available data */
size_t avail = rx->available(rx);
if (avail > 0) {
    size_t read = rx->read(rx, buf, avail);
}

/* Set receive callback */
rx->set_callback(rx, my_rx_callback, NULL);

Release when done:

nx_factory_uart_release(uart);

SPI 模块

Get SPI device:

nx_spi_t* spi = nx_factory_spi(0);

/* Or with configuration */
nx_spi_config_t cfg = {
    .clock_hz   = 1000000,
    .mode       = 0,
    .bit_order  = NX_SPI_MSB_FIRST,
};
nx_spi_t* spi = nx_factory_spi_with_config(0, &cfg);

/* Use SPI... */

nx_factory_spi_release(spi);

I2C 模块

Get I2C device:

nx_i2c_t* i2c = nx_factory_i2c(0);

/* Or with configuration */
nx_i2c_config_t cfg = {
    .clock_hz = 100000,  /* 100 kHz */
};
nx_i2c_t* i2c = nx_factory_i2c_with_config(0, &cfg);

/* Use I2C... */

nx_factory_i2c_release(i2c);

错误处理

所有工厂函数在失败时返回 NULL。接口方法返回 nx_status_t：

nx_gpio_t* gpio = nx_factory_gpio(port, pin);
if (!gpio) {
    /* Handle error: device not available */
    return -1;
}

nx_status_t status = gpio->set_mode(gpio, NX_GPIO_MODE_OUTPUT_PP);
if (status != NX_OK) {
    /* Handle error */
}

常见状态码：

  • NX_OK - 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_lifecycle_t 接口支持生命周期操作：

nx_gpio_t* gpio = nx_factory_gpio(0, 5);
nx_lifecycle_t* lc = gpio->get_lifecycle(gpio);

/* Suspend device */
lc->suspend(lc);

/* Resume device */
lc->resume(lc);

电源管理

设备通过 nx_power_t 接口支持电源管理：

nx_uart_t* uart = nx_factory_uart(0);
nx_power_t* pwr = uart->get_power(uart);

/* Enter low power mode */
pwr->set_mode(pwr, NX_POWER_MODE_SLEEP);

/* Wake up */
pwr->set_mode(pwr, NX_POWER_MODE_NORMAL);

API 参考

完整 API 文档请参阅 HAL API 参考。