28.2 Flash Library

The following functions are available for use with 1M Flash.

28.2.1 Initialization Functions

osFlashAllErase - Deletes the entire area of Flash

Syntax

#include <ultra64.h>
s32  osFlashAllErase(void);

Description

This is a function that deletes the entire data of 1M Flash.

For a return value, 0 is returned when sucessful and -1 when failed. As the entire area is deleted at one time, this function allows you to delete the entire area in high speed, rather than repeating the execution of osFlashSectorErase.

Timer wait is done inside of osFlashAllErase. Since timer management is done by VI manager, it is necessary to boot VI manager with osCreateViManager prior to the use of this function. It takes from several msec to several hundred msec to delete the entire area of data.

UP


28.2.2 Status Acquisition Function

Function Names
osFlashReadStatus - Acquires the Flash Status Syntax #include <ultra64.h>
void  osFlashReadStatus(u8 *flash_status);

Description

This is a function that reads the status of 1M Flash.

It returns status to argument "flash_status." Normally, it is not necessary for a game application to use this function.

UP


28.2.3 ID Acquisition Function

Function Names
osFlashReadId - Acquires the Flash ID

Syntax

#include <ultra64.h>
void  osFlashReadId(u32 *flash_type, u32 *flash_maker);

Description

This is a function that reads 1M Flash ID.

Argument "flash_type" returns the specification of 1M Flash currently used, and flash_maker returns each manufacturer number and the manufacturer's version number of 1M Flash currently used. Normally, it is not necessary for a game application to use this function.

UP


28.2.4 Status Clear Function

Function Names
osFlashClearStatus - Clears the Flash Status

Syntax

#include <ultra64.h>
void  osFlashClearStatus(void);

Description

This is a function that clears the status of 1M Flash.

Normally, it is not necessary for a game application to use this function.

UP


28.2.5 Entire Region Erase Function

Function Names
osFlashAllErase - Erases Entire Flash Region

Syntax

#include <ultra64.h>
s32  osFlashAllErase(void);

Description

This is a function that deletes the entire data of 1M Flash.

For a return value, 0 is returned when sucessful and -1 when failed. As the entire area is deleted at one time, this function allows you to delete the entire area in high speed, rather than repeating the execution of osFlashSectorErase.

Timer wait is done inside of osFlashAllErase. Since timer management is done by VI manager, it is necessary to boot VI manager with osCreateViManager prior to the use of this function. It takes from several msec to several hundred msec to delete the entire area of data.

UP


28.2.6 Entire Region Erase Function (No Status Check)

Function Names
osFlashAllEraseThrough - Erases the Entire Flash Region (No Status Check)

Syntax

#include <ultra64.h>
void  osFlashAllEraseThrough(void);

Description

This is a function that deletes the entire data of 1M Flash.

It is different from osFlashAllErase in not conducting status check when delete ends inside of osFlashAllEraseThrough.

The execution of osFlashAllEraseThrough is conducted immediately, however, it takes from several msec to several hundred msec to actually delete data.  Determine whether or not deleting data is ended by executing osFlashCheckEraseEnd.

Do not execute other osFlash functions between osFlashAllEraseThrough and osFlashCheckEraseEnd. The status of Flash may be changed when other osFlash functions are executed prior to the execution of osFlashCheckEraseEnd.

UP


28.2.7 Sector Erase Function

Function Names
osFlashSectorErase - Erases 1 Sector of Flash

Syntax

#include <ultra64.h>
s32  osFlashSectorErase(u32 page_num);

Description

This is a function that deletes the data of certain sectors of 1M Flash.

It specifies page number as an argument and deletes the sector which contains the specified page number.

The size of 1 sector is 128 pages (16K bytes), and each page of 0~0x7f, 0x80~0xff, 0x100~0x17f... is considered to be 1 sector.

For return values, 0 is returned when delete is successful and -1 when failed.

Timer wait is operated in osFlashSectorErase. Since timer management is done by VI manager, it is necessary to boot VI manager with osCreateViManager before using this function. It takes from several msec to several hundred msec to delete data of 1 sector.

UP


28.2.8 Sector Erase Function (No Status Check)

Function Names
osFlashSectorEraseThrough - Sector Erase Function (No Status Check)

Syntax
#include <ultra64.h>
void     osFlashSectorEraseThrough(u32 page_num);

Syntax

#include <ultra64.h>
void  osFlashSectorEraseThrough(u32 page_num);

Description

This is a function that deletes the data of certain sectors of 1M Flash.

It specifies page number as an argument and deletes the sector which contains the specified page number.

The size of 1 sector is 128 pages (16K bytes), and each page of 0~0x7f, 0x80~0xff, 0x100~0x17f... is considered to be 1 sector.

The difference between this function and osFlashSectorErase is that it does not conduct status check when delete ends in osFlashSectorEraseThrough.

Although the execution of osFlashSectorEraseThrough is done immediately, it takes several msec to several hundred msec to actually delete data.
Whether or not deletion of data has ended is determined by executing osFlashCheckEraseEnd.

Do not execute other osFlash functions between osFlashSectorEraseThrough and osFlashCheckEraseEnd.
This is because the status of Flash may be changed when other osFlash functions are executed prior to the execution of osFlashCheckEraseEnd.

UP


28.2.9 Erasure Verification Function

Function Names
osFlashCheckEraseEnd - Verifies Status after Flash Erasure

Syntax

#include <ultra64.h>
s32  osFlashCheckEraseEnd(void);

Description

This is a function that determines whether or not the execution of osFlashAllEraseThrough or osFlashSectorEraseThrough to 1M Flash has been sucessful.

As the return values for this function, FLASH_STATUS_ERASE_BUSY is returned when delete is being executed, FLASH_STATUS_ERASE_OK when delete is successful, and FLASH_STATUS_ERASE_ERROR when delete has failed.

UP


28.2.10 Buffer Write Function

Function Names
osFlashWriteBuffer - Writes the Flash Buffer

Syntax

#include <ultra64.h>
s32  osFlashWriteBuffer(OSIoMesg *mb, s32 priority, void *dramAddr, 
                                              OSMesgQueue *mq);

Description

This is a function that writes data into 1M Flash write buffer by DMA.

The arguments are Message request block (*mb), Request priority (priority), Buffer address (*dramAddr) and DMA end message queue (*mq) accordingly.

For return values, return -1 when PI manager is not executed.  If PI manager is executed, return the status of either osSendMesg or osJamMesg.

The use method is basically in the form in accordance with

s32 osPiStartDma(OSIoMesg *mb, s32 priority, s32 direction, u32 devAddr,
void *dramAddr, u32 size, OSMesgQueue *mq)
.

The following are the points different from osPiStartDma:

There is no argument "direction" (because it is exclusively for write).
There is no argument "devAddr" (because the buffer address of 1M Flash are fixed).
There is no argument "size" (because the size to be read is fixed at 128 bytes per page).

Follow the procedure listed below in order to write data in specific pages of 1M Flash:

(1) Delete data
(2) Transfer data from RDRAM to the write buffer in 1M Flash
(3) Transfer data from the write buffer to each page of 1M Flash

This function is used to operate (2) listed above.

UP


28.2.11 Page Write Function

Function Names
osFlashWriteArray - Writes to Flash Page

Syntax

#include <ultra64.h>
s32  osFlashWriteArray(u32 page_num);

Description

This is a function that writes data in each page of 1M Flash from 1M Flash write buffer.

It specifies page numbers as an argument.

For return values, 0 is returned when writing is successful and -1 when failed.

In order to write data in specific pages of 1M Flash, follow the procedure below:

(1) Delete data
(2) Transfer data from RDRAM to 1M Flash write buffer
(3) Transfer data from write buffer to each page of 1M Flash

This function is used to do the operation listed in (3).

Page 0x3fe and 0x3ff are reserved by Nintendo.  Please refrain from using the pages.

Timer wait is operated in osFlashWriteArray.  Since timer management is done by VI manager, it is necessary to boot VI manager with osCreateViManager before using this function.

UP


28.2.12 Page Read Function

Function Names
osFlashReadArray - Reads from the Flash Page

Syntax

#include <ultra64.h>
s32  osFlashReadArray(OSIoMesg *mb, s32 priority, u32 page_num,
                         void *dramAddr, u32 n_pages, OSMesgQueue *mq);

Description

This is a function that read data written in 1M Flash.

The arguments are Message request block (*mb), Request priority (priority), The page number where reading starts (page_num), Buffer address to be read, Buffer address to be read (*dramAddr), the number of pages read (n_pages) and DMA end receiving message queue (*mq) accordingly.

For the return values, return -1 when PI manager is not executed, otherwise return the status of either osSendMesg or osJamMesg.

The use method is basically in the form that is in accordance with s32 osPiStartDma(OSIoMesg *mb, s32 priority, s32 direction, u32 devAddr,void *dramAddr, u32 size, OSMesgQueue *mq).  The following are the points which differ from osPiStartDma.

*There is no argument "direction" (because it is exclusively for read)
*There is a reading page number " n_pages" instead of the argument "size"
*Instead of the argument "devAddr," the page number where reading starts " page_num" is the argument.

When one execution of DMA does not fit in each 32K byte unit of page 0x0~0xff, 0x100~0x1ff, 0x200~0x2ff and 0x300~0x3ff, DMA is divided multiple times and executed in the library.

UP


28.2.13 Flash Switching Function

Function Names
osFlashChange - Switches When More than One Flash is Used

Syntax

#include <ultra64.h>
void    osFlashChange(u32 flash_num);

Description

This is a function which switches the chips of 1M Flash used when using multiple 1M Flash ROMs.

Argument "flash_num" indicates the used Flash number.  You can specify the number from 0 to 3.  When using just one 1M Flash, specify 0.

When using two 1M Flash ROMs, execute osFlashChange(0) to use the first 1M Flash and osFlashChange(1) to use the second 1M Flash.

After switching the 1M Flash used, you can use each 1M Flash just as when one 1M Flash is used.

When using multiple 1M Flash ROMs, be sure to use the Flash ROMs of the same ID.

By switching multiple 1M Flash ROMs, it is possible to expand the recording area up to the maximum of 4M bits (by using four 1M Flash ROMs).

UP