Using the Scheduler

The Scheduler is a host CPU thread that addresses the issues discussed above. It is responsible for executing audio and graphics tasks on the RCP such that host and RCP overrun is minimized or eliminated.

Each video retrace, the Scheduler reads the new tasks generated by client threads from the task queue and adds them to the end of a real-time (audio) or non-real-time (graphics) task schedule list.

If the previous frame’s graphics task has overrun, the Scheduler causes the task to yield. It then runs the next audio task, resuming the yielded task when the audio task has completely processed, and any additional graphics tasks that are to be run to be run in the current frame.

When a task completes, the Scheduler sends a message to the client indicating that the work it requested is complete.

Creating the Scheduler: osCreateScheduler()
In order to use the Scheduler, you must first call osCreateScheduler() to initialize the OSSched data structure, its message queues and the Vi Manager. The osCreateScheduler() function spawns a thread to schedule and manage task execution.

Note: One of the parameters to this call is the thread priority, which should be higher than that of the threads which generate the command lists.

Adding Clients to the Scheduler: osScAddClient()
The Scheduler instantiates the Vi Manager and receives all retrace messages. However, clients of the Scheduler can receive a copy of the retrace message by providing a message queue when they sign in. This is accomplished by calling the osScAddClient() function.

Note: One of the parameters to this call is the message queue on which you wish to receive retrace messages. Make sure that the queue is big enough if you don’t want to lose messages, as the Scheduler does not block when the queue is full.

Creating Scheduler Tasks: The OSScTask Structure
In order to send tasks to the Scheduler for execution, you must first create and initialize an OSScTask structure. The structure and a description of its fields is listed below.

    typedef struct OSScTask_s {
        struct OSScTask_s   *next;
        s32                 state;
        u32			flags;
        void			*framebuffer;

        OSTask 			list;
        OSMesgQueue			*msgQ;
        OSMesg 			msg;
    } OSScTask;

Table 1 OSScTask structure fields

Field | Description
next | Not used by client (used by the scheduler for list management). state Not used by client (used by the scheduler for state management). framebuffer Address of the frame buffer for this task (if it is a graphics task).
list | Structure containing task code and command list data (described below).
msgQ | The message queue on which the client is to receive the task done message.
msg | The message that the client is to receive when the task in done.

Table 2 OSScTask structure fields

Field | Description
type | Task type; should be initialized to M_AUDTASK for audio tasks or M_GFXTASK for graphics tasks.
flags | Various task state bits; should be initialized to 0 for audio tasks, or OS_TASK_DP_WAIT for most graphics tasks ucode_boot Pointer to boot microcode; should be initialized to rspbootTextStart.
ucode_boot_size | Pointer to boot microcode size in bytes; should be initialized to ((u32)rspbootTextEnd - (u32)rspbootTextStart).
ucode | Pointer to task microcode. Should be set to one of gspFast3DTextStart, gspFast3D_dramTextStart, gspLine3DTextStart, or gspLine3D_dramTextStart for graphics tasks; otherwise aspMainTextStart for audio tasks.
ucode_size | Size of microcode; should be initialized to SP_UCODE_SIZE.
ucode_data | Pointer to task microcode. Should be set to one of gspFast3DDataStart, gspFast3D_dramDataStart, gspLine3DDataStart, or gspLine3D_dramDataStart for graphics tasks; otherwise aspMainDataStart for audio tasks.
ucode_data_size | Size of microcode data; should be initialized to SP_UCODE_DATA_SIZE.
dram_stack | Pointer to DRAM matrix stack; should be initialized to 0 for audio tasks and to memory region of size SP_DRAM_STACK_SIZE8 bytes.
dram_stack_size | DRAM matrix stack size in bytes; should be initialized to 0 for audio tasks or SP_DRAM_STACK_SIZE8 for graphics tasks.
output_buff | Pointer to output buffer. The “_dram” 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.
output_buff_size | Pointer to store output buffer length. The SP will write the size of the DP command list in bytes to this location.
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(3P).
data_size | Length of SP command list in bytes.
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 be initialized to 0. Audio tasks should always set this field to 0.
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. This should always be 0 for audio tasks.

Note: Refer to the osSpTaskLoad man page for information about the alignment restrictions of the data pointers.

Sending Tasks to the Scheduler: osScGetTaskQ()
Once you have created and initialized a Scheduler task, you can send it to the Scheduler thread via the Scheduler’s task queue. You can obtain a pointer to this queue by calling osScGetTaskQ().

The Scheduler will read this task queue after the next retrace message from the Vi Manager. Normally, you will send one audio and one graphics task to the Scheduler each frame.

Note: After you send the task to the Scheduler, you should not modify it until you receive the “done” message.

Copyright © 1999 Nintendo of America Inc. All Rights Reserved Nintendo and N64 are registered trademarks of Nintendo Last Updated January, 1999