Memory regions#

This module provides iterators to enumerate memory regions from the device tree:

  • Memory regions: Physical memory regions available for use (from /memory nodes)

  • Reserved regions: Memory ranges reserved by the system and must not be allocated (from /reserved-memory node and memory reservations)

Usage Pattern#

Both iterators follow the same init-then-iterate pattern:

// Initialize iterator
hal_memory_iterator_t iter;
if (hal_get_memory_regions_iterator(&iter) != ERR_NONE)
    return; // Handle error

// Iterate through regions
physical_memory_region_t region;
while (hal_get_next_memory_region(&iter, &region) == ERR_NONE) {
    // Process region
}
// Loop exits when hal_get_next_memory_region returns ERR_NOT_FOUND

Return Value Semantics#

  • ERR_NONE: Successfully retrieved next region; output parameter is valid

  • ERR_NOT_FOUND: End of iteration reached (normal termination, not an error)

  • Other error codes: Actual error occurred; output parameters remain unchanged

API Reference#

group RISC-V memory regions

Functions

error_t hal_get_reserved_regions_iterator(hal_reserved_memory_iterator_t *iterOUT)#

Initialize an iterator for enumerating system-reserved memory regions.

Reserved regions come from two sources in the device tree:

  • The /reserved-memory node and its children

  • The memory reservation table (memreserve entries)

Note

Upon error, iterOUT should remain unchanged.

Parameters:

iterOUT – Pointer to uninitialized iterator to fill.

Return values:

  • ERR_NONE – Iterator initialized successfully

  • ERR_BAD_ARG – Invalid argument (null parameter or device tree validation error)

  • ERR_NOT_INITIALIZED – HAL is not initialized

  • Other – error codes Device tree parsing failures

error_t hal_get_next_reserved_region(hal_reserved_memory_iterator_t *iter, memory_area_t *areaOUT)#

Retrieve the next reserved memory region.

Call this repeatedly after hal_get_reserved_regions_iterator() until it returns ERR_NOT_FOUND.

Note

Upon error, areaOUT should remain unchanged.

Parameters:
Return values:

  • ERR_NONE – Region retrieved successfully

  • ERR_BAD_ARG – Invalid argument (null parameter or device tree validation error)

  • ERR_NOT_FOUND – No more regions (end of iteration)

  • Other – error codes Device tree errors

error_t hal_get_memory_regions_iterator(hal_memory_iterator_t *iterOUT)#

Initialize an iterator for enumerating physical memory regions.

Enumerates all /memory nodes from the device tree, including all register entries within each memory node.

Note

Upon error, iterOUT should remain unchanged.

Parameters:

iterOUT – Pointer to uninitialized iterator to fill.

Return values:

  • ERR_NONE – Iterator initialized successfully

  • ERR_BAD_ARG – Invalid argument (null parameter or device tree validation error)

  • ERR_NOT_INITIALIZED – HAL is not initialized

  • Other – error codes Device tree parsing failures

error_t hal_get_next_memory_region(hal_memory_iterator_t *iter, physical_memory_region_t *areaOUT)#

Retrieve the next available memory region.

Call this repeatedly after hal_get_memory_regions_iterator() until it returns ERR_NOT_FOUND. Each call retrieves one register entry from the device tree memory nodes.

Note

Upon error, areaOUT should remain unchanged.

Parameters:

  • iter – Pointer to active iterator (initialized by hal_get_memory_regions_iterator())

  • areaOUT – Pointer to output structure. On success, filled with region details.

Return values:

  • ERR_NONE – Region retrieved successfully

  • ERR_BAD_ARG – Invalid argument (null parameter or device tree validation error)

  • ERR_NOT_FOUND – No more regions (end of iteration)

  • Other – error codes Device tree errors

struct hal_reserved_memory_iterator_t#
#include <memory_regions.h>

This type is opaque to the caller. Fields of this struct should not be modified directly.

struct hal_memory_iterator_t#
#include <memory_regions.h>

This type is opaque to the caller. Fields of this struct should not be modified directly.