diff --git a/doc/nrf-bm/api/api.rst b/doc/nrf-bm/api/api.rst index 6419280447..fc79992291 100644 --- a/doc/nrf-bm/api/api.rst +++ b/doc/nrf-bm/api/api.rst @@ -84,6 +84,8 @@ Bare Metal Low Power UART with EasyDMA driver :inner: :members: +.. _api_storage: + Bare Metal Storage library ========================== diff --git a/doc/nrf-bm/libraries/bm_storage.rst b/doc/nrf-bm/libraries/bm_storage.rst new file mode 100644 index 0000000000..1fbd0cd908 --- /dev/null +++ b/doc/nrf-bm/libraries/bm_storage.rst @@ -0,0 +1,131 @@ +.. _lib_storage: + +Storage Library +############### + +.. contents:: + :local: + :depth: 2 + +The Storage library provides abstractions for reading, writing, and erasing non-volatile memory (NVM). + +Overview +******** + +The library supports multiple storage instances, each bound to a specific memory region, and reports operation results through user-defined event handlers. +Depending on the backend and runtime state, operations may be synchronous or asynchronous. + +Configuration +************* + +The library is enabled and configured entirely using the Kconfig system. +Set the :kconfig:option:`CONFIG_BM_STORAGE` Kconfig option to enable the library. + +Select a storage backend by enabling one of the following Kconfig options: + +* :kconfig:option:`CONFIG_BM_STORAGE_BACKEND_RRAM` – RRAM backend. The events reported are synchronous. +* :kconfig:option:`CONFIG_BM_STORAGE_BACKEND_SD` – SoftDevice backend. The events reported are asynchronous. + +SoftDevice backend options: + +* :kconfig:option:`CONFIG_BM_STORAGE_BACKEND_SD_QUEUE_SIZE` – Queue size for pending operations. +* :kconfig:option:`CONFIG_BM_STORAGE_BACKEND_SD_MAX_RETRIES` – Maximum retries if the SoftDevice is busy. + +Initialization +============== + +Each storage instance is represented by a :c:struct:`bm_storage` structure. + +To initialize a storage instance, use the :c:func:`bm_storage_init` function, providing the following information: + +* :c:member:`bm_storage.evt_handler` – Event callback. +* :c:member:`bm_storage.start_addr` and :c:member:`bm_storage.end_addr` – Accessible address range. + +You can uninitialize a storage instance with the :c:func:`bm_storage_uninit` function. + +Usage +***** + +The following is a list of operations you can perform with this library. + +Read +==== + +Use the :c:func:`bm_storage_read` function to copy data from NVM into RAM. +The data length must be a multiple of the backend’s program unit and within the configured region. + +.. note:: + + The program unit is the smallest block of data that the backend can write in a single operation. + Both the destination address and the length must be aligned to this size. + The program unit is reported by :c:member:`bm_storage_info.program_unit`. + +Write +===== + +Use the :c:func:`bm_storage_write` function to write data to NVM. +Writes are validated against alignment and range, and completion is reported through :c:member:`bm_storage.evt_handler`. + +.. note:: + + Writes must be aligned to the backend’s program unit, reported by :c:member:`bm_storage_info.program_unit`. + This ensures that both the write address and the write length are correct for the underlying memory technology. + +Erase +===== + +Use the :c:func:`bm_storage_erase` function to erase a region in NVM. +``len`` must be a multiple of the erase unit. +If not supported by the backend, the call may return ``NRF_ERROR_NOT_SUPPORTED``. +This means that the backend does not require the region to be erased before another write operation. + +.. note:: + + The erase unit is the minimum erasable block in NVM. + Erase operations must start at an address aligned by the erase unit and use a length that is a multiple of this value. + The erase unit is reported by :c:member:`bm_storage_info.erase_unit`. + +Busy state +========== + +Use the :c:func:`bm_storage_is_busy` function to check whether a backend is executing an operation. + +Events +====== + +The following events may be reported to the user callback: + +* :c:enum:`BM_STORAGE_EVT_WRITE_RESULT` – Write operation completed. +* :c:enum:`BM_STORAGE_EVT_ERASE_RESULT` – Erase operation completed. + +Each event includes the result code, information about the address range of the associated operation, and whether the operation is synchronous or asynchronous. + +Sample +****** + +The usage of this library is demonstrated in the :ref:`storage_sample` sample. + +Dependencies +************ + +* :kconfig:option:`CONFIG_BM_STORAGE_BACKEND_RRAM`: + + This backend requires the following Kconfig options to be disabled: + + * :kconfig:option:`CONFIG_SOFTDEVICE` + +* :kconfig:option:`CONFIG_BM_STORAGE_BACKEND_SD`: + + This backend requires the following Kconfig options to be enabled: + + * :kconfig:option:`CONFIG_SOFTDEVICE` + * :kconfig:option:`CONFIG_NRF_SDH` + * :kconfig:option:`CONFIG_RING_BUFFER` + +API documentation +***************** + +| Header file: :file:`include/bm_storage.h` +| Source files: :file:`lib/bm_storage/` + +:ref:`Storage library API reference ` diff --git a/doc/nrf-bm/release_notes/release_notes_changelog.rst b/doc/nrf-bm/release_notes/release_notes_changelog.rst index 042200f3e4..5f26e83856 100644 --- a/doc/nrf-bm/release_notes/release_notes_changelog.rst +++ b/doc/nrf-bm/release_notes/release_notes_changelog.rst @@ -151,6 +151,7 @@ Documentation * Added documentation for the :ref:`lib_ble_queued_writes` library. * Added documentation for the :ref:`lib_event_scheduler` library. * Added documentation for the :ref:`lib_sensorsim` library. +* Added documentation for the :ref:`lib_storage` library. * Added documentation for the :ref:`lib_ble_queued_writes` library. Interrupts diff --git a/include/bm/storage/bm_storage.h b/include/bm/storage/bm_storage.h index fee71e1ccd..42e720ebf4 100644 --- a/include/bm/storage/bm_storage.h +++ b/include/bm/storage/bm_storage.h @@ -77,13 +77,21 @@ typedef void (*bm_storage_evt_handler_t)(struct bm_storage_evt *evt); * @brief Information about the implementation-specific non-volatile memory. */ struct bm_storage_info { - /* Size of a page (in bytes). A page is the smallest unit that can be erased. */ + /** + * @brief Size of a page (in bytes). A page is the smallest unit that can be erased. + */ uint32_t erase_unit; - /* Value used by the implementation-specific backend to represent erased memory. */ + /** + * @brief Value used by the implementation-specific backend to represent erased memory. + */ uint32_t erase_value; - /* Size of the smallest programmable unit (in bytes). */ + /** + * @brief Size of the smallest programmable unit (in bytes). + */ uint32_t program_unit; - /* Specifies if the implementation-specific backend does not need erase. */ + /** + * @brief Specifies if the implementation-specific backend does not need erase. + */ bool no_explicit_erase; }; @@ -213,6 +221,8 @@ uint32_t bm_storage_write(const struct bm_storage *storage, uint32_t dest, const * @brief Erase data in a storage instance. * * @param[in] storage Storage instance to erase data in. + * @param[in] dest Address in non-volatile memory where to erase the data. + * @param[in] len Length of the data to be erased (in bytes). * @param[in] ctx Pointer to user data, passed to the implementation-specific API function call. * Can be NULL. *