diff --git a/include/fs/fcb.h b/include/fs/fcb.h index a897779eb71..3ffa133c8f5 100644 --- a/include/fs/fcb.h +++ b/include/fs/fcb.h @@ -21,50 +21,106 @@ extern "C" { #include -#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 + *

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