uhReadGame

Syntax

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

For information on PARTNER functions, see uhPatnerCmd.

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

Explanation
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 (e.g., "/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.

When both sides have correctly made the corresponding procedure call, the transfer will take place and the blocking side will proceed.

If the read is attempted from the host side before the game has executed the write, the host process will block. Conversely, if the write is attempted from the game side before the host has executed a read, the game thread will block.

The uhReadRamrom routine attempts to copy nbytes of data from the ramrom memory, beginning at ramrom_addr.

The uhWriteRamrom routine attempts to write nbytes from data to the ramrom memory beginning at 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();
          }