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              : /**
      36              :  * @brief               Returns the size of the retention area.
      37              :  *
      38              :  * @param dev           Retention device to use.
      39              :  *
      40              :  * @retval              Positive value indicating size in bytes on success, else negative errno
      41              :  *                      code.
      42              :  */
      43            1 : ssize_t retention_size(const struct device *dev);
      44              : 
      45              : /**
      46              :  * @brief               Checks if the underlying data in the retention area is valid or not.
      47              :  *
      48              :  * @param dev           Retention device to use.
      49              :  *
      50              :  * @retval 1            If successful and data is valid.
      51              :  * @retval 0            If data is not valid.
      52              :  * @retval -ENOTSUP     If there is no header/checksum configured for the retention area.
      53              :  * @retval -errno       Error code code.
      54              :  */
      55            1 : int retention_is_valid(const struct device *dev);
      56              : 
      57              : /**
      58              :  * @brief               Reads data from the retention area.
      59              :  *
      60              :  * @param dev           Retention device to use.
      61              :  * @param offset        Offset to read data from.
      62              :  * @param buffer        Buffer to store read data in.
      63              :  * @param size          Size of data to read.
      64              :  *
      65              :  * @retval 0            If successful.
      66              :  * @retval -errno       Error code code.
      67              :  */
      68            1 : int retention_read(const struct device *dev, off_t offset, uint8_t *buffer, size_t size);
      69              : 
      70              : /**
      71              :  * @brief               Writes data to the retention area (underlying data does not need to be
      72              :  *                      cleared prior to writing), once function returns with a success code, the
      73              :  *                      data will be classed as valid if queried using retention_is_valid().
      74              :  *
      75              :  * @param dev           Retention device to use.
      76              :  * @param offset        Offset to write data to.
      77              :  * @param buffer        Data to write.
      78              :  * @param size          Size of data to be written.
      79              :  *
      80              :  * @retval              0 on success else negative errno code.
      81              :  */
      82            1 : int retention_write(const struct device *dev, off_t offset, const uint8_t *buffer, size_t size);
      83              : 
      84              : /**
      85              :  * @brief               Clears all data in the retention area (sets it to 0)
      86              :  *
      87              :  * @param dev           Retention device to use.
      88              :  *
      89              :  * @retval              0 on success else negative errno code.
      90              :  */
      91            1 : int retention_clear(const struct device *dev);
      92              : 
      93              : /**
      94              :  * @}
      95              :  */
      96              : 
      97              : #ifdef __cplusplus
      98              : }
      99              : #endif
     100              : 
     101              : #endif /* ZEPHYR_INCLUDE_RETENTION_ */