.TH osSpTaskLoad 3P local "Silicon Graphics, Inc."
.SH NAME
.upperok
osSpTaskLoad, osSpTaskStartGo, osSpTaskStart, osSpTaskYield, osSpTaskYielded \- start and yield SP tasks
.SH SYNOPSIS
.nf
\f3
.Op c
#include <ultra64.h>
.sp .8v
void osSpTaskLoad(OSTask *task);
.sp .8v
s32 osSpTaskStartGo(OSTask *task);
.sp .8v
s32 osSpTaskStart(OSTask *task);
.sp .8v
s32 osSpTaskYield(void);
.sp .8v
OSYieldResult osSpTaskYielded(OSTask *task);
.Op
\f1
.fi
.SH DESCRIPTION
These functions manage the SP "tasks" that can be invoked from the CPU host.
Tasks are embodied by an
.I OSTask
structure, the fields of which are described below.
Following the completion of a task, the SP interrupts the CPU
and generates an
.I OS_EVENT_SP
event.
The application can associate a message queue with this event with the
.IR osSetEventMesg (3P)
call.
Furthermore,
graphics task display lists should complete with a
.IR gDPFullSync (3P)
command which will additionally cause the DP to interrupt the CPU.
The associated event for
.I osSetEventMesg
is
.I OS_EVENT_DP.
.PP
The
.I osSpTaskLoad
function loads the given task into the SP.
It assumes (requires) that the SP is not currently executing.
If this is a brand new task,
the
.I OSTask
structure members need to initialized by the application.
.PP
The
.I osSpTaskStartGo
function causes the SP to begin executing.
.PP
The
.I osSpTaskStart
macro performs an
.I osSpTaskLoad
followed by a
.I osSpTaskStartGo.
.PP
The
.I osSpTaskYield
requests that the SP "yield".
A yield is a premature stopping of a Graphics task at a point where it can be
restarted.
During a yield,
the SP will save its state so that it can be restarted with a call to
.I osSpTaskStart.
Currently, only graphics tasks can yield.
Yielding is primarily used for pausing the graphics task so that an audio
task can run when it needs to.
.PP
The
.I osSpTaskYielded
function must be called after requesting a yield in order
to ensure the proper state of the task structure.
In addition, it returns OS_TASK_YIELDED if the task successfully yielded.
Otherwise it returns 0 which indicates that the
task finished normally before it could yield (and therefore should not be
restarted later).
.PP
The
.I OSTask
structure members are defined as follows:
.TP 10
.I t.type
Task type; should be initialized to
.I M_AUDTASK
for audio tasks or
.I M_GFXTASK
for graphics tasks.
.TP
.I t.flags
Various task state bits.
.I OS_TASK_DP_WAIT
is the flag of most concern; when this is set, the
boot microcode will wait for the RDP to drain it's current
command stream before continuing. This is necessary if
you are going to use the XBUS or switch the RDP input stream, 
but you do not want to set this flag for audio tasks or
"\fI_fifo\fR" versions of graphics tasks.
.TP
.I t.ucode_boot
Pointer to boot microcode; should be initialized to
.I rspbootTextStart.
.TP
.I t_ucode_boot_size
Pointer to boot microcode size in bytes;
should be initialized to
.I "((u32)rspbootTextEnd - (u32)rspbootTextStart)."
.TP
.I t.ucode
Pointer to task microcode.
Should be set to one of
.I gspFast3DTextStart,
.I gspFast3D_dramTextStart,
.I gspFast3D_fifoTextStart,
.I gspLine3DTextStart,
.I gspLine3D_dramTextStart
or
.I gspLine3D_fifoTextStart
for graphics tasks;
otherwise
.I aspMainTextStart
for audio tasks.
.TP
.I t.ucode_size
Size of microcode; should be initialized to SP_UCODE_SIZE.
.TP
.I t.ucode_data
Pointer to task microcode.
Should be set to one of
.I gspFast3DDataStart,
.I gspFast3D_dramDataStart,
.I gspFast3D_fifoDataStart,
.I gspLine3DDataStart,
.I gspLine3D_dramDataStart
or
.I gspLine3D_fifoDataStart
for graphics tasks;
otherwise
.I aspMainDataStart
for audio tasks.
.TP
.I t.ucode_data_size
Size of microcode data; should be initialized to
.I SP_UCODE_DATA_SIZE.
.TP
.I t.dram_stack
Pointer to DRAM matrix stack;
should be initialized to 0 for audio tasks
and to a memory region of size
.I SP_DRAM_STACK_SIZE8
bytes for graphics tasks.
.TP
.I t.dram_stack_size
DRAM matrix stack size in bytes;
should be initialized to 0 for audio tasks or
.I SP_DRAM_STACK_SIZE8
for graphics tasks.
.TP
.I t.output_buff
Pointer to output buffer.
The "\fI_dram\fR" and "\fI_fifo\fR" versions of the graphics
microcode will route the SP output
to DRAM rather than to the DP.
When this microcode is used, this should point to a memory region to which
the SP will write the DP command list. For "\fI_dram\fR" versions of
the microcode the buffer must be as long or longer than the DP data stream
which will be generated by the RSP.  The "\fI_fifo\fR" versions of the
microcode require a buffer of at least 0x100 bytes, although larger buffers
may provide greater performance.
.TP
.I t.output_buff_size
For the "\fI_dram\fR" version of the microcode this is a 
*POINTER* to a u64 where the output buffer length will go.
The SP will write the size of the DP command list in bytes to this location.
For the "\fI_fifo\fR" version of the microcode this is a *POINTER* the the
byte following the last byte in the output buffer.
The other microcodes (other 
than "\fI_dram\fR" and "\fI_fifo\fR") ignore the t.output_buff_size field.
.TP
.I t.data_ptr
SP command list pointer.
For graphics tasks, this is the application constructed display list.
For audio tasks, this command list is created by
.IR alAudioFrame (3P).
.TP
.I t.data_size
Length of SP command list in bytes.
.TP
.I t.yield_data_ptr
Pointer to buffer to store saved state of yielding task.
If the application is going to support preemption of graphics tasks,
the graphics tasks should have this structure member set.
This should point to a memory region of size
.I OS_YIELD_DATA_SIZE
bytes.
If task preemption is not supported by the application,
this field should be initialized to 0.
Audio tasks should always set this field to 0.
.TP
.I t.yield_data_size
Size of yield buffer in bytes.
When task yielding is to be supported by the application,
this should be initialized to
.I OS_YIELD_DATA_SIZE
for the graphics task.
Audio tasks should set this field to 0.
.PP
The
.I dram_stack, 
.I output_buff,
.I output_buff_size,
and
.I yield_data_ptr
pointers should point to memory regions that reside entirely in an integral
number of data cache lines,
i.e.,
they should be aligned and padded to 16 byte boundaries.
If the affected memory region is not cache aligned,
there exists the possibility that a CPU program variable may also
share the data cache line.
During normal operation of the CPU cache,
the data cache line may be written back and overwrite
the data previously written by SP.
The macros described in
.IR OS_DCACHE_ROUNDUP_ADDR (3P)
may be used,
but the simplest way to align these memory regions is to 
place each of them in its own relocatable ".o".