/* * 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 * * 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 * * 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 0x4F typedef 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_DEBUG extern 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); #endif extern 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 failure extern 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
