\ ****************************************************************************************
\ FILE NAME:  To_xFlash.4th
\ Kernel extension for supporting memory management and flash programming for the
\ Wildcard Carrier Board and QVGA Controller Board
\ Copyright 2002-2003 Mosaic Industries, Inc.  All rights reserved.
\ ---------------------------------------------------------------------
\ DATE:        2003 - Jule 08
\ VERSION:     1.3
\ SUPPORTED HARDWARE:
\       QED-4 (FLASH) Board
\       QVGA Controller Board
\       WildCard Carrier Board
\ ---------------------------------------------------------------------
\ Please see the Wildcard Carrier Board User Guide for detailed instructions.
\
\ These are the User Functions defined by this driver:
\   To_xFlash      ( xsource_addr\xdestination_addr\numbytes -- success )
\   Query_xMemory  ( page -- device.size&type )
\   Is_xRAM        ( page -- flag )
\   Is_xFlash      ( page -- flag )
\   Page_To_xFlash ( source.page -- )
\   Download_Map_QVGA ( -- )
\   Download_Map_WCB  ( -- )
\   Standard_Map_QVGA ( -- )
\   Standard_Map_WCB  ( -- )
\
\ To_xFlash allows writes to the extra flash chip on the WCB, the QVGA Controller,
\ and/or the kernel flash chip. This function has the same behavior as To_Flash
\ (see its glossary entry in the QED-FLASH update notice), but uses the ID of the
\ flash device to determine how to perform the write.
\
\ Query_xMemory determines the size and type of an extra memory device. The value
\ returned is a signed integer of the size in kilobytes. The sign represents the
\ device type, a positive size for RAM, and negative for flash. A value of zero
\ means either no device resides at the base page, or a flash chip is installed with
\ either an unknown ID, or is write protected.
\ Two notes on Query_xMemory:
\   The base page of the device must equal the bitwise-AND of the page and 0xF0.
\   Zero is returned if the base is zero
\
\ Is_xRAM and Is_xFlash return true is the given page resides on the coorepsonding
\ memory device. Note, these functions are wrappers for Query_xMemory.
\
\ Page_To_xFlash is the To_xFlash replacement for PAGE.TO.FLASH. It is aware of the
\ RAM and flash devices available for the WCB and QVGA Controller, and provides
\ download friendly error reporting.
\ Note, it relies on Is_xRAM and Is_xFlash for parameter checking
\
\ Note, the above functions use the same buffer areas as the kernel routines
\ that they supercede (ie To.Flash and Page.To.Flash).
\ (buffers are located in the top half of onchip RAM from 0xB200-0xB3E0).
\ These routines are not re-entrant with respect to multitasking.
\ This means that a multitasking application cannot support simultaneous
\ flash programming by separate tasks unless a resource variable is defined
\ and GET and RELEASE are used.
\
\ Download_Map_QVGA, Download_Map_WCB, Standard_Map_QVGA, Standard_Map_WCB provide a
\ simple way to set the memory map of a board while clearly stating what is being done.
\
\       Standard Map        Download Map
\       RAM     Flash       RAM     Flash
\ QED   01-03   04-06       04-06   01-03
\ WCB   40-4F   50-5F       50-5F   40-4F
\ QVGA  60-6F   70-7F       70-7F   60-6F
\
\ NOTE: The memory map of the QED Board is maintained across power cycles and resets,
\   but is cleared by a factory cleanup. However, the WCB and QVGA, revert to standard
\   map at powerup, but maintain their state across resets or factory cleanups.
\
\ The above functions should provide simple means to compile code for storage in the
\ flash devices of the QED Board, the Wildcard Carrier Board, or the QVGA Controller.
\
\ Top Level C Functions:
\   int To_xFlash ( xaddr source, xaddr destination, uint numbytes )
\   int Query_xMemory ( int page )
\   bool Is_xRAM ( int page )
\   bool Is_xFlash ( int page )
\   void Page_To_xFlash ( int source_page )
\   void Download_Map_QVGA ( void )
\   void Download_Map_WCB ( void )
\   void Standard_Map_QVGA ( void )
\   void Standard_Map_WCB ( void )
\
\ ---------------------------------------------------------------------
\ Disclaimer: THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT
\             ANY WARRANTIES OR REPRESENTATIONS EXPRESS OR IMPLIED,
\             INCLUDING, BUT NOT LIMITED TO, ANY IMPLIED WARRANTIES
\             OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
\
\ *********************************************************************
