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

## uhWriteGame

Syntax

    #include <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
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.

The uhReadGame routine attempts to read nbytes of data from the game and copy it to the memory region beginning at addr. For correct operation, it should be paired from the game side with a osWriteHost with exactly the same number of bytes. The uhWriteGame routine attempts to copy nbytes of data from the host beginning at addr to the game.

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();
              }

See Also
uhCloseGame
uhReadGame
uhReadRamrom
uhWriteRamrom
osReadHost
osWriteHost
osTestHost
osAckRamromRead
osAckRamromWrite

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