.TH uhOpenGame 3P local "Silicon Graphics, Inc."
.SH NAME
.upperok
uhOpenGame, uhCloseGame, uhReadGame, uhWriteGame, uhReadRamrom, uhWriteRamrom  \- data transfer facilities from/to host and game
.SH SYNOPSIS
.nf
\f3
.Op c
#include <ultrahost.h>
.sp .8v
int uhOpenGame(const char *device);
.sp .8v
int uhReadGame(int fd, void *addr, int nbytes);
.sp .8v
int uhWriteGame(int fd, void *addr, int nbytes);
.sp .8v
int uhReadRamrom(int fd, void *ramrom_addr, void *data, int nbytes);
.sp .8v
int uhWriteRamrom(int fd, void *ramrom_addr, void *data, int nbytes);
.sp .8v
int uhCloseGame(int fd);
.Op
\f1
.fi
.SH DESCRIPTION
These 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 the routines described in
.IR osReadHost (3P)
on the game side.
.PP
The
.I uhOpenGame
routine opens the given
.I device
special file and configures it to listen for game I/O events.
Which device should be opened is dependent on which read and write
calls will be needed. For
.I uhReadGame 
and
.I uhWriteGame, uhOpenGame
should open the device
.I /dev/u64_data.
For
.I uhReadRamrom
and 
.I uhWriteRamrom, uhOpenGame
should open
.I /dev/u64.
Note that this is a change from previous releases that specified 
.I /dev/u64 
for all calls.
The file descriptor returned by
.I uhOpenGame
is passed to
.IR uhReadGame ,
.IR uhWriteGame ,
.IR uhReadRamrom ,
.IR uhWriteRamrom ,
and
.IR uhCloseGame ,
presuming the open succeeds.
.PP
The
.I uhReadGame
routine will attempt to read
.I nbytes
of data from the game and copy it to the memory region beginning at
.IR addr .
For correct operation, it should be paired from the game side with a
.I osWriteHost
with
.I exactly
the same number of bytes.
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. When both sides have correctly made the 
corresponding procedure call, the transfer will take place and the 
blocking side will proceed.
.PP
The
.I uhWriteGame
routine will attempt to copy
.I nbytes
of data from the host beginning at
.I addr
to the game.
In this case,
the operation should be paired on the game side with a
.I osReadHost
procedure with the same byte count.
As above,
either the host or game will block until the rendezvous is complete.
.PP
The
.I uhReadRamrom
routine will attempt to copy
.I nbytes
of data from the ramrom memory, begining at 
.I ramrom_addr.
The calling program must supply a buffer,
.I data
big enough to hold the requested nbytes. 
In previous releases, calls to
.I uhReadRamrom
needed to be paired from the game side with a 
.I osAckRamromRead. This is no longer neccessary.
.PP
The
.I uhWriteRamrom
routine will attempt to write
.I nbytes
from 
.I data
to the ramrom memory, begining at
.I ramrom_addr.
In previous releases, calls to
.I uhWriteRamrom 
needed to be paired from the game side with a 
.I osAckRamromWrite. This is no longer neccessary.
.PP
The
.I uhCloseGame
procedure can be used if desired to close the given file descriptor.
.PP
These routines are part of the Ultra 64 host side library
.IR libultrahost.a ,
and thus are available to the application by adding
.I -lultrahost
on the link line.
.SH EXAMPLE
The example on the following page shows how a host application can
initiate the same and establish a connection to transfer data.
This particular sequence will guarantee that no handshaking events will
be lost.
By the time the game sends its first packet of data,
the host device driver is ready to acknowledge it.
Furthermore, the host side application does not attempt to send
data to the game before it has booted.
.bp
.ta 5
.Ex
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();
}
.Ee
.SH DIAGNOSTICS
.PP
.I uhOpenGame
On success, a valid file descriptor is returned.
Otherwise, a -1 is returned and errno is set to indicate the error.
.PP
.I uhReadGame
The number of bytes successfully read is returned.
.PP
.I uhWriteGame
On success, uhWriteGame returns the number of bytes actually written.
Otherwise, it returns -1 and sets errno to identify the error.
.PP
.I uhReadRamrom
On success, a value of 0 is returned.
Otherwise, a -1 is returned and errno is set to indicate the error.
.PP
.I uhWriteRamrom
On success, a value of 0 is returned. 
Otherwise, a -1 is returned and errno is set to indicate the error.
.PP
.I uhCloseGame
On success, a value of 0 is returned. 
Otherwise, a -1 is returned and errno is set to indicate the error.