LCOV - code coverage report
Current view: top level - zephyr/fs - fcb.h Coverage Total Hit
Test: new.info Lines: 97.4 % 39 38
Test Date: 2025-09-05 22:20:39

            Line data    Source code
       1            0 : /*
       2              :  * Copyright (c) 2017-2023 Nordic Semiconductor ASA
       3              :  * Copyright (c) 2015 Runtime Inc
       4              :  *
       5              :  * SPDX-License-Identifier: Apache-2.0
       6              :  */
       7              : #ifndef ZEPHYR_INCLUDE_FS_FCB_H_
       8              : #define ZEPHYR_INCLUDE_FS_FCB_H_
       9              : 
      10              : /*
      11              :  * Flash circular buffer.
      12              :  */
      13              : #include <inttypes.h>
      14              : #include <limits.h>
      15              : 
      16              : #include <zephyr/storage/flash_map.h>
      17              : #include <zephyr/sys/util_macro.h>
      18              : 
      19              : #include <zephyr/kernel.h>
      20              : 
      21              : #ifdef __cplusplus
      22              : extern "C" {
      23              : #endif
      24              : 
      25              : /**
      26              :  * @defgroup fcb Flash Circular Buffer (FCB)
      27              :  * @since 1.11
      28              :  * @version 1.0.0
      29              :  * @ingroup file_system_storage
      30              :  * @{
      31              :  * @}
      32              :  */
      33              : 
      34              : /**
      35              :  * @defgroup fcb_data_structures Flash Circular Buffer Data Structures
      36              :  * @ingroup fcb
      37              :  * @{
      38              :  */
      39              : 
      40            1 : #define FCB_MAX_LEN     (0x3fffu) /**< Max length of element (16,383) */
      41              : 
      42              : /**
      43              :  * @brief FCB entry info structure. This data structure describes the element
      44              :  * location in the flash.
      45              :  *
      46              :  * You would use it to figure out what parameters to pass to flash_area_read()
      47              :  * to read element contents. Or to flash_area_write() when adding a new element.
      48              :  * Entry location is pointer to area (within fcb->f_sectors), and offset
      49              :  * within that area.
      50              :  */
      51            1 : struct fcb_entry {
      52            1 :         struct flash_sector *fe_sector;
      53              :         /**< Pointer to info about sector where data are placed */
      54              : 
      55            1 :         uint32_t fe_elem_off;
      56              :         /**< Offset from the start of the sector to beginning of element. */
      57              : 
      58            1 :         uint32_t fe_data_off;
      59              :         /**< Offset from the start of the sector to the start of element. */
      60              : 
      61            1 :         uint16_t fe_data_len; /**< Size of data area in fcb entry*/
      62              : };
      63              : 
      64              : /**
      65              :  * @brief Helper macro for calculating the data offset related to
      66              :  * the fcb flash_area start offset.
      67              :  *
      68              :  * @param entry fcb entry structure
      69              :  */
      70            1 : #define FCB_ENTRY_FA_DATA_OFF(entry) (entry.fe_sector->fs_off +\
      71              :                                       entry.fe_data_off)
      72              : /**
      73              :  * @brief Structure for transferring complete information about FCB entry
      74              :  * location within flash memory.
      75              :  */
      76            1 : struct fcb_entry_ctx {
      77            1 :         struct fcb_entry loc; /**< FCB entry info */
      78            1 :         const struct flash_area *fap;
      79              :         /**< Flash area where the entry is placed */
      80              : };
      81              : 
      82              : /**
      83              :  * @brief Flag to disable CRC for the fcb_entries in flash.
      84              :  */
      85            1 : #define FCB_FLAGS_CRC_DISABLED BIT(0)
      86              : 
      87              : /**
      88              :  * @brief FCB instance structure
      89              :  *
      90              :  * The following data structure describes the FCB itself. First part should
      91              :  * be filled in by the user before calling @ref fcb_init. The second part is
      92              :  * used by FCB for its internal bookkeeping.
      93              :  */
      94            1 : struct fcb {
      95              :         /* Caller of fcb_init fills this in */
      96            1 :         uint32_t f_magic;
      97              :         /**< Magic value, should not be 0xFFFFFFFF.
      98              :          * It is xored with inversion of f_erase_value and placed in
      99              :          * the beginning of FCB flash sector. FCB uses this when determining
     100              :          * whether sector contains valid data or not.
     101              :          * Giving it value of 0xFFFFFFFF means leaving bytes of the filed
     102              :          * in "erased" state.
     103              :          */
     104              : 
     105            1 :         uint8_t f_version; /**<  Current version number of the data */
     106            1 :         uint8_t f_sector_cnt; /**< Number of elements in sector array */
     107            1 :         uint8_t f_scratch_cnt;
     108              :         /**< Number of sectors to keep empty. This can be used if you need
     109              :          * to have scratch space for garbage collecting when FCB fills up.
     110              :          */
     111              : 
     112            1 :         struct flash_sector *f_sectors;
     113              :         /**< Array of sectors, must be contiguous */
     114              : 
     115              :         /* Flash circular buffer internal state */
     116            1 :         struct k_mutex f_mtx;
     117              :         /**< Locking for accessing the FCB data, internal state */
     118              : 
     119            1 :         struct flash_sector *f_oldest;
     120              :         /**< Pointer to flash sector containing the oldest data,
     121              :          * internal state
     122              :          */
     123              : 
     124            1 :         struct fcb_entry f_active; /**< internal state */
     125            1 :         uint16_t f_active_id;
     126              :         /**< Flash location where the newest data is, internal state */
     127              : 
     128            1 :         uint8_t f_align;
     129              :         /**< writes to flash have to aligned to this, internal state */
     130              : 
     131            1 :         const struct flash_area *fap;
     132              :         /**< Flash area used by the fcb instance, internal state.
     133              :          * This can be transfer to FCB user
     134              :          */
     135              : 
     136            1 :         uint8_t f_erase_value;
     137              :         /**< The value flash takes when it is erased. This is read from
     138              :          * flash parameters and initialized upon call to fcb_init.
     139              :          */
     140              : #ifdef CONFIG_FCB_ALLOW_FIXED_ENDMARKER
     141              :         const uint8_t f_flags;
     142              :         /**< Flags for configuring the FCB. */
     143              : #endif
     144              : };
     145              : 
     146              : /**
     147              :  * @}
     148              :  */
     149              : 
     150              : /**
     151              :  * @brief Flash Circular Buffer APIs
     152              :  * @defgroup fcb_api fcb API
     153              :  * @ingroup fcb
     154              :  * @{
     155              :  */
     156              : 
     157              : /**
     158              :  * Initialize FCB instance.
     159              :  *
     160              :  * @param[in] f_area_id ID of flash area where fcb storage resides.
     161              :  * @param[in,out] fcbp  FCB instance structure.
     162              :  *
     163              :  * @return 0 on success, non-zero on failure.
     164              :  */
     165            1 : int fcb_init(int f_area_id, struct fcb *fcbp);
     166              : 
     167              : /**
     168              :  * Appends an entry to circular buffer.
     169              :  *
     170              :  * When writing the
     171              :  * contents for the entry, use loc->fe_sector and loc->fe_data_off with
     172              :  * flash_area_write() to fcb flash_area.
     173              :  * When you're finished, call fcb_append_finish() with loc as argument.
     174              :  *
     175              :  * @param[in] fcbp FCB instance structure.
     176              :  * @param[in] len Length of data which are expected to be written as the entry
     177              :  *            payload.
     178              :  * @param[out] loc entry location information
     179              :  *
     180              :  * @return 0 on success, non-zero on failure.
     181              :  */
     182            1 : int fcb_append(struct fcb *fcbp, uint16_t len, struct fcb_entry *loc);
     183              : 
     184              : /**
     185              :  * Finishes entry append operation.
     186              :  *
     187              :  * @param[in] fcbp FCB instance structure.
     188              :  * @param[in] append_loc entry location information
     189              :  *
     190              :  * @return 0 on success, non-zero on failure.
     191              :  */
     192            1 : int fcb_append_finish(struct fcb *fcbp, struct fcb_entry *append_loc);
     193              : 
     194              : /**
     195              :  * FCB Walk callback function type.
     196              :  *
     197              :  * Type of function which is expected to be called while walking over fcb
     198              :  * entries thanks to a @ref fcb_walk call.
     199              :  *
     200              :  * Entry data can be read using flash_area_read(), using
     201              :  * loc_ctx fields as arguments.
     202              :  * If cb wants to stop the walk, it should return non-zero value.
     203              :  *
     204              :  * @param[in] loc_ctx entry location information (full context)
     205              :  * @param[in,out] arg callback context, transferred from @ref fcb_walk.
     206              :  *
     207              :  * @return 0 continue walking, non-zero stop walking.
     208              :  */
     209            1 : typedef int (*fcb_walk_cb)(struct fcb_entry_ctx *loc_ctx, void *arg);
     210              : 
     211              : /**
     212              :  * Walk over all entries in the FCB sector
     213              :  *
     214              :  * @param[in] sector     fcb sector to be walked. If null, traverse entire
     215              :  *                       storage.
     216              :  * @param[in] fcbp       FCB instance structure.
     217              :  * @param[in] cb         pointer to the function which gets called for every
     218              :  *                       entry. If cb wants to stop the walk, it should return
     219              :  *                       non-zero value.
     220              :  * @param[in,out] cb_arg callback context, transferred to the callback
     221              :  *                       implementation.
     222              :  *
     223              :  * @return 0 on success, negative on failure (or transferred form callback
     224              :  *         return-value), positive transferred form callback return-value
     225              :  */
     226            1 : int fcb_walk(struct fcb *fcbp, struct flash_sector *sector, fcb_walk_cb cb, void *cb_arg);
     227              : 
     228              : /**
     229              :  * Get next fcb entry location.
     230              :  *
     231              :  * Function to obtain fcb entry location in relation to entry pointed by
     232              :  * <p> loc.
     233              :  * If loc->fe_sector is set and loc->fe_elem_off is not 0 function fetches next
     234              :  * fcb entry location.
     235              :  * If loc->fe_sector is NULL function fetches the oldest entry location within
     236              :  * FCB storage. loc->fe_sector is set and loc->fe_elem_off is 0 function fetches
     237              :  * the first entry location in the fcb sector.
     238              :  *
     239              :  * @param[in] fcbp FCB instance structure.
     240              :  * @param[in,out] loc entry location information
     241              :  *
     242              :  * @return 0 on success, non-zero on failure.
     243              :  */
     244            1 : int fcb_getnext(struct fcb *fcbp, struct fcb_entry *loc);
     245              : 
     246              : /**
     247              :  * Rotate fcb sectors
     248              :  *
     249              :  * Function erases the data from oldest sector. Upon that the next sector
     250              :  * becomes the oldest. Active sector is also switched if needed.
     251              :  *
     252              :  * @param[in] fcbp FCB instance structure.
     253              :  */
     254            1 : int fcb_rotate(struct fcb *fcbp);
     255              : 
     256              : /**
     257              :  * Start using the scratch block.
     258              :  *
     259              :  * Take one of the scratch blocks into use. So a scratch sector becomes
     260              :  * active sector to which entries can be appended.
     261              :  *
     262              :  * @param[in] fcbp FCB instance structure.
     263              :  *
     264              :  * @return 0 on success, non-zero on failure.
     265              :  */
     266            1 : int fcb_append_to_scratch(struct fcb *fcbp);
     267              : 
     268              : /**
     269              :  * Get free sector count.
     270              :  *
     271              :  * @param[in] fcbp FCB instance structure.
     272              :  *
     273              :  * @return Number of free sectors.
     274              :  */
     275            1 : int fcb_free_sector_cnt(struct fcb *fcbp);
     276              : 
     277              : /**
     278              :  * Check whether FCB has any data.
     279              :  *
     280              :  * @param[in] fcbp FCB instance structure.
     281              :  *
     282              :  * @return Positive value if fcb is empty, otherwise 0.
     283              :  */
     284            1 : int fcb_is_empty(struct fcb *fcbp);
     285              : 
     286              : /**
     287              :  * Finds the fcb entry that gives back up to n entries at the end.
     288              :  *
     289              :  * @param[in] fcbp          FCB instance structure.
     290              :  * @param[in] entries       number of fcb entries the user wants to get
     291              :  * @param[out] last_n_entry last_n_entry the fcb_entry to be returned
     292              :  *
     293              :  * @return 0 on there are any fcbs available; -ENOENT otherwise
     294              :  */
     295            1 : int fcb_offset_last_n(struct fcb *fcbp, uint8_t entries, struct fcb_entry *last_n_entry);
     296              : 
     297              : /**
     298              :  * Clear fcb instance storage.
     299              :  *
     300              :  * @param[in] fcbp FCB instance structure.
     301              :  *
     302              :  * @return 0 on success; non-zero on failure
     303              :  */
     304            1 : int fcb_clear(struct fcb *fcbp);
     305              : 
     306              : /**
     307              :  * @}
     308              :  */
     309              : 
     310              : /**
     311              :  * @brief Flash Circular internal
     312              :  * @defgroup fcb_internal fcb non-API prototypes
     313              :  * @ingroup fcb
     314              :  * @{
     315              :  */
     316              : 
     317              : /**
     318              :  * Read raw data from the fcb flash sector.
     319              :  *
     320              :  * @param[in] fcbp   FCB instance structure.
     321              :  * @param[in] sector FCB sector.
     322              :  * @param[in] off    Read offset form sector begin.
     323              :  * @param[out] dst   Destination buffer.
     324              :  * @param[in] len    Read-out size.
     325              :  *
     326              :  * @return  0 on success, negative errno code on fail.
     327              :  */
     328            1 : int fcb_flash_read(const struct fcb *fcbp, const struct flash_sector *sector, off_t off,
     329              :                    void *dst, size_t len);
     330              : 
     331              : /**
     332              :  * Write raw data to the fcb flash sector.
     333              :  *
     334              :  * @param[in] fcbp   FCB instance structure.
     335              :  * @param[in] sector FCB sector.
     336              :  * @param[in] off    Write offset form sector begin.
     337              :  * @param[in] src    Source buffer.
     338              :  * @param[in] len    Write size.
     339              :  *
     340              :  * @return  0 on success, negative errno code on fail.
     341              :  */
     342            1 : int fcb_flash_write(const struct fcb *fcbp, const struct flash_sector *sector, off_t off,
     343              :                     const void *src, size_t len);
     344              : 
     345              : /**
     346              :  * @}
     347              :  */
     348              : 
     349              : #ifdef __cplusplus
     350              : }
     351              : #endif
     352              : 
     353              : #endif /* ZEPHYR_INCLUDE_FS_FCB_H_ */
        

Generated by: LCOV version 2.0-1