fds.h

Go to the documentation of this file.

 
#ifndef FDS_H__
#define FDS_H__
 
#include <stdint.h>
#include <stdbool.h>
#include "sdk_errors.h"
#include "app_util_platform.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
 
#define FDS_FILE_ID_INVALID     (0xFFFF)
 
 
#define FDS_RECORD_KEY_DIRTY    (0x0000)
 
#define FDS_BOUND_NOT_SET (0)
 
 
enum
{
    FDS_SUCCESS = NRF_SUCCESS,  
    FDS_ERR_OPERATION_TIMEOUT,  
    FDS_ERR_NOT_INITIALIZED,    
    FDS_ERR_UNALIGNED_ADDR,     
    FDS_ERR_INVALID_ARG,        
    FDS_ERR_NULL_ARG,           
    FDS_ERR_NO_OPEN_RECORDS,    
    FDS_ERR_NO_SPACE_IN_FLASH,  
    FDS_ERR_NO_SPACE_IN_QUEUES, 
    FDS_ERR_RECORD_TOO_LARGE,   
    FDS_ERR_NOT_FOUND,          
    FDS_ERR_NO_PAGES,           
    FDS_ERR_USER_LIMIT_REACHED, 
    FDS_ERR_CRC_CHECK_FAILED,   
    FDS_ERR_BUSY,               
    FDS_ERR_INTERNAL,           
};
 
 
typedef struct
{
    uint16_t record_key;    
    uint16_t length_words;  
    uint16_t file_id;       
    uint16_t crc16;         
                            /* The CRC is calculated over the entire record as stored in flash,
                             * including the record metadata except the CRC field itself.
                             */
    uint32_t record_id;     
} fds_header_t;
 
 
typedef struct
{
    uint32_t         record_id;         
    uint32_t const * p_record;          
    uint16_t         gc_run_count;      
    bool             record_is_open;    
} fds_record_desc_t;
 
 
typedef struct
{
    fds_header_t const * p_header;  
    void         const * p_data;    
} fds_flash_record_t;
 
 
typedef struct
{
    uint16_t file_id;           
    uint16_t key;               
    struct
    {
        void     const * p_data;
        uint32_t         length_words;
    } data;
} fds_record_t;
 
 
typedef struct
{
    uint16_t page;           
    uint16_t length_words;   
} fds_reserve_token_t;
 
 
typedef struct
{
    uint32_t const * p_addr;
    uint16_t         page;
} fds_find_token_t;
 
 
typedef enum
{
    FDS_EVT_INIT,       
    FDS_EVT_WRITE,      
    FDS_EVT_UPDATE,     
    FDS_EVT_DEL_RECORD, 
    FDS_EVT_DEL_FILE,   
    FDS_EVT_GC          
} fds_evt_id_t;
 
 
ANON_UNIONS_ENABLE;
 
typedef struct
{
    fds_evt_id_t id;        
    ret_code_t   result;    
    union
    {
        struct
        {
            uint32_t record_id;
            uint16_t file_id;
            uint16_t record_key;
            bool     is_record_updated;
        } write; 
        struct
        {
            uint32_t record_id;
            uint16_t file_id;
            uint16_t record_key;
        } del; 
    };
} fds_evt_t;
 
ANON_UNIONS_DISABLE;
 
 
typedef struct
{
    uint16_t pages_available;   
    uint16_t open_records;      
    uint16_t valid_records;     
    uint16_t dirty_records;     
    uint16_t words_reserved;    
 
    uint16_t words_used;
 
    uint16_t largest_contig;
 
    uint16_t freeable_words;
 
    bool corruption;
} fds_stat_t;
 
 
typedef void (*fds_cb_t)(fds_evt_t const * p_evt);
 
 
ret_code_t fds_register(fds_cb_t cb);
 
 
ret_code_t fds_init(void);
 
 
ret_code_t fds_record_write(fds_record_desc_t       * p_desc,
                            fds_record_t      const * p_record);
 
 
ret_code_t fds_reserve(fds_reserve_token_t * p_token, uint16_t length_words);
 
 
ret_code_t fds_reserve_cancel(fds_reserve_token_t * p_token);
 
 
ret_code_t fds_record_write_reserved(fds_record_desc_t         * p_desc,
                                     fds_record_t        const * p_record,
                                     fds_reserve_token_t const * p_token);
 
 
ret_code_t fds_record_delete(fds_record_desc_t * p_desc);
 
 
ret_code_t fds_file_delete(uint16_t file_id);
 
 
ret_code_t fds_record_update(fds_record_desc_t       * p_desc,
                             fds_record_t      const * p_record);
 
 
ret_code_t fds_record_iterate(fds_record_desc_t * p_desc,
                              fds_find_token_t  * p_token);
 
 
ret_code_t fds_record_find(uint16_t            file_id,
                           uint16_t            record_key,
                           fds_record_desc_t * p_desc,
                           fds_find_token_t  * p_token);
 
 
ret_code_t fds_record_find_by_key(uint16_t            record_key,
                                  fds_record_desc_t * p_desc,
                                  fds_find_token_t  * p_token);
 
 
ret_code_t fds_record_find_in_file(uint16_t            file_id,
                                   fds_record_desc_t * p_desc,
                                   fds_find_token_t  * p_token);
 
 
ret_code_t fds_record_open(fds_record_desc_t  * p_desc,
                           fds_flash_record_t * p_flash_record);
 
 
ret_code_t fds_record_close(fds_record_desc_t * p_desc);
 
 
ret_code_t fds_gc(void);
 
 
ret_code_t fds_descriptor_from_rec_id(fds_record_desc_t * p_desc,
                                      uint32_t            record_id);
 
 
ret_code_t fds_record_id_from_desc(fds_record_desc_t const * p_desc,
                                   uint32_t                * p_record_id);
 
 
ret_code_t fds_stat(fds_stat_t * p_stat);
 
ret_code_t flash_bounds_set (const uint32_t start_addr, const uint32_t end_addr);
 
#ifdef __cplusplus
}
#endif
 
#endif // FDS_H__