/* * File: flash.h * * This is an interface to a utility which allows the caller to read and * write to non-volatile flash memory. This is an abstraction of generic * flash and the functionality presented by this interface is independent * of the actual device utilized. The module which is implemented to expose * this generic interface will handle the specifics of the physical flash * components utilized. * * See Also *   flash_intel.c   -- An implementation exposing a flash.h interface. *   flash_toshiba.c -- An implementation exposing a flash.h interface. * * Copyright (C) 2002 RidgeRun, Inc. * Author: RidgeRun, Inc  <skranz@ridgerun.com> * *  This program is free software; you can redistribute  it and/or modify it *  under  the terms of  the GNU General  Public License as published by the *  Free Software Foundation;  either version 2 of the  License, or (at your *  option) any later version. * *  THIS  SOFTWARE  IS  PROVIDED  ``AS  IS''  AND   ANY  EXPRESS  OR IMPLIED *  WARRANTIES,   INCLUDING, BUT NOT  LIMITED  TO, THE IMPLIED WARRANTIES OF *  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN *  NO  EVENT  SHALL   THE AUTHOR  BE    LIABLE FOR ANY   DIRECT,  INDIRECT, *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT *  NOT LIMITED   TO, PROCUREMENT OF  SUBSTITUTE GOODS  OR SERVICES; LOSS OF *  USE, DATA,  OR PROFITS; OR  BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON *  ANY THEORY OF LIABILITY, WHETHER IN  CONTRACT, STRICT LIABILITY, OR TORT *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF *  THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * *  You should have received a copy of the  GNU General Public License along *  with this program; if not, write  to the Free Software Foundation, Inc., *  675 Mass Ave, Cambridge, MA 02139, USA. * * Please report all bugs/problems to the author or <support@dsplinux.net> * * key: RRGPLCR (do not remove) * */#ifndef FLASH_H#define FLASH_H#include "memconfig.h"/* Common Flash Interface - see www.amd/com/products/nvd/overview/cfi.html */#define CFI_START_ADDR 0x10#define CFI_END_ADDR 0x4Ftypedef unsigned char (*GetByteCallBack_t)(void);typedef void (*GetValAtAddrCallBack_t)(unsigned short *vaddr, unsigned short *val);typedef void (*PutValAtAddrCallBack_t)(unsigned short *vaddr, unsigned short val);#ifdef BSPCONF_BTLDR_MEMMAP_DEBUGextern int read_device_codes(unsigned long *Code);extern int read_cfi_array(unsigned short array[], int array_size);extern int build_sector_map(unsigned int sector_map[], int sector_map_size);#endifextern void flash_read(unsigned int offset,   // Of flash.                       unsigned short *dest,  // Destination buffer                       unsigned int num_bytes,                       PutValAtAddrCallBack_t CBack); // NULL okay  // --flash_read--   //   Think of the flash part as starting at address  //   zero (the first read/writable location in the flash  //   device). The specified dest buffer is filled with flash  //   data found starting at the specified flash memory range  //   offset. Unless num_bytes == 0, a minimum of 2 bytes  //   will always be read into the supplied buffer. If  //   a CBack is supplied then it will be used to write the  //   the 16bit flash values, otherwise the supplied *dest  //   buffers is written to.  extern int flash_write(unsigned int offset,    // Of flash.                        unsigned short *src,    // source buffer.                        unsigned int num_bytes,                        GetValAtAddrCallBack_t CBack); // NULL okay  // --flash_write--   //   The src pointer indicates the start of the data block  //   which is to be copied to the flash memory range starting  //   at the specified offset. Note: unless num_bytes == 0, a  //   minimum of 2 bytes is always written. If a CBack is  //   supplied then it will be use to acquire each 16bit val  //   which is to be written to flash, otherwise the supplied  //   *src buffer is used for the copy.  //   Returns zero on success and non-zero on flash write failureextern int flash_flush(void);  // --flash_flush--  //   Similiar to the `fflush()` of standard Linux.  //   Use this after you have completed your set of  //   flash_write() calls to insure that any internally  //   buffered data has been written to flash.  //   returns -1 on success, otherwise returns the flash  //   offset for which a write error occured.extern void flash_erase(void);  // --flash_erase--  //   Erases the board's entire flash range.extern void flash_erase_range(int start_addr, int end_addr);  // --flash_erase_range--  //   Erases the indicated portion of the flash.  //   Note: the whole block containing the start_addr as well as  //   the whole block containing the end_addr, and all blocks  //   in-between, are erased. Keep this in mind when forming  //   your range request -- if not careful you will get more  //   erased than your range defines due to the erase constraints  //   of flash chips. They can only erase whole blocks.  //   +--- NOTE! ----  //   |  *revisit-skranz* This routine is an intermediate solution.  //   |  How does the client know which addresses fall on which  //   |  flash blocks without knowing the details of the underlying  //   |  flash chips used? Unfortunatley, at the moment, they will  //   |  just have to know. And in fact the areas of the flash map  //   |  which have been choosen to hold the various components  //   |  (bootloader, params, kernel, filesystem) have been defined  //   |  in the comp_flash_info[] array of btldr_pi.c in a way that  //   |  places them convieniently on flash block boundaries that  //   |  allow each component to be erased without effecting the  //   |  surrounding components. There is a coupling here that we  //   |  hope to remove in the future since ideally the client  //   |  shouldn't need to know anything about the underlying chips.  //   +--------------extern int flash_init(void);  // --flash_init--  //   Called once at bootloader init to initialize the module and make  //   it ready for client use.  //   +--- NOTE! ----  //   |  *revisit-skranz* At the moment this function has a return value  //   |  indicating to the caller the type of chips located on the  //   |  board so that the client can later make the correct type of  //   |  calls to the flash_erase_range() routine (see comments above).  //   |  Again, this exists only as part of the intermediate solution.  //   |  There is a coupling here that we hope to remove in the future. The  //   |  client shouldn't need to know anything about the underlying chips.  //   |  Current valid return values are: 128, 160, 320  //   +--------------#endif