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.