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_ */