.TH osPiStartDma 3P local "Silicon Graphics, Inc."
.SH NAME
.upperok
osPiStartDma, osPiWriteIo, osPiReadIo, osCreatePiManager, osPiGetCmdQueue \- managed address to the parallel interface (PI)
.SH SYNOPSIS
.nf
\f3
.Op c
#include <ultra64.h>
.sp .8v
s32 osPiStartDma(OSIoMesg \(**mb, s32 priority, s32 direction,
		u32 devAddr, void \(**vAddr, u32 nbytes, OSMesgQueue \(**mq);
.sp .8v
void osCreatePiManager(OSPri pri, OSMesgQueue \(**cmdQ, OSMesg \(**cmdBuf, 
		s32 cmdMsgCnt);
.sp .8v
OSMesgQueue \(**osPiGetCmdQueue(void);
.sp .8v
s32 osPiWriteIo(u32 devAddr, u32 data);
.sp .8v
s32 osPiReadIo(u32 devAddr, u32 \(**data);
.Op
\f1
.fi
.SH DESCRIPTION
The parallel interface (PI) is responsible for the transport of data between
RDRAM and bulk-storage devices (BSD) which could be ROM, RAM, CDROM, and other
technologies.
These functions listed above provide "managed" control of the PI,
which provide synchronization and mutual exclusion support
when the parallel interface is to be shared for simple peripheral I/O.
The use of these PI routines require that the operating system be correctly
initialized.
.PP
The
.I osPiStartDma
routine sets up a DMA transfer between RDRAM
and PI device address space by sending
an I/O message block request 
.I mb
to the PI manager. The caller specifies various parameters to be included in
the request block such as 
.I direction, 
device address
.I devAddr, 
RDRAM address
.I vAddr, nbytes
of transfer, and message queue 
.I mq
to receive the notification from PI manager once the I/O operation has 
completed. If the requested 
.I priority 
is OS_MESG_PRI_HIGH (default is OS_MESG_PRI_NORMAL), 
.I osPiStartDma 
jams the message to the front of PI manager's command queue; otherwise,
it simply appends the message to the end of the queue. If the PI manager has
not been started, 
.I osPiStartDma 
returns -1. Otherwise, it returns the status of either 
.I osSendMesg(3P) 
or 
.I osJamMesg(3P).
The length count
.I nbytes
contains the number of bytes to transfer (up to 16 Mbytes) and must be a
multiple of 2 bytes.
The PI device address
.I devAddr
must be 2-byte aligned.
The RDRAM virtual address
.I vAddr
must be 8-byte aligned,
but for OS_READ DMA operations, a stricter alignment is recommended.
See
.IR OS_DCACHE_ROUNDUP_ADDR (3P)
for a description of the problems that may result when transfers
are not an integral number of cache lines.
.PP
.I osCreatePiManager
creates and starts the PI manager system thread to provide mutual exclusion
and synchronization support for the PI devices. The caller specifies the 
priority 
.I pri
at which the PI manager will run and the command message queue 
.I cmdQ
where the PI manager will accept its request messages.
Together,
.I cmdBuf
and 
.I cmdMsgCnt
specify the message buffer and its number of entries needed by the command 
message queue.
.I osPiGetCmdQueue
simply returns a pointer to the command queue of the PI manager or NULL if
PI manager has not been started.
.PP
The
.I osPiWriteIo
routine performs a 32-bit programmed IO write to the PI device address
.I devAddr.
Similarly,
.I osPiRawReadIo
performs a 32-bit programmed IO read from the PI device address
.I devAddr
and returns the value in
.I data.
.SH NOTES
It is strongly recommended that the high-level functions (i.e., 
.I osCreatePiManager, osPiWriteIo, osPiReadIo, 
and 
.I osPiStartDma) 
be used to access PI. Caution must be exercised when intermixing 
low (raw) and high level PI functions. Without proper synchronization, 
this type of usage might cause an error in the PI
since PI can only support one I/O 
operation at any one time. 
.SH SEE ALSO
.IR osPiRawStartDma (3P),
.IR osSendMesg (3P),
.IR osJamMesg (3P)