Implement memory regions iterators (#104)

Author: moojek

CMake/TestsConfig.cmake

@@ -2,20 +2,26 @@ function(SETUP_UNIT_TEST name)
     add_executable(${name})
     SETUP_COMMON(${name})
 
-	file(GLOB_RECURSE SOURCES CONFIGURE_DEPENDS *.c)
-    file(GLOB_RECURSE HEADERS CONFIGURE_DEPENDS *.h)
+      file(GLOB_RECURSE HEADERS CONFIGURE_DEPENDS *.h)
 
-    target_sources(${name}
-      PRIVATE
-        ${SOURCES}
-		${ARGN}
-      PRIVATE
-        FILE_SET HEADERS
-        BASE_DIRS .
-        FILES ${HEADERS}
-      )
+      # If explicit sources were passed to the macro, use them only.
+      if (ARGN)
+          set(EXPLICIT_SOURCES ${ARGN})
+      else()
+          file(GLOB_RECURSE EXPLICIT_SOURCES CONFIGURE_DEPENDS *.c)
+      endif()
 
-	target_link_libraries(${name} PRIVATE unity)
+      target_sources(${name}
+        PRIVATE
+          ${EXPLICIT_SOURCES}
+        PRIVATE
+          FILE_SET HEADERS
+          BASE_DIRS .
+          FILES ${HEADERS}
+        )
+
+      # Link common libraries required by tests that reference core helpers and DT parsing.
+      target_link_libraries(${name} PRIVATE unity libcore libboot_dt)
 
 	add_test(NAME ${name} COMMAND ${name})
 

docs/doxygen/groups.dox

@@ -5,6 +5,7 @@
 		@defgroup palloc Physical memory allocator
 	@defgroup kinit Kernel initialization
 	@defgroup hal Hardware abstraction layer
+		@defgroup hal_riscv_mem RISC-V memory regions
 @defgroup libboot_dt
 @defgroup libcore
 	@defgroup sbi

docs/source/pages/api/kernel/index.rst

@@ -6,4 +6,5 @@ Internal kernel APIs
    :maxdepth: 1
 
    mm/index
+   memory_regions
 

docs/source/pages/api/kernel/memory_regions.rst

@@ -0,0 +1,40 @@
+=======================
+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:
+
+.. code-block:: c
+
+    // 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
+=============
+
+.. doxygengroup:: hal_riscv_mem

include/libboot/dt/dt.h

@@ -236,6 +236,19 @@ error_t dt_get_prop_buffer(const fdt_t* fdt, dt_prop_t prop, buffer_t* bufOUT);
 [[gnu::nonnull(3)]]
 error_t dt_get_rsv_mem_entry(const fdt_t* fdt, u32 index, fdt_rsv_entry* entryOUT);
 
+/**
+ * @brief Get #address-cells and #size-cells properties from a node.
+ * @param fdt Pointer to the fdt object.
+ * @param node The node to read cell counts from.
+ * @param[out] address_cellsOUT Number of address cells (default 2).
+ * @param[out] size_cellsOUT Number of size cells (default 1).
+ * @retval ERR_NONE on success
+ * @retval ERR_BAD_ARG on nullptr args
+ * @retval ERR_NOT_VALID if the FDT is invalid or cell counts exceed 2
+ */
+[[gnu::nonnull(3, 4)]]
+error_t dt_get_reg_cell_counts(const fdt_t* fdt, dt_node_t node, u32* address_cellsOUT, u32* size_cellsOUT);
+
 /// @}
 
 #endif // !DT_DT