.TH osAi 3P local "Silicon Graphics, Inc."
.SH NAME
.upperok
osAiGetStatus, osAiGetLength, osAiSetFrequency, osAiSetNextBuffer \-
interrogate and control the audio interface (AI)
.SH SYNOPSIS
.nf
\f3
.Op c
#include <ultra64.h>
.sp .8v
u32 osAiGetStatus(void);
.sp .8v
u32 osAiGetLength(void);
.sp .8v
s32 osAiSetFrequency(u32 frequency);
.sp .8v
s32 osAiSetNextBuffer(void *vaddr, u32 nbytes);
.Op
\f1
.fi
.SH DESCRIPTION
These routines provide basic control for the audio interface. 
.PP
.I osAiGetStatus
simply returns the hardware status of the audio interface.
In this 32-bit value,
only bits
.I AI_STATUS_FIFO_FULL
and 
.I AI_STATUS_DMA_BUSY
contain useful information. 
.I AI_STATUS_FIFO_FULL
is set when both audio DMA registers have been programmed.
.I AI_STATUS_DMA_BUSY
is set when DMA is in progress.
.PP
Based on the input requested 
.I frequency
(in Hz), 
.I osAiSetFrequency
calculates the correct values for the internal divisors and returns
the actual frequency generated by these divisors.
The requested frequency should fall between 3000 Hz and 368000 Hz on
NTSC systems,
or between 3050 Hz and 376000 Hz on PAL systems.
.PP
.I osAiSetNextBuffer
sets up the next DMA transfer from DRAM to the audio interface buffer.
.I vaddr 
points to the buffer in DRAM and 
.I nbytes 
specifies the number of bytes to transfer.
Note that the buffer address 
.I vaddr
must be 64-bit aligned and that 
.I nbytes 
must be a multiple of 8 bytes.
A maximum transfer size of 262144 bytes is supported.
If the interface is busy (i.e. 
.I AI_STATUS_FIFO_FULL
is set), 
.I osAiSetNextBuffer 
returns -1 and aborts the DMA operation.
.PP
.I osAiGetLength
simply returns the number of bytes remaining in the current DMA buffer.

.SH KNOWN BUGS
It is worth noting that a previous hardware bug has been fixed by a
software patch in osAiSetNextBuffer.  This bug occurred when the
address of the end of the buffer specified by osAiSetNextBuffer was
at a specific value.  This value occurred when 
.sp 8v
.B (vaddr + nbytes) & 0x00003FFF == 
.B 0x00002000
.PP
(when the end of the buffer is a number ending in a set bit followed by 13 clear
bits). In this case, the DMA transfer will not complete successfully.
This can cause clicks and pops in the audio output.  This bug no longer
requires special handling by the application since it is patched by
osAiSetNextBuffer.

.SH NOTES
For hardware version 1.0, the audio DMA length register is only 15-bit long
and thus supports a maximum transfer size of 32 Kbytes. In the final 
release, this register is extended to 18 bits to support a transfer of 
256 Kbytes.
.SH "SEE ALSO"
.IR osTvType (3P).