source: svn/trunk/newcon3bcm2_21bu/dta/src/bfdb/bfdb.h @ 2

/***************************************************************************
 *     Copyright (c) 2003-2010, Broadcom Corporation
 *     All Rights Reserved
 *     Confidential Property of Broadcom Corporation
 *
 *  THIS SOFTWARE MAY ONLY BE USED SUBJECT TO AN EXECUTED SOFTWARE LICENSE
 *  AGREEMENT  BETWEEN THE USER AND BROADCOM.  YOU HAVE NO RIGHT TO USE OR
 *  EXPLOIT THIS MATERIAL EXCEPT SUBJECT TO THE TERMS OF SUCH AN AGREEMENT.
 *
 * $brcm_Workfile: $
 * $brcm_Revision: $
 * $brcm_Date: $
 *
 * Module Description: simple log structured flash database
 *
 * Revision History:
 *
 * $brcm_Log: $
 * 
 *
 ***************************************************************************/
#if !defined(__BFDB_H__)
#define __BFDB_H__

/**
   Database consists of tuples with each tuple containing up to 256 bytes of
   data. Each tuple is identified with ID which can be anything from 1 to 0xfd.
   ID 0 is reserved for erased tuple, ID 0xff idicates empty flash and ID 0xfe
   is reserved for house keeping data. Database is very simple, cursor based.
   To operate on any record caller must first position the cursor on the record
   and then perform desired operation.
   
   To position cursor on any given record:
   1. Position cursor to the beginning of the database by calling 
   bfdb_rewind .
   2. Call bfdb_next to advance cursor to the next record with given ID.
   
   Database records can be accessed by:
   1. Positioning cursor to the desired record
   2. Calling bfdb_get to retreive record pointed by cursor.
   
   Database record can be deleted by:
   1. Positioning cursor on the desired record
   2. Calling bfdb_delete to mark record as deleted.

   Database record can be added by:
   1. Calling bfdb_add with record ID and record data.

   Since the data base is designed operate with flash there is no way to modify
   a record. Caller must add new record and erase old one to achieve the same
   effect.
   
   In case of database corruption or code lockup due to database structure, 
   content of database must be dumped in to a file for analisys. To dump 
   content use gdb "dump" command:
   dump binary memory flash.raw <start address> <end address>
   flash.raw is the name of the file and can be changes as desired
   <start address> is the starting address of the database and for 1MB flash 
   where last 64K are occupied by database it is calculated as following:
   0xbec00000 + 0x100000 - 0x10000
   <end address> is the end address of the database and for the same conditions
   as above is calculated as following:
   0xbec00000 + 0x100000
   Direct calculations can be used on gdb input line since gdb will understand
   and process these expressions.
 */

#include "bfds.h"

typedef int bfdb_err;

#define BFDB_OK 0
#define BFDB_INVALID_PARAMETER 1
#define BFDB_STORE_ERROR 2
#define BFDB_RECORD_NOT_FOUND 3
#define BFDB_INTERNAL_ERROR 4
#define BFDB_LOG_ERROR 5
#define BFDB_LOG_FULL 6
#define BFDB_ALREADY_COMPACT 7

/* Reserved database ids */
#define BFDB_TUPLE_ERASED 0x0
#define BFDB_TUPLE_BLANK 0xff
#define BFDB_TUPLE_LOG 0xfe

/* Maximum size of tuple allowed */
#define BFDB_DATA_MAX 0xff

/* Record structure */
struct bfdb_tuple {
        uint8_t id;
        uint8_t size;
        uint8_t data[2];
} __attribute__((packed));

/**
   bfdb_settings structure defines configuration of database and memory 
   allocated to the database. There are some restrictions on memory -
   db_offset must be aligned on sector_size
   db_size must be aligned on sector_sise so the database fits in whole
   number of sectors.
   page_size is dependent on flash part and can be obtained from datasheet
   sector_size is also dependent on flash part.
  */
struct bfdb_settings {
        uint32_t page_size;                     /* size of writeable page */
        uint32_t sector_size;           /* size of minimal eraseable sector */
        uint32_t db_offset;                     /* starting offset of the database in flash */
        uint32_t db_size;                       /* size of flash allocated to the database */
};

typedef struct bfdb_state * bfdb_handle;

/**
   Private structure for use by internal functions.
   fl_start - offset of first byte of flash allocated to db
   fl_end - offset of fiirst free byte of flash after db
   db_head - offset off start of database log.
   db_tail - offset off first free byte where the next write should start.
 */
struct bfdb_state {
        uint32_t magic;
        uint32_t page_size;
        uint32_t sector_size;
        uint32_t fl_start;
        uint32_t fl_end;
        uint32_t db_head;
        uint32_t db_tail;
        bfds_handle store;
        uint8_t * page_buffer;
        uint8_t * page_buffer2;
        uint32_t pb_size;
        uint32_t cursor;
        uint32_t sector_sum32;
};

/***************************************************************************
Summary:
 Open database and initialize in memory data structures.
Description:
 Database will be positioned on the first valid record;
Input:
Output:
Returns:
SeeAlso:
None
***************************************************************************/
bfdb_err bfdb_open(struct bfdb_settings * settings, bfdb_handle * handle);

/***************************************************************************
Summary:
 Move database cursor to the first record with given id in the database.
Description:
 Function will move cursor to the first record in the database, then it will
 advance one record at the time until it finds first valid record with 
 specified id. If no record with desired id is found function will return an
 error.
Input:
Output:
Returns:
SeeAlso:
None
***************************************************************************/
bfdb_err bfdb_rewind(bfdb_handle handle, uint8_t id);

/***************************************************************************
Summary:
 Move database cursor to the next record with given id in the database. 
Description:
 Function will move cursor from current record to the next record with
 the specified id. If no record with such id is found function will return
 an error.
Input:
Output:
Returns:
SeeAlso:
None
***************************************************************************/
bfdb_err bfdb_next(bfdb_handle handle, uint8_t id);

/***************************************************************************
Summary:
 Get data from the database record pointed by the cursor.
Description:
 Function will read specified amount of data from record that is pointed by
 the cursor. Data will be placed in to memory pointed by given pointer. No
 more data than is specified by the size will be copied. If specified size
 is larger than amount of data in the record only data from the record will
 be copied.
Input:
Output:
Returns:
SeeAlso:
None
***************************************************************************/
bfdb_err bfdb_get(bfdb_handle handle, uint8_t * data, size_t size);

/***************************************************************************
Summary:
 Add record to the end of the database.
Description:
 Function will add a record to the end of the database. The record will have
 specified id and will contain data of given size pointed by given pointer.
 If provided size is larger than single record can contain, call will return
 an error. Depending on state of database buffers, data may be commited to
 flash. To make certain that data is commited caller should use bfdb_commit
 call. Normally data will be commited when database page buffer will become
 full to increase flash performace by combining smaller writes.
Input:
Output:
Returns:
SeeAlso:
None
***************************************************************************/
bfdb_err bfdb_add(bfdb_handle handle, uint8_t id, uint8_t * data, size_t size);

/***************************************************************************
Summary:
 Delete record pointed by the cursor.
Description:
 The record pointed by the cursor is marked as deleted. It will not come up
 during the record iteration. The record data will still be present and 
 the occupied space will be reclaimed later.
Input:
Output:
Returns:
SeeAlso:
None
***************************************************************************/
bfdb_err bfdb_delete(bfdb_handle handle);

/***************************************************************************
Summary:
 Compact database.
Description:
 bfdb_compact will move valid data from the first sector to the end of the
 database and after all of the data moved out it will erase empty sector.
 Head of the log will advance in to the next sector.
Input:
Output:
Returns:
SeeAlso:
None
***************************************************************************/
bfdb_err bfdb_compact(bfdb_handle handle);

/***************************************************************************
Summary:
 Erase database.
Description:
 bfdb_erase will completely erase flash store for the database, setting all
 bytes in the store to 0xff. Only sectors that are within the database 
 boundaries will be erased. This is completely destructive operation.
 This call should only be used if database is corrupted.
Input:
Output:
Returns:
SeeAlso:
None
***************************************************************************/
bfdb_err bfdb_erase(bfdb_handle handle);

#endif