/******************************************************/
/* Copyright (C) 2008 Arch Rock Corporation 2008      */
/* License Agreement: refer to LICENSE.txt            */
/*                                                    */
/******************************************************/

#ifndef _FLASH_H
#define _FLASH_H    1

/*! A system call to provide random write access to the 
 *  on-chip flash as a non-volatile storage.
 *  
 *  \pre Do not call this inside the interrupt handler context.
 *       Caller must maintain its own flash address management to avoid
 *       overwriting previous data.  0 is the start address 
 *       of the flash abstraction.
 *  \post If successful, \em size number of bytes of \em frombuf
 *        is written into the flash starting at \em toaddr.
 *
 *  @param[in] frombuf pointer to the buffer to be written to flash
 *  @param[in] size size of the buffer in bytes
 *  @param[in] toaddr start address on the flash where content will be
 *             copied to
 *             
 *  \return 0 if succeed or -1 if fail and errno is set appropriately.
 *  \par Errors:
 *    EINVAL if invalid parameters are passed
 *  \par
 *    ESIZE  if size is too large
 */
int16_t flwrite(const void *frombuf, uint16_t size, uint16_t toaddr);

/*! A system call to provide random read access of the 
 *  on-chip flash as a non-volatile storage.
 *  
 *  \pre Do not call this inside the interrupt handler context.
 *       Caller must maintain its own flash address management to avoid
 *       reading unwanted data.  0 is the start address 
 *       of the flash abstraction.
 *  \post If successful, \em size number of bytes of \em fromaddr
 *        on the flash is written to \em tobuf.
 *
 *  @param[in] fromaddr address of the flash where data is read from
 *  @param[out] tobuf address of a the buffer where content will be
 *             copied to
 *  @param[in] size size of \em tobuf in bytes
 *             
 *  \return 0 if succeed or -1 if fail and errno is set appropriately.
 *  \par Errors:
 *    EINVAL if invalid parameters are passed
 *  \par 
 *    ESIZE  if size is too large
 */
int16_t flread(uint16_t fromaddr, void *tobuf, uint16_t size);

/*! A function call that returns the total size of the internal
 *  non-volatile storage in bytes that are available for application to use.
 *  
 *  \pre None.
 *  \post returns the total size of the internal non-voltagile storage in bytes
 *                that are available to applications.
 *             
 *  \return size of the internal non-voltagile storage in bytes
 */
uint16_t flsize();

#endif
