osSpTaskLoad, osSpTaskStartGo, osSpTaskStart, osSpTaskYield, osSpTaskYielded

Starts/yields SP tasks

Syntax

#include <ultra64.h>     /* ultra64.h */
void osSpTaskLoad(OSTask *task);
s32 osSpTaskStartGo(OSTask *task);
s32 osSpTaskStart(OSTask *task);s32 osSpTaskYield(void);
OSYieldResult osSpTaskYieled(OSTask *task);

Description

These functions manage the signal processor (SP) "tasks" that can be invoked from the CPU host. Tasks are embodied by an OSTask structure. Please follow the instruction described below for task fields. Following the completion of a task, the SP interrupts the CPU and generates an OS_EVENT_SP event. The application can associate a message queue with this event with the osSetEventMesg call. Furthermore, graphics task display lists should complete with a call to gDPFullSync to additionally cause the display processor (DP) to interrupt the CPU. The associated event for osSetEventMesg is OS_EVENT_DP.

The osSpTaskLoad function loads the given task into the SP. Before calling it, you must ensure that the SP is not currently executing. If this is a brand new task, the OSTask structure members need to be initialized by the application.

The osSpTaskStartGo function causes the SP to begin executing.

The osSpTaskStart macro calls the osSpTaskStartGo, and then calls the osSpTaskLoad function.

The osSpTaskYield function 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 saves its state so that it can be restarted by calling 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.

The osSpTaskYielded function must be called after requesting a yield to ensure the proper state of the task structure. 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).

Following are the members of the OSTask Structure:

t.type

Task type. It should be initialized to M_AUDTASK for audio tasks or M_GFXTASK for graphics tasks.

t.flags

Various task state bits. OS_TASK_DP_WAIT is the most important flag. When this flag is set, the boot microcode waits for the RDP to drain its current command stream before continuing.

This is necessary if you are going to use the XBUS or switch the RDP input stream. However, do not set this flag for audio tasks or "_fifo" versions of graphics tasks.

t.ucode_boot

Pointer to boot microcode. It should be initialized to rspbootTextStart.

t.ucode_boot_size

Pointer to boot microcode size in bytes. It should be initialized to ((u32)rspbootTextEnd - (u32)rspbootTextStart).

t.ucode

Pointer to task microcode. For graphic tasks, use of of the following: gspFast3DTextStart, gspFast3D_dramTextStart, gspFast3D_fifoTextStart, gspLine3DTextStart, gspLine3D_dramTextStart, and gspLine3D_fifoTextStart. It should be set to aspMainTextStart for audio tasks.

t.ucode_size

Size of microcode. It should be initialized to SP_UCODE_SIZE.

t.ucode_data

Pointer to task microcode. For graphics tasks, the followings should be set: gspFast3DDataStart, gspFast3D_dramDataStart, gspFast3D_fifoDataStart, gspLine3DDataStart, gspLine3D_dramDataStart, gspLine3D_fifoDataStart. It should be set to aspMainDataStart for audio tasks

t.ucode_data_size

Size of microcode data. It should be initialized to SP_UCODE_DATA_SIZE.

t.dram_stack

Pointer to DRAM matrix stack. It should be initialized to 0 for audio tasks and to a memory region of size SP_DRAM_STACK_SIZE8 bytes for graphics tasks.

t.dram_stack_size

DRAM matrix stack size in bytes. It should be initialized to 0 for audio tasks or SP_DRAM_STACK_SIZE8 for graphics tasks.

t.output_buff

Pointer to output buffer. The "_dram" and "_fifo" 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 "_dram" versions of the microcode the buffer must be as long or longer than the DP data stream that will be generated by the RSP. The "_fifo" versions of the microcode require a buffer of at least 0x100 bytes, although larger buffers may provide greater performance.

t.output_buff_size

For the "_dram" version of the microcode this is a *POINTER* to a N64 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 "_fifo" version of the microcode this is a *POINTER* to the byte following the last byte in the output buffer. The other microcodes ignore the t.output_buff_size field.

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 alAudioFrame.

t.data_size

Length of SP command list in bytes.

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 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.

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 OS_YIELD_DATA_SIZE for the graphics task. Audio tasks should set this field to 0.

The dram_stack, output_buff, output_buff_size, and yield_data_ptr pointers should point to memory regions that reside entirely in an integral number of data cache lines. That is, 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 OS_DCACHE_ROUNDUP_ADDR can be used, but the easiest way to align these memory regions is to place each of them in its own relocatable ".o." object file.

See Also

osSpTaskLoad, osSpTaskStartGo, osSpTaskStart, and osSpTaskYield

Revision History

1999/04/30 Changed Format