N64® Functions Menu

al - Audio Library Functions
gDP - DP GBI Macros
gdSP - General GBI Macros
gSP - SP GBI Macros
gt - Turbo Microcode RDP
gu - Graphics Utilities
Math - Math Functions
nuSys - NuSystem
os - N64 Operating System
sp - Sprite Library Functions
uh - Host to Target IO
64DD - N64 Disk Drive

Nintendo® Confidential

## osPfsInitPak

Syntax

#include <ultra64.h>
s32 osPfsInitPak(OSMesgQueue *mq, OSPfs *pfs, int controller_no);
Explanation
Initializes the OSPfs structure pfs, which is the file handle used to operate the Controller Pak. This function should be called first when a Controller Pak is used for the first time, a new Controller Pak is inserted, or to access different Controller Paks inserted in multiple controllers. However, because configuration must be performed to use SI, osContInit should be called once at the start, before osPfsInitPak is called.
When controlling a file system, a Controller Pak function uses the OSPfs structure pointed to by the pfs argument as a file handle to gain access. This function (osPfsInitPak) initializes that OSPfs structure.
The controller_no argument specifies the Controller number (0~3) into which the Controller Pak is inserted.
The mq argument is the initialized message queue linked to OS_EVENT_SI. Please refer to osSetEventMesg for creation of this link. Because mq is used by the function as an internal message queue, it is not necessary for the application to use mq for purposes such as queuing function-termination messages.

osPfsInitPak performs the following kinds of processing internally. First it checks the disk ID area. If it recognizes the ID, it calls the function osPfsChecker. This enables recovery to be performed automatically if the file managment area (FAT area) is destroyed.

Although the previous Pfs initialization function, osPfsInit, performed automatic recovery if the ID area was completely destroyed, osPfsInitPak does not perform automatic restoration. (osPfsInitPak confirms ID integrity internally by checksum comparison. If the checksums do not agree, the ID is evaluated as corrupt.) ID recover requires a separate call to function osPfsRepairId. Normally when initializing the Controller Pak, the function osPfsInitPak should be used rather than osPfsInit. In addition, be sure to integrate osPfsRepairId into the program so that it can be called. This is necessary because certain addresses could become indeterminate due to a poor connection at the connector or for other reasons. If you use osPfsInit, the function could go to the wrong address, although it was supposed to check the ID. Looking at the data at the wrong address, the function could determine that it is not an ID. In this case, the old osPfsInit function assigns a new ID automatically and it could write the new ID to the wrong address. As a result, the content of the Controller Pak may be destroyed.

Therefore, always use the following procedure when initializing a Controller Pak.
Procedure for Initializing a Controller Pak
To initialize a Controller Pak, always call osPfsInitPak. If 0 is returned, the call is successful.

If PFS_ERR_ID_FATAL is returned as the error code, one of the following problems may exist:

- The Controller Pak's ID area is destroyed.
- The Controller Pak is not connected properly.
- The Controller Pak ID cannot be read due to a dirty connector.
- The Controller's joy bus or Controller Pak is damaged.

In this case, you must display the message, "The Controller or Controller Pak may not be inserted properly, the content may have been destroyed, or it may be damaged." Then prompt the user to choose between "connect again" or "repair it - the content of the Controller Pak may be destroyed."
If the user chooses "connect again," call the osPfsInitPak function again. If the user chooses "repair," call the osPfsRepairId function, and then call osPfsInitPak again.
Possible Error Conditions
When an error occurs, one of the following error conditions is returned:

- PFS_ERR_NOPACK - Some type of PIF error has occurred. Either the Controller Pak is not inserted into the specified Controller or the Controller is not properly connected. To determine which is the case, use osContStartQuery or osContGetQuery function.
- PFS_ERR_NEW_PACK - A different Controller Pak has been inserted. To use the inserted Controller Pak, initialize it by calling this function (osPfsInitPak) again.
- PFS_ERR_CONTRFAIL - Data transfer to or from the Controller has failed. If a transfer error occurs, up to three tries will be done internally, so this error rarely occurs. If it does occur, it is possible that either the Controller is not connected properly, or the Controller Pak or Controller Socket is damaged.
- PFS_ERR_ID_FATAL - An attempt was made to initialize the file system, but the ID area was corrupt. Either the Controller Pak data were corrupted or the controller itself is malfunctioning or not properly connected. When this error is returned, the user should first be asked whether the Controller Pak should be initialized (assign a new ID) or to check the Controller Pak connection. If the user responds that the Controller Pak should be initialized, the function osPfsRepairId should be called.
- PFS_ERR_DEVICE - A peripheral device other than a Controller Pak (eg, Rumble Pak, 64GB Pak) has been inserted in the controller. Whether a Controller Pak has been inserted is determined by whether the device has RAM. This error is issued if there is no RAM present.

Example

    void
    mainproc(void) {
      int            i;
      OSMesgQueue    intMesgQueue;
      OSMesg         intMesgBuf[1];
      OSContStatus   contstat[MAXCONTROLLERS];
      OSPfs          pfs[MAXCONTROLLERS];
      u8             contpat;

      osCreateMesgQueue(&intMesgQueue, intMesgBuf, 1);
      osSetEventMesg(OS_EVENT_SI, &intMesgQueue, NULL);
      osContInit(&intMessageQ, &contpat, contstat);

      for (i = 0  ; i < MAXCONTROLLERS ; i ++) {
        if ((contpat >> i) & 1) {
          if ((contstat[i].type & CONT_TYPE_MASK) == CONT_TYPE_NORMAL) {
             do {
               ret = osPfsInitPak(&intMessageQ, &pfs[i], i);

               switch(ret) {
               case 0:
                 osSyncPrintf("Controller Pak is inserted into PORT %d\n", i);
                 break;
               case PFS_ERR_NOPACK:
                 osSyncPrintf("Controller Pak is not inserted into PORT %d\n", i);
                 osSyncPrintf("Insert Controller Pak\n");
                 break;
               case PFS_ERR_NEW_PACK:
                 osSyncPrintf("Controller Pak for PORT %d was replaced\n", i);
                 osSyncPrintf("This Controoler Pak will be used.\n");
                 break;
               case PFS_ERR_CONTRFAIL:
                 osSyncPrintf("Abnormality is found in connection of Controller Pak for PORT %d\n", i);
                 osSyncPrintf("Check if Controller is inserted properly\n");
                 break;
               case PFS_ERR_DEVICE:
                 osSyncPrintf("It cannot be saved in Controller Pak for PORT %d\n", i);
                 osSyncPrintf("Check if Controller Pakis inserted properly\n");
                 break;
               case PFS_ERR_ID_FATAL:
                 osSyncPrintf("Abnormality is found in Controller Pak for PORT %d\n", i);
                 osSyncPrintf("   A button..try to recover\n");
                 osSyncPrintf("Other buttons, re-insert\n");
                if (AskQuestion(i) == A_BUTTON) {
                   osPfsRepairId(&pfs[i]);
                 }
                 break;
               }
               WaitForPushingAnyButton(i);
             } while (ret != 0) ;
          } else {
              osSyncPrintf("PORT %d is not a normal Controller\n", i);
          }
        } else {
          osSyncPrintf("Controller is not inserted into PORT %d\n", i);
        }
      }
    }

See Also
osPfsRepairId
osContInit
osPfsAllocateFile
osPfsChecker
osPfsDeleteFile
osPfsFileState
osPfsFindFile
osPfsFreeBlocks
osPfsIsPlug
osPfsReadWriteFile
osPfsSetLabel

Revision History
2/1/1999 Revised entirely

Nintendo® Confidential Warning: all information in this document is confidential and covered by a non-disclosure agreement. You are responsible for keeping this information confidential and protected. Nintendo will vigorously enforce this responsibility.
Copyright © 1998
Nintendo of America Inc. All rights reserved
Nintendo and N64 are registered trademarks of Nintendo
Last updated March 1998