uhOpenGame (function)

uhOpenGame, uhCloseGame
uhReadGame, uhWriteGame
uhReadRamRom, uhWriteRamRom

Transfer data from the host to the game and vice versa

Syntax

#include <ultrahost.h> /* ultrahost.h */
int uhOpenGame(const char *device);

int uhReadGame(int fd, void *addr, int nbytes);
int uhWriteGame(int fd, void *addr, int nbytes);

int uhReadRamRom(int fd,void *ramrom_addr,void *local_addr,int nbytes);
int uhWriteRamRom(int fd,void *ramrom_addr,void *local_addr,int nbytes);

int uhCloseGame(int fd);

* For information on PARTNER functions, see uhPatnerCmd.

Return Value

uhOpenGame

On success, uhOpenGame returns a valid file descriptor. Otherwise, it returns -1 and sets errno to indicate the error.

uhReadGame

It returns the number of bytes the function successfully read.

uhWriteGame

On success, it returns the number of bytes the function successfully wrote. Otherwise, it returns -1 and sets errno to indicate the error.

uhReadRamrom

On success, it returns zero. Otherwise, it returns -1 and sets errno to indicate the error.

uhWriteRamrom

On success, it returns zero. Otherwise, it returns -1 and sets errno to indicate the error.

uhCloseGame

On success, it returns zero. Otherwise, it returns -1 and sets errno to indicate the error.

Description

The host-to-target IO routines allow a host application to set up a communications channel for the transfer of raw data between the host and the game. They work in concert with OS routines on the game side. (For information on other routines called from the game, please see osReadHost.)

The uhOpenGame routine performs initialization that allows communication events to be received by the specified device("/dev/u64_data","PARTNER-N64"). It returns a handler that enables the device to be operated. If the device is successfully opened, the handler returned by uhOpenGame is passed to uhReadGame, uhWriteGame, uhReadRamrom, uhWriteRamrom, and uhCloseGame

The uhReadGame routine attempts to read nbytes of data from the RDRAM on game side and copy it to the memory region beginning at addr. The uhWriteGame routine sends nbytes of data from the host beginning at addr to the osReadHost function on game side. Please make sure to match the number of bytes to be transferred between the pairing functions that include osReadHost and uhWriteGame, and osWriteHost and uhReadGame for accurate synchronization.

When the procedures for both functions are called, the corresponding instructions on game side will be executed, and the originating process will be blocked until the transfer ends.

If the uhReadGame has been executed, the process on the host side will be blocked until the osWriteHost gets executed on the game side. Conversely, if the osReadHost has been executed on the game side, the thread on the game side will be blocked until the WriteGame gets executed on the host side.

The uhReadRamrom routine attempts to copy nbytes of data from the 64 cartridge ROM emulation memory (it is called ramrom memory on development board), beginning at ramrom_add to local_addr on the host side.

uhWriteRamrom routine attempts to copy nbytes of data from local_addr on the host side to ramrom_addr.

The uhCloseGame procedure can be used if desired to close the given file descriptor.

These routines are provided by the NINTENDO 64 host communication library (e.g., libultrahost.a). Using them requires a makefile entry that links these libraries (e.g.,-lultrahost).

When using PARTNER, PARTNER must have been started when the host application is executed.

Example

The following is an example of using uh functions for the development cassette.
(An example of their use with PARTNER is in uhPartnerCmd)

        main(int argc, char **argv) /* Host side code */
          {
                  pid_t pid;
                  int fd, status;
                  if ((fd = uhOpenGame("/dev/u64_data")) == -1) {
                          perror("uhOpenGame");
                          return(-1);
                  }
                  if ((pid = fork()) == -1) {
                          perror("fork");
                          return(-1);
                  } else if (pid == 0) {
                          (void)execl("/usr/sbin/gload", "/usr/sbin/gload", 0);
                          fprintf(stderr, "host: execl(\"gload\") failed\n");
                          return(-1);
                  }
                  if (uhReadGame(fd, hostBuffer, 4) == -1) {
                          fprintf(stderr, "uhReadGame %s\n", sys_errlist[errno]);
                          return(1);
                  }
                  if (uhCloseGame(fd) != 0) {
                          perror("uhCloseGame");
                          return(-1);
                  }
                  if (waitpid(pid, &status, WUNTRACED) == -1) {
                          perror("waitpid");
                          return(-1);
                  }
          }

        mainproc(void *arg) /* Game side code */
          {
                  osWriteHost(gameBuffer, 4);
                  osExit();
          }

See Also

osReadHost, osWriteHost, uhPartnerCmd, and uhGLoad

Revision History

1999/04/30 Changed format