N64 Functions Reference (HTML Manual Pages) Function Page

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

Format
#include <ultra64.h>
s32 osPfsInitPak(OSMesgQueue *mq, OSPfs *pfs, int controller_no);

What This Function Does
It initializes the Controller Pak's file handle. In other words, it initializes the OSPfs structure pointed to by the pfs argument, which is the file handle for a Controller Pak. Call this function when dealing with the Controller Pak for the first time or when the Controller Pak is initially inserted.

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. The message queue (mq) should not be shared, because osPfsInitPak blocks on the message queue (mq). Also, osContInit must be called first, before calling osPfsInitPak to initialize the synchronization at the low level.

Internal Processing
The osPfsInitPak function first checks the status and ID area by calling the osPfsChecker function. When the ID is recognized, it checks to see if the file management area is destroyed.

Note that the osPfsInit function automatically performs a repair when the ID area is destroyed completely. However, osPfsInitPak does not perform a repair operation automatically. To repair the ID, you must call osPfsRepairId . Use osPfsInitPak instead of osPfsInit for initializing a Controller Pak. Also, always use osPfsInitPak with osPfsRepairId.

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 - Although initialization of the file system has been attempted, the ID area was destroyed. The Controller Pak is not connected, it is damaged, or a peripheral device without SRAM is inserted. When this error is returned, follow the initialization procedure outlined previously on this page.
PFS_ERR_DEVICE - During the initialization of the file system, the device ID at page 0 of the ID area was not the Controller Pak's device ID. Something other than a Controller Pak is inserted into the Controller.

Note
There is a difference between PFS_ERR_ID_FATAL and PFS_ERR_DEVICE. When initializing with osPfsInitPak, the ID management area is checked first. If the function call discovers that the ID management area was destroyed, PFS_ERR_ID_FATAL is returned. If the ID management area was not destroyed, the device ID in the ID management area is checked. If no bit is found in the device ID to show that it is the Controller Pak, PFS_ERR_DEVICE is returned.

Using the Rumble Pak
There is no ID management area in a Rumble Pak, so PFS_ID_FATAL is returned for a Rumble Pak.

Example Code

void
mainproc(void) {
  int i;
  u8 contpat;
  OSContStatus contstat[MAXCONTROLLERS];
  OSPfs pfs[MAXCONTROLLERS];

  osContInit(&n_siMessageQ,
    &contpat, contstat);
  for (i = 0  ;
    i < MAXCONTROLLERS ; i ++) {
    if ((contpat >> i) & 1) {
      if ((contstat[i].type &
        CONT_JOYPORT) != 0 &&
        (contstat[i].type &
        CONT_ABSOLUTE) != 0) {
        do {
          ret = osPfsInitPak(
          &n_siMessageQ, &pfs[i], i);
          switch(ret) {
          case 0:
             osSyncPrintf(
"There is a Controller Pak on
 PORT %d\n", i);
             break;
          case PFS_ERR_NOPACK:
             osSyncPrintf(
"No Controller Pak on PORT %d\n", i);
             osSyncPrintf(
"Please connect the Controller Pak\n");
             break;
          case PFS_ERR_NEW_PACK:
             osSyncPrintf(
"The Controller Pak on PORT %d
 has been swapped\n", i);
             osSyncPrintf(
"This Controller Pak will be used\n");
             break;
          case PFS_ERR_CONTRFAIL:
             osSyncPrintf(
"There is a Controller connection
 problem on PORT %d\n", i);
             osSyncPrintf(
"Please make sure that the
 Controller is connected properly\n");
             break;
          case PFS_ERR_DEVICE:
             osSyncPrintf(
"No data can be saved in the
 Controller Pak on PORT %d\n", i);
             osSyncPrintf(
"Please make sure that the
 Controller Pak is connected properly\n");
             break;
          case PFS_ERR_ID_FATAL:
             osSyncPrintf(
"There is a problem with the
 Controller Pak on PORT %d\n", i);
             osSyncPrintf(
"A Button     ... Try to fix it\n");
             osSyncPrintf(
"Other Button ... I will
 re-connect the Controller Pak\n");
          if (AskQuestion(i) == A_BUTTON) {
             osPfsRepairId(&pfs[i]);
             }
             break;
          }
          WaitForPushingAnyButton(i);
        } while (ret != 0) ;
      } else {
          osSyncPrintf(
"The device on PORT %d is not
 a normal Controller\n", i);
      }
    } else {
      osSyncPrintf(
"No Controller on PORT %d\n", i);
    }
  }

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 January 1998