.TH osReadHost 3P local "Silicon Graphics, Inc."
.SH NAME
.upperok
osReadHost, osWriteHost, osTestHost, osAckRamromRead, osAckRamromWrite \- transfer data from/to host and DRAM
.SH SYNOPSIS
.nf
\f3
.Op c
#include <ultra64.h>
.sp .8v
void osReadHost(void *vAddr, s32 nbytes);
.sp .8v
void osWriteHost(void *vAddr, s32 nbytes);
.sp .8v
void osAckRamromRead(void);
.sp .8v
void osAckRamromWrite(void);
.SH NO LONGER SUPPORTED
.nf
\f3
.Op c
s32 osTestHost(void);
.sp .8v
.Op
\f1
.fi
.SH DESCRIPTION
These routines allow the game to transfer data back and forth from a
host application. 
They work with the routines described in
.IR uhOpenGame (3P)
on the host side.
.PP
The
.I osReadGame
routine will set up the game side connection to accept
.I nbytes
of data from the host and copy it to DRAM beginning at the address
.IR vAddr .
For correct synchronization,
it should be paired from the game side with a
.I uhWriteGame
with
.I exactly
the same number of bytes.
If the read is attempted from the game side before the host has executed
the write,
the game thread will block.
Conversely,
if the write is attempted from the host side before the game has executed
a read,
the host process 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 osWriteHost
routine will attempt to copy
.I nbytes
of data from the game beginning at
.I vAddr
to the host.
In this case,
the operation should be paired on the host side with a
.I uhReadGame
procedure with the same byte count.
As above,
either the host or game will block until the rendezvous is complete.
.PP
The DRAM virtual address
.I vAddr
should be 8 byte (64 bit) aligned.
Due to a host restriction,
the transfer size
.I nbytes
should be a multiple of 4.
In addition,
it is required that
.I rmon
be running to manage the low level synchronization.
.PP
The
.I osTestHost
is no longer supported.
.PP
The
.I osAckRamromRead
and
.I osAckRamromWrite
routines are used in conjunction with
.I uhReadRamrom
and 
.I uhWriteRamrom
Under the current release, they are not needed, however dummy stubs 
remain in the library for backwards compatibility.
.PP
See
.IR uhOpenGame (3P)
for an example on how to correctly initiate and use a connection from
the host.