Line data    Source code

       1           1 : /*
       2             :  * Copyright (c) 2023 Nordic Semiconductor ASA
       3             :  *
       4             :  * SPDX-License-Identifier: Apache-2.0
       5             :  */
       6             : 
       7             : /**
       8             :  * @file
       9             :  * @brief Public API for retention API
      10             :  */
      11             : 
      12             : #ifndef ZEPHYR_INCLUDE_RETENTION_
      13             : #define ZEPHYR_INCLUDE_RETENTION_
      14             : 
      15             : #include <stdint.h>
      16             : #include <stddef.h>
      17             : #include <sys/types.h>
      18             : #include <zephyr/kernel.h>
      19             : #include <zephyr/device.h>
      20             : #include <zephyr/types.h>
      21             : 
      22             : #ifdef __cplusplus
      23             : extern "C" {
      24             : #endif
      25             : 
      26             : /**
      27             :  * @brief Retention API
      28             :  * @defgroup retention_api Retention API
      29             :  * @since 3.4
      30             :  * @version 0.1.0
      31             :  * @ingroup os_services
      32             :  * @{
      33             :  */
      34             : 
      35           0 : typedef ssize_t (*retention_size_api)(const struct device *dev);
      36           0 : typedef int (*retention_is_valid_api)(const struct device *dev);
      37           0 : typedef int (*retention_read_api)(const struct device *dev, off_t offset, uint8_t *buffer,
      38             :                                   size_t size);
      39           0 : typedef int (*retention_write_api)(const struct device *dev, off_t offset,
      40             :                                    const uint8_t *buffer, size_t size);
      41           0 : typedef int (*retention_clear_api)(const struct device *dev);
      42             : 
      43           0 : struct retention_api {
      44           0 :         retention_size_api size;
      45           0 :         retention_is_valid_api is_valid;
      46           0 :         retention_read_api read;
      47           0 :         retention_write_api write;
      48           0 :         retention_clear_api clear;
      49             : };
      50             : 
      51             : /**
      52             :  * @brief               Returns the size of the retention area.
      53             :  *
      54             :  * @param dev           Retention device to use.
      55             :  *
      56             :  * @retval              Positive value indicating size in bytes on success, else negative errno
      57             :  *                      code.
      58             :  */
      59           1 : ssize_t retention_size(const struct device *dev);
      60             : 
      61             : /**
      62             :  * @brief               Checks if the underlying data in the retention area is valid or not.
      63             :  *
      64             :  * @param dev           Retention device to use.
      65             :  *
      66             :  * @retval 1            If successful and data is valid.
      67             :  * @retval 0            If data is not valid.
      68             :  * @retval -ENOTSUP     If there is no header/checksum configured for the retention area.
      69             :  * @retval -errno       Error code code.
      70             :  */
      71           1 : int retention_is_valid(const struct device *dev);
      72             : 
      73             : /**
      74             :  * @brief               Reads data from the retention area.
      75             :  *
      76             :  * @param dev           Retention device to use.
      77             :  * @param offset        Offset to read data from.
      78             :  * @param buffer        Buffer to store read data in.
      79             :  * @param size          Size of data to read.
      80             :  *
      81             :  * @retval 0            If successful.
      82             :  * @retval -errno       Error code code.
      83             :  */
      84           1 : int retention_read(const struct device *dev, off_t offset, uint8_t *buffer, size_t size);
      85             : 
      86             : /**
      87             :  * @brief               Writes data to the retention area (underlying data does not need to be
      88             :  *                      cleared prior to writing), once function returns with a success code, the
      89             :  *                      data will be classed as valid if queried using retention_is_valid().
      90             :  *
      91             :  * @param dev           Retention device to use.
      92             :  * @param offset        Offset to write data to.
      93             :  * @param buffer        Data to write.
      94             :  * @param size          Size of data to be written.
      95             :  *
      96             :  * @retval              0 on success else negative errno code.
      97             :  */
      98           1 : int retention_write(const struct device *dev, off_t offset, const uint8_t *buffer, size_t size);
      99             : 
     100             : /**
     101             :  * @brief               Clears all data in the retention area (sets it to 0)
     102             :  *
     103             :  * @param dev           Retention device to use.
     104             :  *
     105             :  * @retval              0 on success else negative errno code.
     106             :  */
     107           1 : int retention_clear(const struct device *dev);
     108             : 
     109             : /**
     110             :  * @}
     111             :  */
     112             : 
     113             : #ifdef __cplusplus
     114             : }
     115             : #endif
     116             : 
     117             : #endif /* ZEPHYR_INCLUDE_RETENTION_ */