feat: support external flash via flash driver instances (STM32H7 SPI FRAM)

.github/workflows/ci.yml

@@ -34,6 +34,7 @@ jobs:
         run: |
           make -s stm32f103
           make -s stm32g0b1
+          make -s stm32h753xx
           make -s ubuntu
 
   test_params_generator:

Makefile

@@ -52,6 +52,11 @@ stm32g0b1: clean
 		-DCMAKE_TOOLCHAIN_FILE=${ROOT_DIR}/tests/platform_specific/cmake/arm-none-eabi-toolchain.cmake
 	cmake --build build/tests/platform_specific/stm32g0b1
 
+stm32h753xx: clean
+	cmake -S tests/platform_specific/stm32h753xx -B build/tests/platform_specific/stm32h753xx \
+		-DCMAKE_TOOLCHAIN_FILE=${ROOT_DIR}/tests/platform_specific/cmake/arm-none-eabi-toolchain.cmake
+	cmake --build build/tests/platform_specific/stm32h753xx
+
 UBUNTU_BUILD_DIR=${ROOT_DIR}/build/tests/platform_specific/ubuntu
 UBUNTU_CMAKE_DIR=${ROOT_DIR}/tests/platform_specific/ubuntu
 ubuntu: clean

README.md

@@ -81,7 +81,7 @@ Look at [libparams/storage.h](libparams/storage.h) to get full API and [src/stor
 
 ROM driver simply allows you to write and read sequence of bytes. Mainly, it consist of 3 operations.
 
-1. Initialization. It is necessary to call `romInit()` to configure the driver. Storage driver do it automatically.
+1. Initialization. It is necessary to call `romInit()` with flash driver ops to configure the driver. Storage driver do it automatically.
 
 2. Read operation. You just need to call `romRead` with corresponded arguments.
 
@@ -174,9 +174,15 @@ The initialization of the application can be as shown below:
 
 ```c++
 #include "params.h"
+#include "flash_driver.h"
+#include "platform_flash_driver.h"
 
 void application_example() {
-    paramsInit(IntParamsIndexes::INTEGER_PARAMS_AMOUNT, StrParamsIndexes::STRING_PARAMS_AMOUNT, -1, 1);
+    paramsInit(stm32h753xxInternalFlashGetOps(),
+               IntParamsIndexes::INTEGER_PARAMS_AMOUNT,
+               StrParamsIndexes::STRING_PARAMS_AMOUNT,
+               -1,
+               1);
     paramsLoad();
 }
 ```

include/libparams/flash_driver.h

@@ -18,40 +18,18 @@
 extern "C" {
 #endif
 
+typedef struct {
+    void (*init)(void);
+    int8_t (*unlock)(void);
+    int8_t (*lock)(void);
+    int8_t (*erase)(uint32_t start_page_idx, uint32_t num_of_pages);
+    int32_t (*write)(const uint8_t* data, size_t offset, size_t bytes_to_write);
+    size_t (*read)(uint8_t* data, size_t offset, size_t bytes_to_read);
+    uint16_t (*get_number_of_pages)(void);
+    uint32_t (*get_page_size)(void);
+    size_t start_addr;
+} FlashDriverOps;
 
-/**
- * @brief Do nothing at the moment, but reserved for future possible updates
- */
-void flashInit();
-
-/**
- * @param start_page_idx starts from 0 up to maximum number of pages
- * @param num_of_pages last page should not be above flashGetNumberOfPages()
- * @return 0 if success, otherwise < 0
- */
-int8_t flashErase(uint32_t start_page_idx, uint32_t num_of_pages);
-
-/**
- * @brief Before writing you must call flashUnlock(), after writing you must call flashLock()
- *        Write chunk of data like memcpy
- * @return number of written bytes if success, otherwise < 0
- */
-int8_t flashUnlock();
-int32_t flashWrite(const uint8_t* data, size_t offset, size_t bytes_to_write);
-int8_t flashLock();
-
-/**
- * @brief Read chunk of data like memcpy
- * @return bytes_to_read if success, otherwise 0
- */
-size_t flashRead(uint8_t* data, size_t offset, size_t bytes_to_read);
-
-
-/**
- * @return Info about the flash memory
- */
-uint16_t flashGetNumberOfPages();
-uint32_t flashGetPageSize();
 
 #ifdef __cplusplus
 }

include/libparams/rom.h

@@ -12,6 +12,7 @@
 #include <stdint.h>
 #include <stddef.h>
 #include <stdbool.h>
+#include "flash_driver.h"
 
 #ifdef __cplusplus
 extern "C" {
@@ -23,6 +24,7 @@ extern "C" {
  * Use romInit() to create an instance.
  */
 typedef struct {
+    const FlashDriverOps* flash;
     size_t addr;
     size_t first_page_idx;
     size_t total_size;
@@ -41,9 +43,9 @@ typedef struct {
  * On Ubuntu platform, it is safe to use -1 even if it has a single page (equal to idx=0).
  * @param pages_num The amount of allocated pages. At least 1 page is required.
  * @return ROM driver instance. It will have inited=true on success and inited=false on failure.
- * @note Example of a single latest page allocation: romInit(-1, 1)
+ * @note Example of a single latest page allocation: romInit(stm32h753xxInternalFlashGetOps(), -1, 1)
  */
-RomDriverInstance romInit(int32_t first_page_idx, size_t pages_amount);
+RomDriverInstance romInit(const FlashDriverOps* flash, int32_t first_page_idx, size_t pages_amount);
 
 /**
  * @brief Return the number of bytes read (may be less than requested_size).

include/libparams/storage.h

@@ -74,14 +74,17 @@ typedef uint16_t ParamIndex_t;
 
 /**
  * @brief           Initialize the parameters. Call this on startup.
+ * @param flash     Flash driver operations used as parameter storage.
  * @param int_num   The amount of integers parameters
  * @param str_num   The amount of string parameters
  * @param first_page_idx Index of the first page. Negative values are counted from the end.
  *                  For example, -1 means the latest page. For stm32f103 it will be page_idx=127.
  * @param pages_num The amount of allocated pages. At least 1 page is required.
  * @return          LIBPARAMS_OK on success, otherwise < 0.
  */
-int8_t paramsInit(ParamIndex_t int_num, ParamIndex_t str_num,
+int8_t paramsInit(const FlashDriverOps* flash,
+                  ParamIndex_t int_num,
+                  ParamIndex_t str_num,
                   int32_t first_page_idx, size_t pages_num);
 
 /**

libparams.cmake

@@ -18,10 +18,24 @@ FILE(GLOB libparamsPlatformSpecificSrc
   ${CMAKE_CURRENT_LIST_DIR}/platform_specific/${LIBPARAMS_PLATFORM}/*.c*
 )
 
+if(LIBPARAMS_PLATFORM STREQUAL "stm32h753xx")
+  FILE(GLOB libparamsStm32h753xxSpiFramSrc
+    ${CMAKE_CURRENT_LIST_DIR}/platform_specific/stm32h753xx/stm32h753xx_spifram/*.c*
+  )
+  list(APPEND libparamsPlatformSpecificSrc ${libparamsStm32h753xxSpiFramSrc})
+endif()
+
 FILE(GLOB libparamsPlatformSpecificHeaders
   ${CMAKE_CURRENT_LIST_DIR}/platform_specific/${LIBPARAMS_PLATFORM}/
 )
 
+set(libparamsExtraPlatformHeaders)
+if(LIBPARAMS_PLATFORM STREQUAL "stm32h753xx")
+  list(APPEND libparamsExtraPlatformHeaders
+    ${CMAKE_CURRENT_LIST_DIR}/platform_specific/stm32h753xx/stm32h753xx_spifram/
+  )
+endif()
+
 set(libparamsSrc
   ${CMAKE_CURRENT_LIST_DIR}/src/rom.c
   ${CMAKE_CURRENT_LIST_DIR}/src/storage.c
@@ -32,4 +46,5 @@ set(libparamsHeaders
   ${CMAKE_CURRENT_LIST_DIR}/include/libparams/
   ${CMAKE_CURRENT_LIST_DIR}/platform_specific/${LIBPARAMS_PLATFORM}/
   ${libparamsPlatformSpecificHeaders}
+  ${libparamsExtraPlatformHeaders}
 )

platform_specific/stm32f103/flash_driver.c

@@ -8,6 +8,7 @@
 
 #include "flash_driver.h"
 #include <string.h>
+#include "platform_flash_driver.h"
 #include "libparams_error_codes.h"
 #include "flash_registers.h"
 
@@ -21,21 +22,29 @@
 
 uint32_t HAL_GetTick();
 
+static void flashInit(void);
+static int8_t flashUnlock(void);
+static int8_t flashLock(void);
+static int8_t flashErase(uint32_t start_page_idx, uint32_t num_of_pages);
+static int32_t flashWrite(const uint8_t* data, size_t offset, size_t size);
+static size_t flashRead(uint8_t* data, size_t offset, size_t bytes_to_read);
+static uint16_t flashGetNumberOfPages(void);
+static uint32_t flashGetPageSize(void);
 static uint8_t* flashGetPointer();
 static int8_t flashWaitForLastOperation(uint32_t timeout);
 static void flashPageErase(uint32_t page_address);
 static void flashProgramHalfWord(uint32_t address, uint16_t data);
 
 
-void flashInit() {
+static void flashInit(void) {
 }
 
-int8_t flashUnlock() {
+static int8_t flashUnlock(void) {
     WRITE_REG(FLASH->KEYR, FLASH_KEYR_KEY1);
     WRITE_REG(FLASH->KEYR, FLASH_KEYR_KEY2);
     return 0;
 }
-int8_t flashLock() {
+static int8_t flashLock(void) {
     SET_BIT(FLASH->CR, FLASH_CR_LOCK);
     return 0;
 }
@@ -46,7 +55,7 @@ int8_t flashLock() {
  * max 40 ms
  * @note from https://www.st.com/resource/en/datasheet/stm32f103c8.pdf
  */
-int8_t flashErase(uint32_t start_page_idx, uint32_t num_of_pages) {
+static int8_t flashErase(uint32_t start_page_idx, uint32_t num_of_pages) {
     if (flashWaitForLastOperation((uint32_t)FLASH_TIMEOUT_VALUE) != 0) {
         return -1;
     }
@@ -70,7 +79,7 @@ static uint8_t* flashGetPointer() {
     return (uint8_t*) FLASH_START_ADDR;
 }
 
-int32_t flashWrite(const uint8_t* data, size_t offset, size_t size) {
+static int32_t flashWrite(const uint8_t* data, size_t offset, size_t size) {
     int32_t status = flashWaitForLastOperation(FLASH_TIMEOUT_VALUE);
 
     if (status < 0) {
@@ -92,7 +101,7 @@ int32_t flashWrite(const uint8_t* data, size_t offset, size_t size) {
     return status;
 }
 
-size_t flashRead(uint8_t* data, size_t offset, size_t bytes_to_read) {
+static size_t flashRead(uint8_t* data, size_t offset, size_t bytes_to_read) {
     if (data == NULL) {
         return 0;
     }
@@ -102,14 +111,29 @@ size_t flashRead(uint8_t* data, size_t offset, size_t bytes_to_read) {
     return bytes_to_read;
 }
 
-uint16_t flashGetNumberOfPages() {
+static uint16_t flashGetNumberOfPages(void) {
     return 128;
 }
 
-uint32_t flashGetPageSize() {
+static uint32_t flashGetPageSize(void) {
     return FLASH_PAGE_SIZE;
 }
 
+const FlashDriverOps* stm32f103InternalFlashGetOps(void) {
+    static const FlashDriverOps ops = {
+        flashInit,
+        flashUnlock,
+        flashLock,
+        flashErase,
+        flashWrite,
+        flashRead,
+        flashGetNumberOfPages,
+        flashGetPageSize,
+        FLASH_START_ADDR,
+    };
+    return &ops;
+}
+
 static int8_t flashWaitForLastOperation(uint32_t timeout) {
     uint32_t tickstart = HAL_GetTick();
 

platform_specific/stm32f103/platform_flash_driver.h

@@ -0,0 +1,24 @@
+/*
+ * Copyright (c) 2026 Ilia Kliantsevich <iliawork112005@gmail.com>
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+#ifndef LIBPARAMS_STM32F103_PLATFORM_FLASH_DRIVER_H_
+#define LIBPARAMS_STM32F103_PLATFORM_FLASH_DRIVER_H_
+
+#include "flash_driver.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+const FlashDriverOps* stm32f103InternalFlashGetOps(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif  // LIBPARAMS_STM32F103_PLATFORM_FLASH_DRIVER_H_

platform_specific/stm32g0b1/flash_driver.c

@@ -8,10 +8,19 @@
 
 #include "flash_driver.h"
 #include <string.h>
+#include "platform_flash_driver.h"
 #include "main.h"
 #include "libparams_error_codes.h"
 
 
+static void flashInit(void);
+static int8_t flashUnlock(void);
+static int8_t flashLock(void);
+static int8_t flashErase(uint32_t first_page_idx, uint32_t num_of_pages);
+static int32_t flashWrite(const uint8_t* data, size_t offset, size_t size);
+static size_t flashRead(uint8_t* data, size_t offset, size_t bytes_to_read);
+static uint16_t flashGetNumberOfPages(void);
+static uint32_t flashGetPageSize(void);
 static uint8_t* flashGetPointer();
 static int8_t flashErasePagessInSingleBank(uint32_t first_page_idx, uint32_t num_of_pages);
 static int8_t flashWriteU64(uint32_t address, uint64_t data);
@@ -20,13 +29,13 @@ static int8_t flashWriteU64(uint32_t address, uint64_t data);
 static const size_t FLASH_WORD_SIZE = 8;
 
 
-void flashInit() {
+static void flashInit(void) {
 }
 
-int8_t flashUnlock() {
+static int8_t flashUnlock(void) {
     return -HAL_FLASH_Unlock();
 }
-int8_t flashLock() {
+static int8_t flashLock(void) {
     return -HAL_FLASH_Lock();
 }
 
@@ -36,7 +45,7 @@ int8_t flashLock() {
  * max 40 ms
  * @note from https://www.st.com/resource/en/datasheet/stm32g030c6.pdf
  */
-int8_t flashErase(uint32_t first_page_idx, uint32_t num_of_pages) {
+static int8_t flashErase(uint32_t first_page_idx, uint32_t num_of_pages) {
     uint32_t last_page_idx = first_page_idx + num_of_pages;
     if (last_page_idx > flashGetNumberOfPages() || num_of_pages == 0) {
         return LIBPARAMS_WRONG_ARGS;
@@ -57,7 +66,7 @@ int8_t flashErase(uint32_t first_page_idx, uint32_t num_of_pages) {
 }
 
 
-int32_t flashWrite(const uint8_t* data, size_t offset, size_t size) {
+static int32_t flashWrite(const uint8_t* data, size_t offset, size_t size) {
     int32_t status = 0;
     if ((data == NULL) || (size == 0U)) {
         return LIBPARAMS_WRONG_ARGS;
@@ -85,7 +94,7 @@ int32_t flashWrite(const uint8_t* data, size_t offset, size_t size) {
 
     return (int32_t)size;
 }
-size_t flashRead(uint8_t* data, size_t offset, size_t bytes_to_read) {
+static size_t flashRead(uint8_t* data, size_t offset, size_t bytes_to_read) {
     if (data == NULL) {
         return 0;
     }
@@ -95,14 +104,29 @@ size_t flashRead(uint8_t* data, size_t offset, size_t bytes_to_read) {
     return bytes_to_read;
 }
 
-uint16_t flashGetNumberOfPages() {
+static uint16_t flashGetNumberOfPages(void) {
     return 256;
 }
 
-uint32_t flashGetPageSize() {
+static uint32_t flashGetPageSize(void) {
     return 2048;
 }
 
+const FlashDriverOps* stm32g0b1InternalFlashGetOps(void) {
+    static const FlashDriverOps ops = {
+        flashInit,
+        flashUnlock,
+        flashLock,
+        flashErase,
+        flashWrite,
+        flashRead,
+        flashGetNumberOfPages,
+        flashGetPageSize,
+        FLASH_START_ADDR,
+    };
+    return &ops;
+}
+
 static uint8_t* flashGetPointer() {
     return (uint8_t*) FLASH_START_ADDR;
 }