/***************************************************************************
 *     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: flash data store abstraction
 *
 * Revision History:
 *
 * $brcm_Log: $
 * 
 *
 ***************************************************************************/

#if !defined(__BFDS_H__)
#define __BFDS_H__

/* Flash store handle */
typedef struct bfds_state * bfds_handle;

typedef struct bfds_properties {
    unsigned flash_sector_size; /* size of minimum erasable block */
    unsigned flash_page_size;   /* size of maximum writable block */
    unsigned flash_total_size;   /* size of flash */
} bfds_properties;

#define BFDS_OK 0
#define BFDS_ERROR 1

/***************************************************************************
Summary:
	Open block device.

Description:
	Open block device for reading and writing.

Returns:
	BFDS_OK or BFDS_ERROR on failure.

See Also:
	bfds_close()

****************************************************************************/
int bfds_open (
                bfds_handle * handle  /* [out] return device handle */
              );

/***************************************************************************
Summary:
	Close block device.

Description:
	Close block device and release resources.

Returns:
	BFDS_OK or BFDS_ERROR on failure.

See Also:
	bfds_open()

****************************************************************************/
int bfds_close(
				bfds_handle handle  /* [in] device handle */
			   );

/***************************************************************************
Summary:
	Read from device at offset.

Description:
	Read from device at offset, copying data into the buffer provided.

Returns:
	BFDS_OK or BFDS_ERROR on failure.

See Also:
	bfds_open()

****************************************************************************/
int bfds_read(
			bfds_handle handle,   /* [in] device handle */
			unsigned offset,      /* [in] offset in bytes */
			void * data,          /* [out] buffer to copy data into at offset */
			unsigned size         /* [in] size of the buffer */
			);
/***************************************************************************
Summary:
	Erase the sector/block at offset.

Description:
	Erase the sector/block at offset.

Returns:
	BFDS_OK or BFDS_ERROR on failure.

See Also:
	bfds_open(), bfds_page_program()

****************************************************************************/
int bfds_sector_erase(
						bfds_handle handle,   /* [in] device handle */
						unsigned offset       /* [in] offset in bytes */
						);
/***************************************************************************
Summary:
	Program the sector/block at offset.

Description:
	Program the sector/block at offset with the contents of the buffer provided in data.
	Normaly for flash devices bfds_sector_erase should be called prior to any programming.

Returns:
	BFDS_OK or BFDS_ERROR on failure.

See Also:
	bfds_open(), bfds_sector_erase()

****************************************************************************/
int bfds_page_program(
						bfds_handle handle,   /* [in] device handle */
						unsigned offset,      /* [in] offset in bytes */
						void * data,          /* [in] buffer to program at offset */
						unsigned size         /* [in] size of the buffer */
						);
/***************************************************************************
Summary:
    Retrieve parameters of flash device.

Description:
    Retrieve parameters of flash device such as sector and page sizes.

Returns:
    BFDS_OK or BFDS_ERROR on failure.

See Also:
    bfds_open()

****************************************************************************/
int bfds_get_properties (
    bfds_handle handle,   /* [in] device handle */
    bfds_properties * properties /* [out] details of flash device */
    );

#endif