平台与系统¶

FreeRTOS 启动与钩子、HAL 公共定义、系统控制、时钟、定时器、看门狗、RTC 与内存分配辅助。说明取自头文件注释（英文）。

freertos_app_hooks.h¶

#include "freertos_app_hooks.h"（源代码）

FreeRTOS application support: platform start-up, heap set-up and stack report.

The matching source file also provides weak default FreeRTOS hooks (stack overflow, malloc failed, idle, static idle and timer task memory, assert). An application replaces any of them by defining its own version.

Typical main():

int main(void)
{
    ipro_platform_init();
    xTaskCreate(app_task, "app", 1024, NULL, 5, NULL);
    vTaskStartScheduler();
    return 0;
}

ipro_setup_heap¶

void ipro_setup_heap(void);

Hand the linker-defined heap regions to the FreeRTOS heap.

Builds the region list for vPortDefineHeapRegions() from linker symbols: the main heap (in PSRAM for flash builds with PSRAM enabled, otherwise in on-chip RAM) and, when the memory layout provides one, the non-retention on-chip RAM heap. Empty regions are skipped, the regions are sorted by address and the size of each is printed.

ipro_platform_init¶

void ipro_platform_init(void);

Run the standard platform start-up sequence before the scheduler starts.

In order: system and debug-UART initialization (platform_init()), ipro_setup_heap(), hal_boot2_init(), a PSRAM check (flash builds with PSRAM print a warning if PSRAM failed to initialize), ipro_log_init() when CONFIG_IPRO_LOG_ENABLE is set, the shell on UART0 with its own task when CONFIG_SHELL is set, and ipro_pm_init() when CONFIG_IPRO_PM is set.

After it returns, create the application tasks and call vTaskStartScheduler().

ipro_dump_task_stacks¶

void ipro_dump_task_stacks(const char *where);

Print the free heap size and every task's stack high-water mark.

For each task (up to 20) it prints the smallest free stack space ever seen, in bytes. A small value means the task came close to overflowing and its stack must not shrink; a large value means the stack is over-provisioned and can be reduced. It uses a static buffer and uxTaskGetSystemState() rather than the heap, so the default malloc-failed and stack-overflow hooks can call it.

hal_common.h¶

#include "hal_common.h"（源代码）

Definitions shared by the HAL drivers, global interrupt control, chip resets and memory-address helpers.

cpu_global_irq_enable¶

void cpu_global_irq_enable(void);

Enable interrupts globally on the CPU.

Not nestable: interrupts are enabled even if they were disabled by an outer section. Use __irq_save() / __irq_restore() for nested critical sections.

cpu_global_irq_disable¶

void cpu_global_irq_disable(void);

Disable interrupts globally on the CPU (see cpu_global_irq_enable()).

hal_por_reset¶

void hal_por_reset(void);

Trigger a software power-on reset of the whole chip.

hal_system_reset¶

void hal_system_reset(void);

Trigger a software system reset.

hal_cpu_reset¶

void hal_cpu_reset(void);

Trigger a software reset of the CPU only.

hal_reboot_config¶

void hal_reboot_config(hal_reboot_cfg_t rbot);

Select the boot mode for the next reboot.

hal_get_chip_id¶

void hal_get_chip_id(uint8_t chip_id[8]);

Read the 8-byte chip ID (factory MAC address field) from efuse.

hal_enter_usb_iap¶

void hal_enter_usb_iap(void);

Reboot into the boot loader's USB download (IAP) mode.

Does not return.

Sets a request flag in the always-on domain, waits 1 s and performs a power-on reset.

hal_jump2app¶

void hal_jump2app(uint32_t flash_offset);

Start a firmware image at another flash offset.

Does not return.

Maps the XIP window to flash_offset and jumps to its start.

hal_get_trng_seed¶

int hal_get_trng_seed(void);

Get a 32-bit random seed from the hardware random number generator.

返回值：Random value.

hal_system_init¶

void hal_system_init(void);

Run the board initialization (board_init()).

Called by the platform start-up code.

hal_is_cacheable_addr¶

int hal_is_cacheable_addr(const void *addr);

Check whether an address is in the cacheable memory view.

返回值：1 for addresses in the 0x1xxxxxxx cacheable view, 0 otherwise.

hal_get_noncacheable_addr¶

void * hal_get_noncacheable_addr(const void *addr);

Get the non-cacheable alias of an address.

Memory in the cacheable 0x1xxxxxxx view is also visible, without the data cache, at the same offset in the 0x2xxxxxxx view.

返回值：The 0x2xxxxxxx alias of a cacheable address, or addr unchanged if it is not cacheable.

hal_reboot_cfg_t¶

Boot mode after a reboot.

宏¶

hal_sys.h¶

#include "hal_sys.h"（源代码）

System control: reset reason, reboot and reset, oscillator calibration, peripheral clock gating.

The reset reason is determined once during start-up (hal_rst_reason_detect()) and can then be read with hal_rst_reason_get(). It is kept in HBN RAM (see hal_hbnram_mgnt.h).

hal_rst_reason_str¶

const char * hal_rst_reason_str(hal_rst_reason_t reason);

Get a printable name of a reset reason.

返回值：Constant string such as "Power-On", or "Invalid" for a value outside hal_rst_reason_t.

hal_rst_reason_get¶

hal_rst_reason_t hal_rst_reason_get(void);

Get the reset reason detected during start-up.

返回值：The value determined by hal_rst_reason_detect(), or HAL_RST_REASON_UNKNOWN if detection has not run.

hal_rst_reason_set¶

void hal_rst_reason_set(hal_rst_reason_t reason);

Store the reason for an upcoming reset.

The value is kept in HBN RAM and reported by hal_rst_reason_detect() at the next boot (unless a hardware reason such as a watchdog reset takes precedence). hal_reboot() and the exception handler call it themselves.

hal_rst_reason_detect¶

hal_rst_reason_t hal_rst_reason_detect(void);

Determine the reset reason (start-up code only).

Evaluates the sources listed at hal_rst_reason_t, initializes the HBN RAM system information after a power-on reset, clears the hardware status it used and the stored reason, and caches the result for hal_rst_reason_get().

返回值：Detected reset reason.

hal_reboot¶

void hal_reboot(void);

Reboot the chip with a power-on reset.

Does not return.

Records HAL_RST_REASON_SOFTWARE as reset reason and boots as selected by the boot pins.

hal_reboot_download¶

void hal_reboot_download(void);

Reboot into download (firmware update over interface) mode, regardless of the boot pins.

Does not return.

hal_reboot_media¶

void hal_reboot_media(void);

Reboot and boot the firmware from flash (media boot), regardless of the boot pins.

Does not return.

hal_sys_reset¶

void hal_sys_reset(void);

Reset the system (without a power-on reset).

Does not return.

No reset reason is recorded; the next boot reports HAL_RST_REASON_SOFTWARE unless one was set with hal_rst_reason_set().

hal_poweroff¶

void hal_poweroff(void);

Power off the chip.

hal_rc32k_cal¶

int hal_rc32k_cal(void);

Apply the factory RC32K oscillator trim from efuse.

Called during start-up by hal_boot2_init(). Does not measure the oscillator; use hal_rc32k_force_cal() for a run-time calibration.

返回值：The applied capacitor trim value (0 or greater), or -1 if no valid trim is burned in efuse (the oscillator keeps its reset settings). Always -1 on IPRO6.

hal_rc32k_force_cal¶

int hal_rc32k_force_cal(void);

Calibrate the RC32K oscillator at run time (IPRO7).

Measures the oscillator against the high-frequency crystal (through the machine timer) and searches the capacitor and frequency trim for the smallest error, regardless of the efuse trim. The 32 kHz source selected on entry is restored. The result is logged.

返回值：The selected capacitor trim value. Always -1 on IPRO6.

hal_rc32k_sw_cal¶

int hal_rc32k_sw_cal(void);

Calibrate the RC32K capacitor trim without a 32.768 kHz crystal (IPRO7).

Tries all 16 capacitor trim values, measures each against the machine timer for 150 ms and keeps the value with the smallest error. The 32 kHz source selected on entry is restored.

返回值：The selected capacitor trim value (0 to 15). Always -1 on IPRO6.

hal_rc32k_measure_error_ppm¶

int hal_rc32k_measure_error_ppm(uint32_t window_us);

Measure the frequency error of the current 32 kHz clock (IPRO7).

Compares the RTC counter with the machine timer (derived from the high-frequency crystal) over window_us. The 32 kHz source is not changed, so select the RC32K oscillator first to measure it.

返回值：Signed error in ppm relative to 32768 Hz (positive = fast), or INT32_MAX if the measurement failed. Always INT32_MAX on IPRO6.

hal_rc32k_measure_cdet_ppm¶

int hal_rc32k_measure_cdet_ppm(uint32_t *out_t_count, uint32_t *out_g_count);

Measure the RC32K frequency error with the clock-detection counter (IPRO7).

Counts high-frequency crystal cycles over 32 RC32K cycles in hardware.

返回值：Signed error in ppm relative to 32768 Hz, or INT32_MAX if the counter did not complete or returned no reference count.

hal_rc32m_cal¶

int hal_rc32m_cal(void);

Trim the RC32M oscillator (IPRO7).

Applies the efuse trim if a valid one is burned, otherwise runs the hardware calibration. Called during start-up by hal_boot2_init().

返回值：The applied trim code. Always -1 on IPRO6.

hal_clock_enable¶

int hal_clock_enable(hal_module_t module);

Enable (ungate) the bus clock of a peripheral module.

返回值：0 on success, -1 if the module is not available on this chip.

hal_clock_disable¶

int hal_clock_disable(hal_module_t module);

Disable (gate) the bus clock of a peripheral module.

返回值：0 on success, -1 if the module is not available on this chip.

hal_module_reset¶

int hal_module_reset(hal_module_t module);

Reset a peripheral module by software.

返回值：0 on success, -1 if the module is not available on this chip.

hal_rst_reason_t¶

System reset reason.

hal_rst_reason_detect() checks the sources in this order:

1. AON watchdog reset status (chips with the AON watchdog);
2. HBN RAM magic missing: power-on reset;
3. watchdog reset status;
4. PDS wake-up status;
5. otherwise the reason stored with hal_rst_reason_set() before the reset, or HAL_RST_REASON_SOFTWARE if none was stored.

匿名枚举¶

Legacy reset reason codes; use hal_rst_reason_t instead.

hal_module_t¶

Peripheral modules for hal_clock_enable(), hal_clock_disable() and hal_module_reset().

hal_clock.h¶

#include "hal_clock.h"（源代码）

Clock-source identifiers for board configuration, board clock initialization and (IPRO6) 32 kHz clock selection.

The identifiers are the values that the board configuration header (board_config.h) assigns to its clock-source settings, for example XTAL_TYPE and the BSP_*_CLOCK_SOURCE macros. The initialization functions are implemented by the board support package and are called during start-up (board_init()).

system_clock_init¶

void system_clock_init(void);

Set up the system clocks from the board configuration.

Configures the system (CPU and bus) clock, the machine-timer clock, the 32 kHz clock and the XCLK source as defined by the board configuration. Called by board_init() during start-up.

peripheral_clock_init¶

void peripheral_clock_init(void);

Set up peripheral clock gating and peripheral clock sources from the board configuration.

Called by board_init() during start-up.

system_mtimer_clock_init¶

void system_mtimer_clock_init(void);

Reset the machine timer and clock it from XCLK.

宏¶

hal_mtimer.h¶

#include "hal_mtimer.h"（源代码）

Machine-timer time stamps and busy-wait delays.

The RISC-V machine timer is a free-running 64-bit counter that also drives the RTOS tick. The functions run from TCM, so they can be used in low-power wake-up code before XIP flash is restored.

mtimer_get_time_ms¶

uint64_t mtimer_get_time_ms();

Get the machine-timer time in units of about 1 ms.

返回值：Time stamp in units of 1.024 ms (microseconds divided by 1024, to avoid a 64-bit division), so the value runs about 2.3 % slower than real milliseconds. Use mtimer_get_time_us() / 1000 when exact milliseconds are needed.

mtimer_get_time_us¶

uint64_t mtimer_get_time_us();

Get the machine-timer time in microseconds.

返回值：Microseconds counted by the machine timer since reset or the last mtimer_clear_time().

mtimer_delay_ms¶

void mtimer_delay_ms(uint32_t time);

Busy-wait for a number of milliseconds.

Does not yield to the scheduler; use the RTOS delay functions in tasks.

mtimer_delay_us¶

void mtimer_delay_us(uint32_t time);

Busy-wait for a number of microseconds.

mtimer_clear_time¶

void mtimer_clear_time();

Reset the machine-timer counter to 0.

hal_timer.h¶

#include "hal_timer.h"（源代码）

General-purpose timer driver: counter channels with three compare match interrupts each.

The timer block has two channels. Each channel counts at its channel clock and has three comparators that can raise interrupts and, in preload mode, reload the counter. Typical sequence:

1. Optionally set the clock divider with timer_set_div().
2. Configure the channel with timer_init(); match times are given in microseconds.
3. Register a callback with timer_setCallback().
4. Start counting with timer_start().

timer_init¶

int timer_init(int timer_id, int timer_ch, hal_timer_config_t *timerCfg);

Configure a timer channel without starting it.

Masks the channel interrupts, stops the channel, sets counting mode, reload comparator and reload value, converts the three match times to counter ticks with the channel clock rate at the time of the call, and programs the comparators selected by hal_timer_config_t::trigger (comparator value = ticks + reload - 2, where reload counts only in preload mode). The other comparators are set to 0xFFFFFFFF. The match interrupts of the selected comparators are unmasked and, for TIMER0_INDEX, the channel interrupt is enabled in the CPU and its handler installed.

timer_set_div¶

void timer_set_div(int timer_id, int timer_ch, uint8_t div);

Set the clock divider of a channel.

The counter clock becomes the channel source clock divided by (div + 1). Call it before timer_init(), which converts the match times with the clock rate in effect at that moment.

timer_setCallback¶

void timer_setCallback(int timer_id, int timer_ch, void *fn);

Register the match callback of a channel.

timer_get_counter¶

uint32_t timer_get_counter(int timer_id, int timer_ch);

Read the current counter value of a channel.

返回值：Counter value in counter clock ticks.

timer_start¶

void timer_start(int timer_id, int timer_ch);

Start counting on a channel.

timer_stop¶

void timer_stop(int timer_id, int timer_ch);

Stop counting on a channel.

timer_ch_index_type¶

Timer channel (the timer_ch argument of the timer functions).

timer_index_type¶

Timer block (the timer_id argument of the timer functions).

Use TIMER0_INDEX: the SoC has a single timer block, and timer_init() installs interrupt handlers only for TIMER0_INDEX.

timer_preload_trigger_type¶

Comparator that reloads the counter (hal_timer_config_t::trigger).

timer_init() also enables the match interrupts of this comparator and of all lower-numbered comparators.

timer_cnt_mode_type¶

Counting mode (hal_timer_config_t::cnt_mode).

timer_compare_id_type¶

Comparator number.

timer_it_type¶

Comparator interrupt bit masks (bit n = comparator n).

timer_event_type¶

Events passed to the timer callback.

timer_device_t¶

State of one timer channel kept by the driver.

Applications do not access it directly; the callback member shows the signature expected by timer_setCallback().

hal_timer_config_t¶

Channel configuration for timer_init().

Match times are converted to counter ticks with the channel clock: the resolution is 1 us when the clock is a multiple of 1 MHz, and coarser otherwise (the time is truncated to the resolution).

hal_rtc.h¶

#include "hal_rtc.h"（源代码）

Always-on RTC: counter reset with compare alarm, and a simple time stamp in seconds.

The RTC counter runs from the 32 kHz clock (32768 ticks per second) in the always-on domain and keeps counting during PDS and HBN sleep. The low-power functions (hal_lp.h, hal_pm.h) use the same counter.

rtc_init¶

void rtc_init(uint64_t sleep_time);

Restart the RTC counter and arm its compare alarm.

Clears the RTC counter, sets the compare value to sleep_time seconds later and enables the counter.

rtc_set_timestamp¶

void rtc_set_timestamp(uint64_t time_stamp);

Set the offset that rtc_get_timestamp() adds to the RTC time.

rtc_get_timestamp¶

uint64_t rtc_get_timestamp(void);

Get the RTC time stamp in seconds.

返回值：The RTC counter in whole seconds plus the offset set with rtc_set_timestamp(). The offset is added as is; it is not adjusted for the counter value at the time it was set.

hal_wdt.h¶

#include "hal_wdt.h"（源代码）

Watchdog timer (WDT) of the timer block: chip reset or interrupt on timeout.

Start the watchdog with wdt_init() and call wdt_feed() more often than the timeout. The timeout is counted in watchdog clock ticks; this driver does not set the watchdog clock source or divider. For a watchdog that keeps running in the low-power modes see hal_aon_wdt.h.

wdt_init¶

void wdt_init(int int_mode, uint32_t wdt_timeout);

Configure and start the watchdog.

Stops the watchdog; if wdt_timeout is non-zero, sets the timeout, selects the timeout action and starts it again.

wdt_disable¶

void wdt_disable(void);

Stop the watchdog.

wdt_get_counter¶

uint32_t wdt_get_counter(void);

Read the watchdog counter.

返回值：Current counter value in watchdog clock ticks (16 bits).

wdt_feed¶

void wdt_feed(void);

Reset the watchdog counter (feed the watchdog).

wdt_isWDTReset¶

void wdt_isWDTReset(void);

Read the watchdog reset flag.

wdt_clearWDTReset¶

void wdt_clearWDTReset(void);

Clear the flag that records a reset caused by the watchdog.

wdt_setTimeout¶

void wdt_setTimeout(uint32_t wdt_timeout);

Change the watchdog timeout.

Stops the watchdog, writes the new timeout and starts it again, even if it was stopped before.

hal_aon_wdt.h¶

#include "hal_aon_wdt.h"（源代码）

Always-on (AON) watchdog timer: chip reset on timeout, also in the PDS and HBN sleep modes.

The AON watchdog is clocked by the 32 kHz clock (RC32K or XTAL32K) and keeps running in the PDS and HBN sleep modes. The timeout is selected with a mask bit:

timeout = 2^(mask_bit + 1) / 32768 seconds

mask_bit timeout mask_bit timeout mask_bit timeout

15 2 s 18 16 s 21 128 s

16 4 s 19 32 s 22 256 s

17 8 s 20 64 s

Every step doubles the timeout, so there are no intermediate values: a 30 s budget means choosing 32 s (mask 19).

aon_wdt_init() clears the AON watchdog reset flag, so read aon_wdt_get_reset_status() before calling it. On chips without AON watchdog support (CONFIG_AON_WDT_SUPPORT not set, for example IPRO6) all functions do nothing and aon_wdt_get_reset_status() returns 0.

aon_wdt_init¶

void aon_wdt_init(uint8_t mask_bit);

Initialize and start the AON watchdog timer.

Stops the watchdog, clears its reset flag, sets the timeout, enables it and feeds it once.

aon_wdt_feed¶

void aon_wdt_feed(void);

Feed (kick) the AON watchdog timer, resetting its counter.

aon_wdt_disable¶

void aon_wdt_disable(void);

Disable the AON watchdog timer.

aon_wdt_get_reset_status¶

int aon_wdt_get_reset_status(void);

Check if the last reset was caused by the AON watchdog.

aon_wdt_clear_reset_status¶

void aon_wdt_clear_reset_status(void);

Clear the AON watchdog reset status flag.

宏¶

hal_cache_alloc.h¶

#include "hal_cache_alloc.h"（源代码）

Cache-line aligned heap allocation for DMA and hardware-accelerator buffers (FreeRTOS builds).

pvPortMalloc() only guarantees portBYTE_ALIGNMENT (8 bytes on IPRO7). Buffers shared with DMA or hardware accelerators need cache-line alignment so that cleaning or invalidating the data cache for the buffer does not affect other heap objects in the same cache line. Allocate such buffers with pvPortMallocCacheAligned() and round their size up to a multiple of HAL_CACHE_LINE_SIZE as well.

pvPortMallocCacheAligned¶

void * pvPortMallocCacheAligned(size_t size);

Allocate a heap block whose start is aligned to a cache line.

Allocates size + HAL_CACHE_LINE_SIZE + sizeof(void *) bytes with pvPortMalloc() and returns the first cache-line aligned address inside it.

返回值：Cache-line aligned pointer, or NULL if the allocation failed.

vPortFreeCacheAligned¶

void vPortFreeCacheAligned(void *ptr);

Free a block allocated with pvPortMallocCacheAligned().

宏¶

hal_hbnram_mgnt.h¶

#include "hal_hbnram_mgnt.h"（源代码）

HBN RAM layout: the 4 KB always-on RAM shared by boot, firmware and the low-power framework.

HBN RAM keeps its contents in PDS sleep, in HBN level 0 and across warm resets; it is undefined after a power-on reset. This header is the single definition of how the 4 KB are divided. Use the HAL_HBNRAM_*_ADDR and *_SIZE macros instead of hard-coded addresses.

Layout (offsets from HBN_RAM_BASE, 0x20090000 on IPRO7 and IPRO6):

0x000  LP_FW       1024 B  low-power wake-up code
0x400  LP_PARAM     512 B  low-power framework state
0x600  RSTINFO       32 B  hal_hbnram_sysinfo_t (reset reason, boot status)
0x620  LP_WAKE_CTX   64 B  hal_hbnram_lp_wake_ctx_t (HBN fast-boot wake)
0x660  BOOT2        644 B  boot-parameter snapshot for HBN fast-boot wake
0x8E4  RESERVED    1564 B  free (IPRO6: 540 B, followed by WLCAL)
0xB00  WLCAL       1024 B  IPRO6 only: Wi-Fi/RF calibration data
0xF00  IOT2LP       256 B  parameters of the stand-alone low-power image
0x1000 end

The LP_FW, LP_PARAM, BOOT2 and IOT2LP regions belong to the HAL and the low-power framework; applications must not write them. Applications may use the documented fields of hal_hbnram_sysinfo_t and the scratch words of hal_hbnram_lp_wake_ctx_t.

hal_hbnram_sysinfo_t¶

System information kept in HBN RAM, shared by boot loader and firmware.

Survives PDS/HBN sleep and warm resets. After a power-on reset the content is undefined; hal_rst_reason_detect() recognizes this through magic, then sets magic and clears reset_reason. Access the structure through hal_hbnram_sysinfo. Size: 32 bytes.

hal_hbnram_lp_wake_ctx_t¶

Wake context of the HBN fast-boot path.

hal_lp_enter_fastboot() fills this structure just before the chip enters HBN. A wake-up from HBN is a full boot, so the firmware reads it after start-up with hal_lp_get_wake_context(), after hal_lp_is_fastboot_wakeup() has returned true. Size: 64 bytes, all fields 32-bit.

类型定义¶

宏¶