内存、Flash 与启动¶

Flash 读写、PSRAM、boot2 与分区表管理。说明取自头文件注释（英文）。

hal_flash.h¶

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

Serial NOR flash access: identification, read, program, erase.

All addresses taken by these functions are flash offsets (0 = first byte of the flash device), not CPU bus addresses; the flash is also visible read-only through the XIP window at FLASH_XIP_BASE. Program and erase follow NOR rules: a range must be erased (all bytes 0xFF) before it is programmed, and erase works on whole sectors.

The read, program and erase functions disable interrupts while they talk to the flash, because code and data in XIP flash are not reachable during the operation. flash_write() does this per 256-byte chunk; flash_erase() keeps interrupts disabled for the whole erase, so split large erases if interrupt latency matters.

The flash driver is initialized during start-up (hal_boot2_init() calls flash_init()).

flash_get_jedecid¶

uint32_t flash_get_jedecid(void);

Get the JEDEC ID of the flash detected by flash_init().

返回值：The 24-bit JEDEC ID as 0xMMTTCC: manufacturer ID in bits 23:16, memory type in bits 15:8, capacity code in bits 7:0. 0 before flash_init() has run.

flash_get_size¶

uint32_t flash_get_size(void);

Get the flash size derived from the JEDEC capacity code.

返回值：Flash size in bytes, or 0 when the JEDEC ID is not known yet.

flash_init¶

int flash_init(void);

Initialize the flash driver configuration.

Takes over the configuration set up by the boot ROM (or detects the flash when no configuration is available) so that the other functions in this header can be used.

返回值：0 (SUCCESS) on success, non-zero if the flash could not be configured.

flash_read_jedec_id¶

int flash_read_jedec_id(uint8_t *data);

Read the JEDEC ID directly from the flash device.

返回值：Always 0 (SUCCESS).

flash_read_via_xip¶

int flash_read_via_xip(uint32_t addr, uint8_t *data, uint32_t len);

Read flash through the memory-mapped XIP window and the cache.

返回值：Always 0 (SUCCESS).

flash_read¶

int flash_read(uint32_t addr, uint8_t *data, uint32_t len);

Read data from flash with flash commands.

返回值：0 (SUCCESS) on success, non-zero on failure.

flash_write¶

int flash_write(uint32_t addr, uint8_t *data, uint32_t len);

Program data into flash.

The data is copied through a 256-byte internal buffer, so data may be located in any memory, including PSRAM. Interrupts are disabled for each 256-byte chunk and restored to their previous state afterwards.

返回值：0 (SUCCESS) on success, non-zero if data is NULL, the range wraps past the end of the 32-bit address space, or programming fails.

flash_erase¶

int flash_erase(uint32_t startaddr, uint32_t len);

Erase a flash range.

Every sector that overlaps [startaddr, startaddr + len - 1] is erased; aligned 32 KB and 64 KB blocks are erased with block commands. The sector size is normally 4 KB.

返回值：0 (SUCCESS) on success, non-zero on failure.

flash_get_cfg¶

int flash_get_cfg(uint8_t **cfg_addr, uint32_t *len);

Get the flash configuration used by the driver.

返回值：Always 0 (SUCCESS).

flash_readReg¶

uint32_t flash_readReg(uint8_t readRegCmd, uint8_t len);

Read a flash register with a custom read-register command.

返回值：The register bytes in little-endian order; only the low len bytes are meaningful.

flash_writeReg¶

void flash_writeReg(uint8_t writeRegCmd, uint32_t writeVal, uint8_t len);

Write a flash register with a custom write-register command.

hal_flash_config_update¶

int hal_flash_config_update(uint32_t flashCfgAddr);

Print the active flash configuration if a configuration block is present.

Checks for FLASH_MAGIC_CODE at flashCfgAddr + 4 and, if found, prints the main fields of the configuration the driver is using. The driver configuration itself is not changed.

返回值：Always 0.

宏¶

hal_psram.h¶

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

On-chip PSRAM: initialization, DQS calibration and sleep modes.

The functions are available in builds with CONFIG_USE_PSRAM. The system start-up code initializes and calibrates the PSRAM before the PSRAM data sections are loaded, so applications normally only use the sleep-mode functions, if any.

The DQS (read strobe) delay is chosen from a table of HAL_PSRAM_DQS_TABLE_SIZE steps. A calibration result ("DQS configuration") is encoded as (left << 4) | right, the first and last table index at which the PSRAM passed the read/write test; the centre of that window is used.

hal_psram_gpio_init¶

void hal_psram_gpio_init(void);

Prepare the PSRAM pads for the PSRAM controller.

Releases the sleep-mode pad configuration of the PSRAM pins and resets them to plain inputs without pull resistors.

hal_psram_get_dqs_value¶

uint16_t hal_psram_get_dqs_value(uint8_t index);

Get an entry of the DQS delay table.

返回值：The DQS delay setting; 0xFFC0 (the default delay) for an index outside the table.

hal_psram_get_dqs_cfg¶

uint16_t hal_psram_get_dqs_cfg(void);

Get the DQS configuration in use.

返回值：DQS configuration (left << 4) | right, as set by calibration or hal_psram_set_dqs_cfg(); 0 before either.

hal_psram_set_dqs_cfg¶

void hal_psram_set_dqs_cfg(uint16_t cfg);

Record the DQS configuration of a PSRAM initialized elsewhere.

Used by the start-up code when the PSRAM was set up before the HAL (by the early start-up code or the boot loader), so that the low-power framework can restore it after PDS.

hal_psram_winbond_init_dqs¶

uint16_t hal_psram_winbond_init_dqs(int8_t burst_len, uint8_t is_fixLatency, uint8_t latency, uint16_t dqs_delay);

Initialize the PSRAM controller and device with a given DQS delay.

返回值：The PSRAM ID register read back; HAL_PSRAM_ID_WINBOND_8MB when the device responds correctly.

hal_psram_enter_hybridsleep¶

void hal_psram_enter_hybridsleep(void);

Put the PSRAM into hybrid sleep; its contents are retained.

The PSRAM cannot be accessed until hal_psram_exit_hybridsleep() (or the low-power framework's restore) has run. Used by the PDS entry path.

hal_psram_enter_deepsleep¶

void hal_psram_enter_deepsleep(void);

Put the PSRAM into deep power-down; its contents are lost.

The PSRAM must be initialized again before it is used.

hal_psram_exit_hybridsleep¶

void hal_psram_exit_hybridsleep(void);

Leave hybrid sleep; blocks for about 120 us.

hal_psram_rw_check¶

uint8_t hal_psram_rw_check(void);

Test the PSRAM with a write/read pattern.

返回值：SUCCESS (0) if the test passed, ERROR (1) otherwise.

hal_psram_x8_calibration¶

uint16_t hal_psram_x8_calibration(uint16_t psram_dqs_cfg, int32_t *psram_dqs_win_num, uint16_t *new_dqs_cfg);

Select the DQS delay of the PSRAM.

With a valid efuse value the PSRAM is initialized at the centre of the stored window. With psram_dqs_cfg = 0xFFFF (no efuse trim) all HAL_PSRAM_DQS_TABLE_SIZE delays are tried with hal_psram_rw_check() and the centre of the passing window is used; the window must be wider than 4 steps.

返回值：HAL_PSRAM_ID_WINBOND_8MB on success, ERROR (1) on failure.

hal_psram_init¶

uint32_t hal_psram_init(uint16_t psram_dqs_cfg);

Initialize and calibrate the PSRAM.

Sets up the pads and the PSRAM clock, then runs hal_psram_x8_calibration() and keeps the result for the low-power framework. Runs from TCM.

返回值：HAL_PSRAM_ID_WINBOND_8MB on success.

hal_psram_print_calibration_log¶

void hal_psram_print_calibration_log(void);

Print the PSRAM calibration log recorded during early boot.

Calibration runs before the console is available, so its messages are kept in a small buffer at the start of the heap. Call this after the console UART is initialized and before the heap is used; the buffer is printed once.

宏¶

hal_sf_psram.h¶

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

External quad-SPI PSRAM on the second serial-flash interface.

hal_sf_psram_init¶

void hal_sf_psram_init(uint8_t sw_reset);

Initialize an external quad-SPI PSRAM and enable cached access.

Configures the pins (CLK GPIO27, CS GPIO17, DATA0 to DATA3 on GPIO28, GPIO24, GPIO23 and GPIO26, flash CS GPIO25), initializes the controller and the device, resets the device, reads and prints its ID, and enables cached quad-mode access.

hal_boot2.h¶

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

Boot information: partition table lookup and update, efuse boot configuration, PSRAM bring-up from the boot path.

At start-up the boot loader (boot2) hands the active partition table to the firmware. hal_boot2_init() copies it into RAM (reading it from flash if the hand-over copy is not valid) and initializes the flash driver. Afterwards the partition helpers in this header resolve a partition by name to its flash offset or to its XIP bus address, and hal_boot2_update_ptable() switches the active image slot of an entry for a firmware update (see hal_ptmgr.h for the table format).

Typical firmware-update flow:

PtTable_Entry_Config e;
if (hal_boot2_get_active_entries(PT_ENTRY_FW_CPU0, &e) == 0) {
    uint32_t slot = e.Address[!e.activeIndex];   // inactive slot
    // erase and write the new image at 'slot' with flash_erase()/flash_write()
    e.len = image_len;                           // size of the new image
    hal_boot2_update_ptable(&e);                 // boot the new slot next time
    hal_reboot();
}

hal_boot2_partition_bus_addr_active¶

int hal_boot2_partition_bus_addr_active(const char *name, uint32_t *addr, uint32_t *size);

Get the XIP bus address and size of the active copy of a partition.

Same as hal_boot2_partition_bus_addr(), returning only the copy selected by the entry's active index.

返回值：0 on success, or a negative errno value as listed for hal_boot2_partition_bus_addr().

hal_boot2_partition_bus_addr_inactive¶

int hal_boot2_partition_bus_addr_inactive(const char *name, uint32_t *addr, uint32_t *size);

Get the XIP bus address and size of the inactive copy of a partition.

返回值：0 on success, or a negative errno value as listed for hal_boot2_partition_bus_addr().

hal_boot2_partition_bus_addr¶

int hal_boot2_partition_bus_addr(const char *name, uint32_t *addr0, uint32_t *addr1, uint32_t *size0, uint32_t *size1, int *active);

Look up a partition and return both copies as XIP bus addresses.

The flash offsets stored in the partition table are converted to addresses in the memory-mapped flash window, relative to the flash offset of the running image, so the partition can be read directly through a pointer. This only works for partitions placed after the "FW" partition.

hal_boot2_partition_addr_active¶

int hal_boot2_partition_addr_active(const char *name, uint32_t *addr, uint32_t *size);

Get the flash offset and size of the active copy of a partition.

hal_boot2_partition_addr_inactive¶

int hal_boot2_partition_addr_inactive(const char *name, uint32_t *addr, uint32_t *size);

Get the flash offset and size of the inactive copy of a partition.

Firmware updates write the new image to this copy.

hal_boot2_partition_addr¶

int hal_boot2_partition_addr(const char *name, uint32_t *addr0, uint32_t *addr1, uint32_t *size0, uint32_t *size1, int *active);

Look up a partition and return the flash offsets of both copies.

hal_boot2_get_active_partition¶

uint8_t hal_boot2_get_active_partition(void);

Get which of the two partition-table copies is in use.

返回值：The active table, a PtTable_ID_Type value (PT_TABLE_ID_0 or PT_TABLE_ID_1).

hal_boot2_get_active_entries_byname¶

int hal_boot2_get_active_entries_byname(uint8_t *name, PtTable_Entry_Config *ptEntry_hal);

Copy the partition entry with the given name.

hal_boot2_get_active_entries¶

int hal_boot2_get_active_entries(int type, PtTable_Entry_Config *ptEntry);

Copy the first partition entry of the given type.

hal_boot2_update_ptable¶

int hal_boot2_update_ptable(PtTable_Entry_Config *ptEntry);

Switch the active copy of a partition entry and store the table.

Toggles ptEntry->activeIndex, increments ptEntry->age, replaces the entry of the same type in the RAM copy of the table (or appends it) and writes the table, with its age incremented, to the partition-table copy that is not currently active. The boot loader picks the table with the higher age, so the change takes effect at the next boot.

返回值：A PtTable_Error_Type value: PT_ERROR_SUCCESS (0) on success.

hal_boot2_dump¶

int hal_boot2_dump(void);

Print the loaded partition table to the console.

返回值：Always 0.

hal_boot2_psram¶

uint32_t hal_boot2_psram(void);

Initialize and calibrate the on-chip PSRAM from the boot path.

Calls hal_psram_init() with the DQS value read from efuse. Builds without CONFIG_USE_PSRAM return 0 without touching the hardware.

返回值：The PSRAM device ID on success, 0 when PSRAM support is not built in. See hal_psram_init() for the failure behaviour.

hal_boot2_init¶

int hal_boot2_init(void);

Load the partition table and initialize the flash driver.

Copies the partition table handed over by the boot loader (or reads it from flash when that copy is not valid), initializes the flash driver, prints the partition table and flash information, and applies the RC32K and RC32M oscillator trims (hal_rc32k_cal(), hal_rc32m_cal()).

返回值：Always 0.

hal_boot2_get_psram_dqs_cfg¶

unsigned int hal_boot2_get_psram_dqs_cfg(void);

Get the PSRAM DQS calibration value read from efuse.

返回值：The value encoded as (left << 4) | right, or 0xFFFF when no valid trim is burned. Valid after hal_boot2_init_efuse().

hal_boot2_init_efuse¶

void hal_boot2_init_efuse(void);

Read the boot-relevant efuse settings into the HAL's copy.

Called early by the system start-up code, before PSRAM is initialized. Applications do not need to call it.

HAL_Err_Type¶

Generic success/error code.

boot2_efuse_hw_config¶

Boot-relevant efuse settings, read by hal_boot2_init_efuse().

The HAL keeps one instance, filled during system start-up; the PSRAM calibration value is available through hal_boot2_get_psram_dqs_cfg().

类型定义¶

宏¶

hal_ptmgr.h¶

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

Partition table format and low-level partition-table access.

The flash holds two copies of the partition table (PT0 and PT1). Each copy is a PtTable_Config header followed by entryCnt PtTable_Entry_Config entries and a CRC32 over those entries. The boot loader uses the valid copy with the higher age. Every entry describes one partition with two slots (Address[0]/Address[1]); activeIndex selects the slot that is in use, which is how A/B firmware updates are switched.

Most applications use the higher-level helpers in hal_boot2.h, which work on the table loaded at start-up. The functions here operate on a caller supplied PtTable_Stuff_Config and are meant for code that reads or writes the tables itself.

PtTable_Get_Active_Entries¶

PtTable_Error_Type PtTable_Get_Active_Entries(PtTable_Stuff_Config *ptStuff, PtTable_Entry_Type type, PtTable_Entry_Config *ptEntry);

Copy the first entry of a given type from a partition table.

PtTable_Update_Entry¶

PtTable_Error_Type PtTable_Update_Entry(const SPI_Flash_Cfg_Type *pFlashCfg, PtTable_ID_Type targetTableID, PtTable_Stuff_Config *ptStuff, PtTable_Entry_Config *ptEntry);

Update an entry in a partition table and write the table to flash.

Same as PtTable_Update_Entry_Ops() using the HAL flash functions (flash_read(), flash_erase(), flash_write()).

返回值：See PtTable_Update_Entry_Ops().

PtTable_Get_Active_Entries_By_Name¶

PtTable_Error_Type PtTable_Get_Active_Entries_By_Name(PtTable_Stuff_Config *ptStuff, uint8_t *name, PtTable_Entry_Config *ptEntry);

Copy the entry with a given name from a partition table.

PtTable_Get_Active_Partition_Ops¶

PtTable_ID_Type PtTable_Get_Active_Partition_Ops(const PtTable_Flash_Ops *ops, PtTable_Stuff_Config ptStuff[2]);

Read both partition-table copies and select the active one.

Each copy is checked for PT_MAGIC_CODE, a valid entry count and both CRCs. If both are valid the one with the higher age is selected (PT0 on a tie).

返回值：PT_TABLE_ID_0 or PT_TABLE_ID_1, or PT_TABLE_ID_INVALID when neither copy is valid.

PtTable_Update_Entry_Ops¶

PtTable_Error_Type PtTable_Update_Entry_Ops(const PtTable_Flash_Ops *ops, PtTable_ID_Type targetTableID, PtTable_Stuff_Config *ptStuff, PtTable_Entry_Config *ptEntry);

Update an entry in a partition table and write the table to flash.

The entry with the same type as ptEntry is replaced (or ptEntry is appended if no such entry exists), the table age is incremented, both CRCs are recomputed, and the table is erased and written at the flash offset of targetTableID.

PtTable_Error_Type¶

Result codes of the partition-table functions.

PtTable_ID_Type¶

Identifies one of the two partition-table copies.

PtTable_Entry_Type¶

Well-known partition entry types (PtTable_Entry_Config::type).

PtTable_Config¶

Partition table header.

PtTable_Entry_Config¶

One partition entry.

PtTable_Stuff_Config¶

In-memory image of one partition-table copy.

PtTable_Flash_Ops¶

Flash access functions used by the _Ops variants.

Addresses are flash offsets. Each function returns 0 (SUCCESS) on success and non-zero on failure.

类型定义¶

宏¶