OSK5912 Flash Module

The FLASH module API provides functions to erase as well as read and write from the on-board Flash memory. Programming errors can be detected through use of a checksum function. The total size of Flash memory can be determined by the number of pages on each ob-board Flash memory module through use of the getTotalPages function.

The Flash memory is divided into logical pages which must be erased before being re-programmed. After being erased, locations within the page can be programmed in any order. However, each location can only be programmed once per erasure.

To optimize very large reads and writes to Flash memory, the readBurst() and writeBurst() functions can be used instead of read() & write().

Programs that use the FLASH API should include both the osk5912.h and the osk5912_flash.h BSL header files. The header file osk5912_flash.h contains several constants that may be useful while programming:

Description
Initialize the Flash memory, set the mode to read, and disable the Flash write protect. Must be called before using any other Flash function.

Required Headers
osk5912.h
osk5912_flash.h

Required Libraries
osk5912bsl.lib

Function Prototype
void OSK5912_FLASH_init( )

Parameters
None

Return Value
None

Example

    /* Initialize Flash to read mode 
     * with the Flash write protection disabled */
    OSK5912_FLASH_init( );

Description
A checksum is most commonly used check for programming errors in Flash. The checksum is the unsigned sum of all 8-bit bytes in a given memory range. If the sum is exceeds 0xFFFFFFFF it wraps around at 32-bits. The sum is returned as a single 32-bit value

Required Headers
osk5912.h
osk5912_flash.h

Required Libraries
osk5912bsl.lib

Function Prototype
Uint32 OSK5912_FLASH_checksum( Uint32 start, Uint32 length )

Parameters
start - Starting address of Flash memory
length - Length in bytes

Return Value
32-bit checksum that is generated by adding all the bytes in the Flash range

Example

    Uint32 checksum;

    /* Calculate the checksum for the first sector in Flash */
    checksum = OSK5912_FLASH_checksum( OSK5912_FLASH_BASE, 
                    OSK5912_FLASH_PAGESIZE );

Description
Erase a given range of memory in Flash. The erase function can only erase full pages of Flash memory, not an arbitrary length in Flash. Therefore the pages that encapsulate the given range are erased. Once the erase is complete, the values at Flash memory are all ‘ones’.

Required Headers
osk5912.h
osk5912_flash.h

Required Libraries
osk5912bsl.lib

Function Prototype
void OSK5912_FLASH_erase( Uint32 start, Uint32 length )

Parameters
start - Starting address of Flash to beginning erase
length - Minimum length of erase in bytes. Must be a non-zero number. Flash memory can only erase full pages.

Return Value
None

Example

    /* Erase the first page of Flash */
    OSK5912_FLASH_erase( OSK5912_FLASH_BASE, 
                         OSK5912_FLASH_PAGESIZE );

    /* This function has a similar effect  as the function call 
     * above.  Only full pages can be erased. */
    OSK5912_FLASH_erase( OSK5912_FLASH_BASE, 1 );

    /* Erase the entire contents of Flash in the first device */
    Uint32 pages = OSK5912_FLASH_getTotalPages( 1 );
    OSK5912_FLASH_erase( OSK5912_FLASH_BASE, pages * 
                         OSK5912_FLASH_PAGESIZE );

Description
Each Flash device has a Device ID & Manufacture ID. The total number of pages in a Flash device can be determined by reading these 2 IDs from each Flash device.

Required Headers
osk5912.h
osk5912_flash.h

Required Libraries
osk5912bsl.lib

Function Prototype
Uint32 OSK5912_FLASH_getTotalPages( Uint16 num_flash_device )

Parameters
num_flash_device - Number of physical Flash devices on the OSK5912( typically 1 device )

Return Value
Number of total pages in Flash memory

Example

    Uint32 pages, total_bytes_count;

    /* Get the total number of pages from the 2 Flash device 
     * on the OSK5912 */
    pages = OSK5912_FLASH_getTotalPages( 2 );

    /* To determine total bytes, take the page and multiply 
     * with OSK5912_FLASH_PAGESIZE */
    total_bytes_count = pages * OSK5912_FLASH_PAGESIZE;

Description
Read data from a range in Flash

Required Headers
osk5912.h
osk5912_flash.h

Required Libraries
osk5912bsl.lib

Function Prototype
void OSK5912_FLASH_read( Uint32 src, Uint32 dst, Uint32 length )

Parameters
src - Address of Flash memory to read from
dst - Address of non-Flash memory to write to
length - Length in bytes

Return Value
None

Example

    Uint8 buffer[256];

    /* Copy the first 256 8-bit bytes from the beginning of 
     * Flash Memory to buffer: Buffer must be type-cast to 
     * Uint32( unsigned 32-bit integer ) */
    OSK5912_FLASH_read( OSK5912_FLASH_BASE,(Uint32)buffer, 256 );

Description
Write data to a range in Flash. The range in Flash must be erased prior to writing.

Required Headers
osk5912.h
osk5912_flash.h

Required Libraries
osk5912bsl.lib

Function Prototype
void OSK5912_FLASH_write( Uint32 src, Uint32 dst, Uint32 length )

Parameters
src - Address of non-Flash memory to read from
dst - Address of Flash memory to write to
length - Length in bytes

Return Value
None

Example

    Uint8 buffer[256];
    Int16 i;
    for( i = 0 ; i < 256 ; i++ )
        buffer[i] = i;

    /* Write the memory pattern in 'buffer' 
     * to the first 256 bytes of Flash. */
    OSK5912_FLASH_write(OSK5912_FLASH_BASE,(Uint32)buffer, 256);

Description
Read data from a range in Flash. This function will use a faster approach to reading Flash memory.

Required Headers
osk5912.h
osk5912_flash.h

Required Libraries
osk5912bsl.lib

Function Prototype
void OSK5912_FLASH_readBurst( Uint32 src, Uint32 dst, Uint32 length )

Parameters
src - Address of Flash memory to read from
dst - Address of non-Flash memory to write to
length - Length in bytes

Return Value
None

Example

Uint8 buffer[256];

/* Copy the first 256 8-bit bytes from the beginning 
 * of Flash Memory to buffer: Buffer must be type-cast 
 * to Uint32( unsigned 32-bit  integer ). */

/* This is Functionally identical to OSK5912_FLASH_read(),
 * however it is more efficient at reading large bursts 
 * of data but not single entries. */
OSK5912_FLASH_readBurst(OSK5912_FLASH_BASE,(Uint32)buffer,256);

Description
Write data to a range in Flash. The range in Flash must be erased prior to writing. This function uses a buffer on the Flash device to speed up writes.

Required Headers
osk5912.h
osk5912_flash.h

Required Libraries
osk5912bsl.lib

Function Prototype
void OSK5912_FLASH_writeBurst( Uint32 src, Uint32 dst, Uint32 length )

Parameters
src - Address of non-Flash memory to read from
dst - Address of Flash memory to write to
length - Length in bytes

Return Value
None

Example

Uint8 buffer[256];
Int16 i;
for( i = 0 ; i < 256 ; i++ )
	buffer[i] = i;

/* Write the memory pattern in 'buffer' to the 
 * first 256 bytes of Flash.  Functionally this is identical 
 * to OSK5912_FLASH_write(), however it is more efficient at
 * writing large bursts of data but not single entries. */
OSK5912_FLASH_writeBurst(OSK5912_FLASH_BASE,(Uint32)buffer,256);