fs/fcb: add API documentation to the header
Added doxygen documentation for FCB API. Signed-off-by: Andrzej Puzdrowski <andrzej.puzdrowski@nordicsemi.no>
This commit is contained in:
Andrzej Puzdrowski
Maureen Helm
parent
50b28c010d
commit
a6d44f6c8f
1 changed files with 244 additions and 43 deletions
287
include/fs/fcb.h
287
include/fs/fcb.h
|
|
@ -21,50 +21,106 @@ extern "C" {
|
|||
|
||||
#include <kernel.h>
|
||||
|
||||
#define FCB_MAX_LEN (CHAR_MAX | CHAR_MAX << 7) /* Max length of element */
|
||||
/**
|
||||
* @defgroup fcb Flash Circular Buffer (FCB)
|
||||
* @ingroup file_system_storage
|
||||
* @{
|
||||
* @}
|
||||
*/
|
||||
|
||||
/*
|
||||
/**
|
||||
* @defgroup fcb_data_structures Flash Circular Buffer Data Structures
|
||||
* @ingroup fcb
|
||||
* @{
|
||||
*/
|
||||
|
||||
#define FCB_MAX_LEN (CHAR_MAX | CHAR_MAX << 7) /**< Max length of element */
|
||||
|
||||
/**
|
||||
* @brief FCB entry info structure. This data structure describes the element
|
||||
* location in the flash.
|
||||
*
|
||||
* You would use it to figure out what parameters to pass to flash_area_read()
|
||||
* to read element contents. Or to flash_area_write() when adding a new element.
|
||||
* Entry location is pointer to area (within fcb->f_sectors), and offset
|
||||
* within that area.
|
||||
*/
|
||||
struct fcb_entry {
|
||||
struct flash_sector *fe_sector; /* ptr to sector */
|
||||
/* within fcb->f_sectors */
|
||||
u32_t fe_elem_off; /* start of entry */
|
||||
u32_t fe_data_off; /* start of data */
|
||||
u16_t fe_data_len; /* size of data area */
|
||||
struct flash_sector *fe_sector;
|
||||
/**< Pointer to info about sector where data are placed */
|
||||
|
||||
u32_t fe_elem_off;
|
||||
/**< Offset from the start of the sector to beginning of element. */
|
||||
|
||||
u32_t fe_data_off;
|
||||
/**< Offset from the start of the sector to the start of element. */
|
||||
|
||||
u16_t fe_data_len; /**< Size of data area in fcb entry*/
|
||||
};
|
||||
|
||||
/*
|
||||
* Helper macro for calculate the data offset related to
|
||||
/**
|
||||
* @brief Helper macro for calculating the data offset related to
|
||||
* the fcb flash_area start offset.
|
||||
*
|
||||
* @param entry fcb entry structure
|
||||
*/
|
||||
#define FCB_ENTRY_FA_DATA_OFF(entry) (entry.fe_sector->fs_off +\
|
||||
entry.fe_data_off)
|
||||
|
||||
/**
|
||||
* @brief Structure for transferring complete information about FCB entry
|
||||
* location within flash memory.
|
||||
*/
|
||||
struct fcb_entry_ctx {
|
||||
struct fcb_entry loc;
|
||||
struct fcb_entry loc; /**< FCB entry info */
|
||||
const struct flash_area *fap;
|
||||
/**< Flash area where the entry is placed */
|
||||
};
|
||||
|
||||
/**
|
||||
* @brief FCB instance structure
|
||||
*
|
||||
* The following data structure describes the FCB itself. First part should
|
||||
* be filled in by the user before calling @ref fcb_init. The second part is
|
||||
* used by FCB for its internal bookkeeping.
|
||||
*/
|
||||
struct fcb {
|
||||
/* Caller of fcb_init fills this in */
|
||||
u32_t f_magic; /* As placed on the disk */
|
||||
u8_t f_version; /* Current version number of the data */
|
||||
u8_t f_sector_cnt; /* Number of elements in sector array */
|
||||
u8_t f_scratch_cnt; /* How many sectors should be kept empty */
|
||||
struct flash_sector *f_sectors; /* Array of sectors, */
|
||||
/* must be contiguous */
|
||||
u32_t f_magic;
|
||||
/**< Magic value. It is placed in the beginning of FCB flash sector.
|
||||
* FCB uses this when determining whether sector contains valid data
|
||||
* or not.
|
||||
*/
|
||||
|
||||
u8_t f_version; /**< Current version number of the data */
|
||||
u8_t f_sector_cnt; /**< Number of elements in sector array */
|
||||
u8_t f_scratch_cnt;
|
||||
/**< Number of sectors to keep empty. This can be used if you need
|
||||
* to have scratch space for garbage collecting when FCB fills up.
|
||||
*/
|
||||
|
||||
struct flash_sector *f_sectors;
|
||||
/**< Array of sectors, must be contiguous */
|
||||
|
||||
/* Flash circular buffer internal state */
|
||||
struct k_mutex f_mtx; /* Locking for accessing the FCB data */
|
||||
struct flash_sector *f_oldest;
|
||||
struct fcb_entry f_active;
|
||||
u16_t f_active_id;
|
||||
u8_t f_align; /* writes to flash have to aligned to this */
|
||||
struct k_mutex f_mtx;
|
||||
/**< Locking for accessing the FCB data, internal state */
|
||||
|
||||
const struct flash_area *fap; /* Flash area used by the fcb instance */
|
||||
/* This can be transfer to FCB user */
|
||||
struct flash_sector *f_oldest;
|
||||
/**< Pointer to flash sector containing the oldest data,
|
||||
* internal state
|
||||
*/
|
||||
|
||||
struct fcb_entry f_active; /**< internal state */
|
||||
u16_t f_active_id;
|
||||
/**< Flash location where the newest data is, internal state */
|
||||
|
||||
u8_t f_align;
|
||||
/**< writes to flash have to aligned to this, internal state */
|
||||
|
||||
const struct flash_area *fap;
|
||||
/**< Flash area used by the fcb instance, , internal state.
|
||||
* This can be transfer to FCB user
|
||||
*/
|
||||
};
|
||||
|
||||
/*
|
||||
|
|
@ -79,66 +135,211 @@ struct fcb {
|
|||
#define FCB_ERR_CRC -6
|
||||
#define FCB_ERR_MAGIC -7
|
||||
|
||||
/**
|
||||
* @}
|
||||
*/
|
||||
|
||||
/**
|
||||
* @brief Flash Circular Buffer APIs
|
||||
* @defgroup fcb_api fcb API
|
||||
* @ingroup fcb
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* Initialize FCB instance.
|
||||
*
|
||||
* @param[in] f_area_id ID of flash area where fcb storage resides.
|
||||
* @param[in,out] fcb FCB instance structure.
|
||||
*
|
||||
* @return 0 on success, non-zero on failure.
|
||||
*/
|
||||
int fcb_init(int f_area_id, struct fcb *fcb);
|
||||
|
||||
/*
|
||||
* fcb_append() appends an entry to circular buffer. When writing the
|
||||
* contents for the entry, use loc->fl_area and loc->fl_data_off with
|
||||
* flash_area_write(). When you're finished, call fcb_append_finish() with
|
||||
* loc as argument.
|
||||
/**
|
||||
* Appends an entry to circular buffer.
|
||||
*
|
||||
* When writing the
|
||||
* contents for the entry, use loc->fl_sector and loc->fl_data_off with
|
||||
* flash_area_write() to fcb flash_area.
|
||||
* When you're finished, call fcb_append_finish() with loc as argument.
|
||||
*
|
||||
* @param[in] fcb FCB instance structure.
|
||||
* @param[in] len Length of data which are expected to be written as the entry
|
||||
* payload.
|
||||
* @param[out] loc entry location information
|
||||
*
|
||||
* @return 0 on success, non-zero on failure.
|
||||
*/
|
||||
int fcb_append(struct fcb *fcb, u16_t len, struct fcb_entry *loc);
|
||||
|
||||
/**
|
||||
* Finishes entry append operation.
|
||||
*
|
||||
* @param[in] fcb FCB instance structure.
|
||||
* @param[in] append_loc entry location information
|
||||
*
|
||||
* @return 0 on success, non-zero on failure.
|
||||
*/
|
||||
int fcb_append_finish(struct fcb *fcb, struct fcb_entry *append_loc);
|
||||
|
||||
/*
|
||||
* Walk over all log entries in FCB, or entries in a given flash_area.
|
||||
* cb gets called for every entry. If cb wants to stop the walk, it should
|
||||
* return non-zero value.
|
||||
/**
|
||||
* FCB Walk callback function type.
|
||||
*
|
||||
* Type of function which is expected to be called while walking over fcb
|
||||
* entries thanks to a @ref fcb_walk call.
|
||||
*
|
||||
* Entry data can be read using flash_area_read(), using
|
||||
* loc->fe_area, loc->fe_data_off, and loc->fe_data_len as arguments.
|
||||
* loc_ctx fields as arguments.
|
||||
* If cb wants to stop the walk, it should return non-zero value.
|
||||
*
|
||||
* @param[in] loc_ctx entry location information (full context)
|
||||
* @param[in,out] arg callback context, transferred from @ref fcb_walk.
|
||||
*
|
||||
* @return 0 continue walking, non-zero stop walking.
|
||||
*/
|
||||
typedef int (*fcb_walk_cb)(struct fcb_entry_ctx *loc_ctx, void *arg);
|
||||
|
||||
/**
|
||||
* Walk over all entries in the FCB sector
|
||||
*
|
||||
* @param[in] sector fcb sector to be wallked. If null, traverse entire
|
||||
* storage.
|
||||
* @param[in] fcb FCB instance structure.
|
||||
* @param[in] cb pointer to the function which gets called for every
|
||||
* entry. If cb wants to stop the walk, it should return
|
||||
* non-zero value.
|
||||
* @param[in,out] cb_arg callback context, transferred to the callback
|
||||
* implementation.
|
||||
*
|
||||
* @return 0 on success, negative on failure (or transferred form callback
|
||||
* return-value), positive transferred form callback return-value
|
||||
*/
|
||||
int fcb_walk(struct fcb *fcb, struct flash_sector *sector, fcb_walk_cb cb,
|
||||
void *cb_arg);
|
||||
|
||||
/**
|
||||
* Get next fcb entry location.
|
||||
*
|
||||
* Function to obtain fcb entry location in relation to entry pointed by
|
||||
* <p> loc.
|
||||
* If loc->fe_sector is set and loc->fe_elem_off is not 0 function fetches next
|
||||
* fcb entry location.
|
||||
* If loc->fe_sector is NULL function fetches the oldest entry location within
|
||||
* FCB storage. loc->fe_sector is set and loc->fe_elem_off is 0 function fetches
|
||||
* the first entry location in the fcb sector.
|
||||
*
|
||||
* @param[in] fcb FCB instance structure.
|
||||
* @param[in,out] loc entry location information
|
||||
*
|
||||
* @return 0 on success, non-zero on failure.
|
||||
*/
|
||||
int fcb_getnext(struct fcb *fcb, struct fcb_entry *loc);
|
||||
|
||||
/*
|
||||
* Erases the data from oldest sector.
|
||||
* Rotate fcb sectors
|
||||
*
|
||||
* Function erases the data from oldest sector. Upon that the next sector
|
||||
* becomes the oldest. Active sector is also switched if needed.
|
||||
*
|
||||
* @param[in] fcb FCB instance structure.
|
||||
*/
|
||||
int fcb_rotate(struct fcb *fcb);
|
||||
|
||||
/*
|
||||
* Start using the scratch block.
|
||||
*
|
||||
* Take one of the scratch blocks into use. So a scratch sector becomes
|
||||
* active sector to which entries can be appended.
|
||||
*
|
||||
* @param[in] fcb FCB instance structure.
|
||||
*
|
||||
* @return 0 on success, non-zero on failure.
|
||||
*/
|
||||
int fcb_append_to_scratch(struct fcb *fcb);
|
||||
|
||||
/*
|
||||
* How many sectors are unused.
|
||||
/**
|
||||
* Get free sector count.
|
||||
*
|
||||
* @param[in] fcb FCB instance structure.
|
||||
*
|
||||
* @return Number of free sectors.
|
||||
*/
|
||||
int fcb_free_sector_cnt(struct fcb *fcb);
|
||||
|
||||
/*
|
||||
* Whether FCB has any data.
|
||||
/**
|
||||
* Check whether FCB has any data.
|
||||
*
|
||||
* @param[in] fcb FCB instance structure.
|
||||
*
|
||||
* @return Positive value if fcb is empty, otherwise 0.
|
||||
*/
|
||||
int fcb_is_empty(struct fcb *fcb);
|
||||
|
||||
/*
|
||||
* Element at offset *entries* from last position (backwards).
|
||||
/**
|
||||
* Finds the fcb entry that gives back up to n entries at the end.
|
||||
*
|
||||
* @param[in] fcb FCB instance structure.
|
||||
* @param[in] entries number of fcb entries the user wants to get
|
||||
* @param[out] last_n_entry last_n_entry the fcb_entry to be returned
|
||||
*
|
||||
* @return 0 on there are any fcbs available; -ENOENT otherwise
|
||||
*/
|
||||
int fcb_offset_last_n(struct fcb *fcb, u8_t entries,
|
||||
struct fcb_entry *last_n_entry);
|
||||
|
||||
/*
|
||||
* Clears FCB passed to it
|
||||
/**
|
||||
* Clear fcb instance storage.
|
||||
*
|
||||
* @param[in] fcb FCB instance structure.
|
||||
*
|
||||
* @return 0 on success; non-zero on failure
|
||||
*/
|
||||
int fcb_clear(struct fcb *fcb);
|
||||
|
||||
/**
|
||||
* @}
|
||||
*/
|
||||
|
||||
/**
|
||||
* @brief Flash Circular internall
|
||||
* @defgroup fcb_internall fcb non-API prototypes
|
||||
* @ingroup fcb
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* Read raw data from the fcb flash sector.
|
||||
*
|
||||
* @param[in] fcb FCB instance structure.
|
||||
* @param[in] sector FCB sector.
|
||||
* @param[in] off Read offset form sector begin.
|
||||
* @param[out] dst Destination buffer.
|
||||
* @param[in] len Read-out size.
|
||||
*
|
||||
* @return 0 on success, negative errno code on fail.
|
||||
*/
|
||||
int fcb_flash_read(const struct fcb *fcb, const struct flash_sector *sector,
|
||||
off_t off, void *dst, size_t len);
|
||||
|
||||
/**
|
||||
* Write raw data to the fcb flash sector.
|
||||
*
|
||||
* @param[in] fcb FCB instance structure.
|
||||
* @param[in] sector FCB sector.
|
||||
* @param[in] off Write offset form sector begin.
|
||||
* @param[out] src Source buffer.
|
||||
* @param[in] len Read-out size.
|
||||
*
|
||||
* @return 0 on success, negative errno code on fail.
|
||||
*/
|
||||
int fcb_flash_write(const struct fcb *fcb, const struct flash_sector *sector,
|
||||
off_t off, const void *src, size_t len);
|
||||
|
||||
/**
|
||||
* @}
|
||||
*/
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue