Nintendo64 CONTROLLER PAK
I. Goals
1. The intended use of CONTROLLER PAK is to save and restore game state.
Maximum performance is not critical.
2. The file system need to allow users to switch RAM Packs while playing.
II. Overview
CONTROLLER PAK has the following features.
1. There are two types of CONTROLLER PAK (32k Bytes and 128k Bytes) now,
so we made the format of CONTROLLER PAK deal with up to 128k.
2. Each access to CONTROLLER PAK is 32 bytes with CRC checking.
3. CONTROLLER PAK is divided into pages (one page = 256bytes);
files will be divided into several pages and saved separately.
4. Each applications may have several files in one CONTROLLER PAK.
5. The number of files that can be saved in one CONTROLLER PAK is
specified in ID area. We can support 16 files or even larger file
system.
6. A file system checker which can fix the corrupted file system
on the fly is provided.
III. Data structure of CONTROLLER PAK
3.1 Whole structure
Backup memory is divided into four areas as follows:
+------------+ -------
| | ^
page 0 | | | ID area 1 page
| | v
+------------+ -------
| | ^
1 | | | INODE area 1 page
| | v
+------------+ -------
| | ^
2 | | | INODE mirror area 1page
| | v
+------------+ -------
| | ^
3 | | |
| | |
+------------+ | DIR area dir_size pages
| | |
: : |
: : |
| | v
+------------+ -------
| | ^
dir_size +3 | | |
| | |
+------------+ | DATA area
| | | 126-dir_size pages (32k)
| | | 254-dir_size pages (64k)
: : :
: : :
: : :
: : :
| | |
+------------+ |
| | |
127(if 32k ) | | |
255(if 64k ) | | v
+------------+ -------
ID area: has the CONTROLLER PAK identifier, etc.
DIR area: has the information about each file
INODE area: describes how the pages link
INODE mirror area: copy of INODE area
DATA area: has the file data itself
The structure of the whole pack file system is defined as follows:
typedef struct {
int status;
OSMesgQueue *queue;
int channel;
u8 id[32];
u8 backup_id[32];
u8 label[32];
int pack_size;
int version;
int dir_size;
int inode_start_page;
} OSPfs;
3.2 ID area
The details of ID area is as follows:
Offset +-------------------------+ ---
+00-+1F | | System reserved
+-------------------------+ ---
+20-+3F | | Serial No.(include pack size)
+-------------------------+ ---
+40-+5F | | System reserved
+-------------------------+ ---
+60-+7F | | Serial No.(include pack size)
+-------------------------+ ---
+80-+9F | | Serial No.(include pack size)
+-------------------------+ ---
+A0-+BF | | System reserved
+-------------------------+ ---
+C0-+DF | | Serial No.(include pack size)
+-------------------------+ ---
+E0-+FF | | Symbolic label
+-------------------------+ ---
Serial No.: Serial number of the pack formatted in Nintendo factory.
There are no CONTROLLER PAKs that have the same serial
numbers. If this number is illegal (and the
following backup number is also illegal), that
pack must not be used.
Backup of serial No.: This is for sudden destruction of serial No. part.
Serial Number block format:
+0 +8 +F
------------------------------------------------------------------
| | |
| serial # (High) | serial # (Mid) |
| | |
------------------------------------------------------------------
| | | | | | |
| serial # (Low) |Device |Mem |Ver| 16bit | 16bit|
| | ID |size| |checksum|~check|
------------------------------------------------------------------
Serial Number block format after repaired:
+0 +8 +F
------------------------------------------------------------------
| | | |
| 0xFFFFFFFF | Random # | serial # (Mid) |
| | | |
------------------------------------------------------------------
| | | | | | |
| serial # (Low) |Device |Mem |Ver| 16bit | 16bit|
| | ID |size| |checksum|~check|
------------------------------------------------------------------
typedef struct {
u32 repaired;
u32 random;
u64 serial_mid;
u64 serial_low;
u16 deviceid;
u8 memory_size;
u8 version;
u16 checksum;
u16 inverted_checksum;
} __OSPackId;
3.3 DIR area
This area has the information about each file. System allocates
32bytes for each file. Since we reserve two pages (512 bytes) for this
area, up to 16 files can exist in a CONTROLLER PAK.
The structure of each file is as follows:
typedef struct {
u16 company_code;
u16 game_code;
u8 start_page;
u8 status;
u16 data_sum;
char ext_name[PFS_FILE_EXT_LEN];
char game_name[PFS_FILE_NAME_LEN];
s32 reserved;
} __OSDir;
NOTE: 1. There is no check-sum for each OSDir structure because
there is CRC checking for each 32-bytes-transition.
3.4 INODE area
This area indicates how the pages link. The data in each address
of this area is a kind of code and this code indicates the status of
the corresponding page (e.g., the data in +20 bytes from the beginning
of INODE area indicates the status of page 20). The meanings of the
codes are as follows:
PFS_EOF (01) The file ends at that page.
PFS_PAGE_NOT_EXIST (02) Memory doesn't exist in that page.
PFS_PAGE_NOT_USED (03) This page is not allocated for any file.
04-FF The file continues to the page
indicated by that number.
The following example shows the way a certain file saved in backup
memory at a certain time.
DIR area of the file INODE area
offset| |
+----------+
+77 | 03 | This page is not used.
Start page +----------+
+------+ +78 | 03 | This page is not used
| 7A | +----------+
+------+ +79 | 03 | This page is not used.
| +----------+
+-------------->+7A | 7B |-------+ This page continues to
+----------+ | page 7B.
+7B | 7C |<------+
| |-------+
+----------+ |
+7C | 7D |<------+
| |-------+
+----------+ |
+7D | 7E |<------+
| |-------+
+----------+ |
+7E | 7F |<------+
| |-------+
+----------+ |
+7F | 01 |<------+ The file ends at this
| | page.
+----------+
+80 | 02 |-+
| | | If the CONTROLLER PAK is
+----------+ | 32Kbytes type, there is no
+81 | 02 | | memory corresponding with
| | | these address.
From this example, one can see that this CONTROLLER PAK is 32kbytes
type, this file occupies six pages (pages 7A-7F), and pages
77 to 79 aren't used at that time.
Since pages 0-3 are used by system, the corresponding addresses
in INODE area (+0 to +3 bytes from the beginning of page 3) isn't
needed. So our system uses these four bytes as the check sum of page
3 (INODE area), etc.
typedef struct {
u8 inode_page[PFS_INODE_SIZE];
} __OSInode;
inode_page[0] is used to save check-sum which can be used to detect
for file system corruption.
IV. Interface Functions
4.1. Error codes returned from functions:
PFS_ERR_NOPACK: No CONTROLLER PAK is plugged in. Apps can
just return.
PFS_ERR_ID_FATAL: dead CONTROLLER PAK is plugged in.
Apps can just return.
PFS_ERR_DEVICE: wrong device type is plugged in.
Apps can just return.
PFS_ERR_NEW_PACK: CONTROLLER PAK has been changed to a
different one.
Apps need to call osPfsInit() to initialize
the new CONTROLLER PAK.
PFS_ERR_INCONSISTENT: File system is corrupted. Apps need to call
osPfsChecker() to fix the file system.
PFS_ERR_CONTRFAIL: Crc error or controller failure. Apps should
retry one more time.
PFS_ERR_INVALID: Invalid parameter or the specified file does
not exist. Apps should change parameter and
then retry.
PFS_DIR_FULL: Directory is full, no new files can be created. Apps should ask users to
change to a new pack or loop through all the
files to let users delete files before
allocating a new file.
PFS_DATA_FULL: No free pages on ram pack. No old files can
grow and no new files can be created.
Apps should ask users to
change to a new pack or loop through all the
files to let users delete files before
allocating a new file.
PFS_ERR_BAD_DATA: The data read from pack are bad. Apps should
just ignore the data.
PFS_ERR_EXIST The specified file which will be created exists
4.2. Open file system:Set up file system for the new plugged-in CONTROLLER PAK
s32
osPfsInit(OSMesgQueue *queue, OSPfs *pfs, int channel)
{
/* Check integrity of file system -- call osPfschecker() */
/* Check valid id */
/* marked file system as initialized */
}
Error codes returned: PFS_ERR_NOPACK, PFS_ERR_ID_FATAL,
PFS_ERR_DEVICE, PFS_ERR_CONTRFAIL.
4.3. Allocate a file: We do not allow to grow a file on a write. Apps
should declare pages needed on allocation time.
s32
osPfsAllocateFile(OSPfs *pfs, u16 company_code, u16 game_code,
u8 *game_name, u8 *ext_name, int file_size_in_bytes,
s32 *file_number)
{
/* Check valid ID and parameters */
/* Allocate a file */
/* If the file exists, return the file number */
/*
* If the file doesn't exist and file_size is not zero,
* preallocate a file and declare file pages. The file
* number is returned.
*/
}
Error codes returned: PFS_ERR_NOPACK, PFS_ERR_NEW_PACK,
PFS_ERR_INCONSISTENT, PFS_ERR_CONTRFAIL,
PFS_ERR_INVALID, PFS_DATA_FULL,
PFS_DIR_FULL, PFS_ERR_EXIST.
4.4. Delete a file
s32
osPfsDeleteFile(OSPfs *pfs, u16 company_code, u16 game_code,
u8 *game_name, u8 *ext_name)
{
/* Check valid ID and parameters */
/* get dir structure */
/* release pages */
/* update dir and inode structures */
}
Error codes returned: PFS_ERR_NOPACK, PFS_ERR_NEW_PACK,
PFS_ERR_INCONSISTENT, PFS_ERR_CONTRFAIL,
PFS_ERR_INVALID.
4.5. Read/Write Data to file
s32
osPfsReadWriteFile(OSPfs *pfs, s32 file_no, u8 flag, int offset,
int size_in_bytes, u8 *data_buffer)
{
/* Check valid ID and parameters */
/* Get dir and inode structures */
/* seek to the specified offset */
/* read/write data from/to CONTROLLER PAK */
}
Error codes returned: PFS_ERR_NOPACK, PFS_ERR_NEW_PACK,
PFS_ERR_INCONSISTENT, PFS_ERR_CONTRFAIL,
PFS_ERR_INVALID, PFS_ERR_BAD_DATA.
4.6. Grow or truncate files:We do not allow to grow a file on a write.
Apps should declare pages needed on allocation
time or use osPfsReSizeFile() to grow/truncate
the specified file.
s32
osPfsReSizeFile(OSPfs *pfs, u16 company_code, u16 game_code,
u8 *game_name, u8 *ext_name, int new_file_size_in_bytes)
{
/* Check valid ID and parameters */
/*
* Fine the specified file. If the file doesn't exist,
* return PFS_ERR_INVALID
*/
/* get dir and inode structures */
/* get current file size */
/* If grow file, declear new pages */
/* If truncate file, release the unsed pages */
/* Write back inode structure */
}
4.7. Get file information
s32
osPfsFileState(OSPfs *pfs, s32 file_no, OSPfsState *state)
{
/*
* typedef struct {
* u32 file_size_in_bytes;
* u16 company_code;
* u16 game_code;
* char ext_name[PFS_FILE_EXT_LEN];
* char game_name[PFS_FILE_NAME_LEN];
* } OSPfsState;
*/
/* Check valid ID and parameters */
/* get dir and inode structures */
/* get file status and calculate file size */
}
Error codes returned: PFS_ERR_NOPACK, PFS_ERR_NEW_PACK,
PFS_ERR_INCONSISTENT, PFS_ERR_CONTRFAIL,
PFS_ERR_INVALID.
4.8. Search for a specified file
s32
osPfsFindFile(OSPfs *pfs, u16 company_code, u16 game_code,
u8 *game_name, u8 *ext_name, s32 *file_no)
{
/* Check valid ID and parameters */
/* loop through all files to search the specified
* file and then return file number
*/
}
Error codes returned: PFS_ERR_NOPACK, PFS_ERR_NEW_PACK,
PFS_ERR_CONTRFAIL, PFS_ERR_INVALID.
4.9. Check integegrity of file system
s32
osPfsChecker(OSPfs *pfs)
{
/* check status */
/*
* loop through all files to make sure that there are no
* file's start pages have been marked NOT_USED, no pages
* are allocated to two different files, no inode are infinite
* loop, all inodes need to be terminated by PFS_EOF .
*/
/*
* return all pages that are not in any file back
* to NOT_USED.
*/
}
Error codes returned: PFS_ERR_NOPACK, PFS_ERR_CONTRFAIL.
4.10. Re-initialize the CONTROLLER PAK in case of corruption.
/*
* This function reformat the whole file system except pack id
* which is assigned by Nintendo.
*/
s32
osReFormatPfs(OSMesgQueue *queue, int channel)
{
/* Check ID */
/* Find CONTROLLER PAK size */
/* make dir */
/* make inode */
}
Error codes returned: PFS_ERR_NOPACK, PFS_ERR_CONTRFAIL.
4.11. Set up symbolic label for CONTROLLER PAK
/*
* This function allows users to setup symbolic label which
* can be used for users to identify CONTROLLER PAK.
*/
s32
osPfsSetLabel(OSPfs *pfs, u8 *label)
{
/* Check ID */
/* Copy label to CONTROLLER PAK */
}
Error codes returned: PFS_ERR_NOPACK, PFS_ERR_CONTRFAIL.
4.12. Read symbolic label which is saved in CONTROLLER PAK
/*
* This function allows users to read symbolic label which
* can be used for users to identify CONTROLLER PAK.
*/
s32
osPfsGetLabel(OSPfs *pfs, u8 *label, int *len)
{
/* Check ID */
/* Copy label to specified data array and return length
* of label back to len
*/
}
Error codes returned: PFS_ERR_NOPACK, PFS_ERR_CONTRFAIL.
4.13. Check to see if CONTROLLER PAK is plugged or not
/*
* This function returns a bit pattern to indicate which memory
* packs are plugged in
*/
s32
osPfsIsPlug(OSMesgQueue *queue, u8 *pattern)
{
/* Set up request command format for all channels */
/* trigger pifmacro */
/* reformat the 64 bytes RAM data and save in data array */
/* loop through data array to check error bits */
}
Error codes returned: None
4.14. Return number of free space in bytes
s32
osPfsFreeBlocks(OSPfs *pfs, s32 *bytes_not_used)
{
/* Check ID */
/* loop through inode table to find all the
* free bloacks
*/
}
Error codes returned: PFS_ERR_NOPACK, PFS_ERR_CONTRFAIL.
4.15. Return the number of max files are allowed on the CONTROLLER PAK and
the number of files exist on CONTROLLER PAK
s32
osPfsNumFiles(OSPfs *pfs, s32 *max_files, s32 *files_used)
{
/* Check ID */
/* loop through directory table to calculate
* the total number of files exist.
*/
}
Error codes returned: PFS_ERR_NOPACK, PFS_ERR_CONTRFAIL.
4.16. Notes for developers
1. In order to achieve the second goal to allow users to switch
RAM Packs while playing, no dir structures, inode structures or
data should be cached on memory.
2. Since each interface function requires some SI DMAs which
are slow, the threads that are calling thses functions should
be low priority threads.
V. Example
mainproc(void *arg)
{
osCreateMesgQueue(&pifMesgQueue, pifMesgBuf, NUM_MESSAGE);
osSetEventMesg(OS_EVENT_SI, &pifMesgQueue, dummyMessage);
osContInit(&pifMesgQueue, &p, &sdata[0]);
for (i = 0; i < MAXCONTROLLERS; i++) {
if (p & (1<<i)){
cont_no = i;
break;
}
}
ret = osPfsInit(&pifMesgQueue, &pfs0, cont_no);
if (ret == PFS_ERR_NOPACK)
osExit();
while(1) {
osContStartReadData(&pifMesgQueue);
osRecvMesg(&pifMesgQueue, NULL, OS_MESG_BLOCK);
osContGetReadData(&rdata[0]);
button = rdata[cont_no].button;
if (button & CONT_A) {
ret = osPfsFindFile(&pfs0, state1.company_code,
state1.game_code, state1.game_name, state1.ext_name, &no);
if (ret == 0) {
ret = osPfsReadWriteFile(&pfs0, no, PFS_READ,
0, state1.file_size, backup_buffer);
if (ret == 0) {
draw_puts(" read success");
}
else {
err_handlaer(ret, &pfs0);
}
}
}
else if (button & CONT_B) {
ret = osPfsFindFile(&pfs0, state1.company_code,
state1.game_code, state1.game_name, state1.ext_name, &no);
if (ret == 0) {
ret = osPfsReadWriteFile(&pfs0, no, PFS_WRITE,
0, state1.file_size, backup_buffer);
if (ret != 0) {
err_handlaer(ret, &pfs0);
}
else {
draw_puts("write file success");
}
}
}
else if (button & CONT_C) {
for(i = 0 ; i < (int)(256*dsize[data_no]) ;i++)
backup_buffer[i] = data_no;
ret = osPfsAllocateFile(&pfs0, c_code[data_no], g_code[data_no],
gname[data_no], ename[data_no],
256*dsize[data_no], &no);
if (ret == 0) {
ret = osPfsReadWriteFile(&pfs0, no, PFS_WRITE,
0, 256*dsize[data_no], backup_buffer);
if (ret != 0) {
draw_puts("create file failure");
} else {
draw_puts("create file success");
}
} else {
if (ret == PFS_ERR_FULL) {
draw_puts("file system full");
} else {
draw_puts("create file failure");
}
}
} else if (button & CONT_D) {
ret = osPfsDeleteFile(&pfs0, state1.company_code,
state1.game_code, state1.game_name, state1.ext_name);
if (ret != 0) {
draw_puts("delete file failure");
} else {
draw_puts("delete file success");
}
} else if (button & CONT_E) {
ret = osPfsChecker(&pfs0);
if (ret != 0) {
err_handlaer(ret, &pfs0);
} else {
draw_puts("check file system success");
}
} else if (button & CONT_F) {
ret = osPfsReFormat(&pifMesgQueue, cont_no);
if (ret != 0) {
draw_puts("check file system failure");
} else {
err_handlaer(ret, &pfs0);
}
}
for(i = 0 ; i < NUM_OF_FILE ; i++) {
ret = osPfsFileState(&pfs0, i, &state);
if (ret == 0) {
s = state.game_name;
for(j = 0; j < PFS_FILE_NAME_LEN ; j++)
draw_char( *s++ );
s = state.ext_name;
for(j = 0; j < PFS_FILE_EXT_LEN ; j++)
draw_char( *s++ );
draw_uint(state.file_size);
} else
err_handlaer(ret, &pfs0);
}
}
osExit();
}
err_handlaer(int error, OSPfs *pfs)
{
switch(error) {
case PFS_ERR_NEW_PACK:
osPfsInit(pfs->queue, pfs, pfs->channel);
break;
case PFS_ERR_INCONSISTENT:
osPfsChecker(&pfs0);
break;
default:
break;
}
return(0);
}
VI. TODO list
1. Provide program or format for Nintendo factory to format
ram pack.
| Name |
Last commit
|
History
|
Last Update |
|---|---|---|
| .. | ||
| CVS | ||
| GNUmakefile | ||
| Makefile | ||
| PCmake | ||
| README | ||
| asci.c | ||
| cfb.c | ||
| eep_test.c | ||
| main.c | ||
| ncode.h | ||
| nu64sys.c | ||
| spec | ||
| textlib.c | ||
| textlib.h | ||
| thread.h |