Revolution OS

From WiiBrew
Jump to navigation Jump to search

Revolution OS is a part of the SDK that is always included. It does not handle security; IOS is responsible for that.

Public functions

Name Prototype Description
OSGetConsoleType int OSGetConsoleType(void) Returns the platform ID. See below for more details.
OSInit void OSInit(void) Initializes all parts of the library.
OSSaveFPUContext void OSSaveFPUContext(OSContext *ctx) Saves the floating point registers to ctx.
OSSetCurrentContext void OSSetCurrentContext(OSContext *ctx) Sets the context to ctx, causing future register saving to go there.
OSGetCurrentContext OSContext *OSGetCurrentContext(void) Gets the OSContext instance currently being used (not the floating point one).
OSSaveContext bool OSSaveContext(OSContext *ctx) Saves nonessential registers to ctx, since essential registers were saved by the exception vector if needed. Returns true if the function is returning after ctx was reloaded back to the state, which was saved as being in this function.
OSLoadContext void OSLoadContext(OSContext *ctx) Loads the registers in ctx. This function is also responsible for ensuring OSDisableInterrupts runs atomically to prevent MSR corruption.
OSGetStackPointer void *OSGetStackPointer(void) Returns the current stack pointer.
OSSwitchFiber void OSSwitchFiber(void *code, void *stack) Swaps the stack and jumps to code.
OSSwitchFiberEx void OSSwitchFiberEx(int param1, int param2, int param3, int param4, void *code, void *stack) Swaps the stack and jumps to code, passing up to 4 args.
OSClearContext void OSClearContext(OSContext *ctx) Marks ctx as having nothing saved to it.
OSInitContext void OSInitContext(OSContext *ctx) Sets all saved registers in ctx to 0.
OSDumpContext void OSDumpContext(OSContext *ctx) Prints all saved registers in ctx.
OSReport void OSReport(char *format, ...) Calls vprintf; the formatted text gets sent through some MetroTRK-related SerialIO port
OSPanic void OSPanic(char *sourceFile, int lineNo, char *format, ...) Prints the message similar to OSReport, then prints the crash location and a stack trace.
OSDisableInterrupts bool OSDisableInterrupts(void) Disables interrupts, allowing code to run atomically. Returns the previous interrupt state for a call to OSRestoreInterrupts.
OSEnableInterrupts bool OSEnableInterrupts(void) Enables interrupts, returning the previous interrupt state. This function should be used with care, since it may have unintended effects if a calling function disabled interrupts.
OSRestoreInterrupts bool OSRestoreInterrupts(bool interruptState) Sets the interrupt state to the state specified by the parameter. Typically used at the end of an atomic segment. Returns the previous interrupt state.
__OSSetInterruptHandler void (*OSSetInterruptHandler(int interrupt, void (*handler)(void)))(void) Sets the handler for a particular interrupt, returning the old handler.
__OSGetInterruptHandler void (*OSGetInterruptHandler(int interrupt))(void) Reads the appropriate handler from a table.
OSInitMessageQueue void OSInitMessageQueue(OSMessageQueue *queue, int *buf, int capacity) Initializes the fields of the OSMessageQueue
OSSendMessage bool OSSendMessage(OSMessageQueue *queue, int msg, bool waitForSpace) Adds a message to the end of the queue. Returns whether this was successful.
OSReceiveMessage bool OSReceiveMessage(OSMessageQueue *queue, int *msg, bool waitForMsg) Removes a message from the front of the queue, returning whether the operation was successful.
OSJamMessage bool OSJamMessage(OSMessageQueue *queue, int msg, bool waitForSpace) Adds a message to the front of the queue. Returns whether this was successful.
OSGetPhysicalMem1Size int OSGetPhysicalMem1Size(void) Reads the MEM1 size from lomem.
OSGetPhysicalMem2Size int OSGetPhysicalMem2Size(void) Reads the MEM2 size from lomem.
OSGetConsoleSimulatedMem1Size int OSGetConsoleSimulatedMem1Size(void) Reads the simulated MEM1 size from lomem.
OSGetConsoleSimulatedMem2Size int OSGetConsoleSimulatedMem2Size(void) Reads the simulated MEM2 size from lomem.
OSInitMutex void OSInitMutex(OSMutex *mutex) Initializes the fields of a mutex
OSLockMutex void OSLockMutex(OSMutex *mutex) Locks a mutex, blocking if needed. Supports recursive locking.
OSUnlockMutex void OSUnlockMutex(OSMutex *mutex) Unlocks a mutex. Supports recursive locking.
OSTryLockMutex bool OSTryLockMutex(OSMutex *mutex) Attempts to lock a mutex, returning whether the operation was successful.
OSYieldThread void OSYieldThread(void) Switches to another thread
OSCreateThread bool OSCreateThread(OSThread *thread, void (*main)(void *arg), void *arg, void *stackPtr, int stackSize, int priority, bool detached) Creates and starts a thread using the given OSThread.
OSCancelThread void OSCancelThread(OSThread *thread) Stops a thread
OSSleepThread void OSSleepThread(OSThreadQueue *waitingQueue) Pauses the current thread until OSResumeThread is called with this thread queue
OSResumeThread void OSResumeThread(OSThreadQueue *waitingQueue) Resumes all threads in the queue

OSGetConsoleType

OSInit calls a function to log platform information, which gets the platform ID from a function called OSGetConsoleType.

OSGetConsoleType priorities the masked DVD device code address first, MEM2 size second, and Hollywood size third. If an entry in the table is marked with an X, then any value can work, unless that value matches an explicitly listed console type.

Name ID (hex) Hollywood version (hex) Masked DVD device code address (hex) MEM2 size Notes
Pre-production board 1 00000011 1 2
3
203
64MB
Pre-production board 2-1 00000012 2 2
3
203
64MB
Pre-production board 2-2 00000020 10 2
3
203
64MB
RVA 1 00000100 X 300 X This did not exist in launch day versions of OSGetConsoleType.
Retail # 0XXXXXXX X 2
3
203
X Always followed by the ID
NDEV 2.1 10000021 11 202 128MB This does not exist in the June 23 2006 version of Revolution OS (found in MIOS), but it does exist in the July 27 2006 version (found in NandIOS2 in RVL_DIAG), which still has support for RVL0 apploaders.
NDEV 2.0 10000020 10 202 128MB
NDEV 1.2 10000012 2 202 128MB
NDEV 1.1 10000011 1 202 128MB
NDEV 1.0 10000010 0 202 128MB
Revolution Emulator 10000008 XXXXXXXX X X
Emulation platform (#) 1XXXXXXX X 202 X Always printed with the console type ID.
TDEV-based emulation HW# 2XXXXXXX X X X Always printed with the console type ID.

OSDBIntegrator

There is a string saying Installing OSDBIntegrator. OSDBIntegrator seems to be a debug stub installed at 0x80000060 that branches to the address stored at 0x80000048. It is not known how this code is reached, as it is not jumped to by any retail code.

The code itself seems to be printing DBExceptionDestination, printing the current OSContext, and hanging the Broadway.

Exceptions

With the exception of a system call, all exceptions have the same handler, which loads the appropriate exception-specific handler from the array at 0x80003000, or the default handler if the is no specific handler or the exception is not recoverable. Exception types are given IDs by Revolution OS; these numbers are used when setting an exception handler.

Type ID Vector location Notes
System Reset 0 80000100
Machine Check 1 80000200
DSI 2 80000300
ISI 3 80000400
External (IRQ) 4 80000500
Alignment 5 80000600
Program 6 80000700
FP unavailable 7 80000800
Decrementer 8 80000900
System call 9 80000C00
Trace 10 80000D00
Performance Monitor 11 80000F00
IABR 12 80001300
Reserved 13 80001400
Thermal 14 80001700
Memory interface 15 N/A Memory IRQs are sent to this exception handler. Unlike other exception handlers, this should be NULL to indicate that it should be unhandled (not a pointer to the default handler).

IRQs

IRQs are processed by handlers in the __OSInterrupt table; the bit index of the each source is the same as the index in the table; integers built from these bits are used for functions that mask interrupts.

Index Source
0 MEM0
1 MEM1
2 MEM2
3 MEM3
4 All MI
5 DSP ADINT
6 DSP ARINT
7 DSP DSPINT
8 AI
9 EXI EXTINT low (channel 0)
10 EXI TCINT (channel 0)
11 EXI EXTINT high (channel 0)
12 EXI EXTINT low (channel 1)
13 EXI TCINT (channel 1)
14 EXI EXTINT high (channel 1)
15 EXI EXTINT low (channel 2)
16 EXI TCINT (channel 2)
26 HSP
25 DEBUG
20 PE FINISH
19 PE TOKEN
24 VI
21 Serial
22 DVD
23 Reset switch
18 CP FIFO
27 GP Runtime Error

Context saving

When a non-syscall exception occurs, the current state is stored in a struct called OSContext; the struct is 0x2c8 bytes long.

struct OSContext {
	u32 gprs[0x20]; // r0-r31
	u32 cr; // 0x80
	u32 lr; // 0x84
	u32 ctr; // 0x88
	u32 xer; // 0x8c
	u64 fprs[0x20]; // f0-f31
	u64 fpscr; // 0x190
	u32 srr0; // 0x198 - saved PC
	u32 srr1; // 0x19c - saved MSR
	u16 state; // 0x1a2; last bit means OSSaveFPUContext was called, second last bit means the GPRs were saved by the exception handler
	u64 gqrs[4]; // 0x1a4
	u64 pairedSingles[0x20]; // starting at 0x1c8
}

Most OSContext instances belong to threads, and are at the beginning of the OSThread struct. However, there are also some standalone OSContext instances, such as the one used while waiting for an available thread.

FPU

Revolution OS keeps the FPU disabled by default, and enables it when an FPU unavailable exception triggers. When other exceptions trigger, Revolution OS disables the FPU in the previous OSContext.

Threads

Threads are stored in the OSThread struct.

struct OSThread {
	struct OSContext ctx;
	u16 state; // 0x2c8; 0 = stopped, 1 = inactive, 2 = active, 4 = sleeping, 8 = returned result?
	u16 detached; // 0x2ca; zero = false, nonzero = true
	u32 suspend; // seems to be a balancing counter. 0 = active, 1 = suspended
	u32 priority; // 0x2d0; can range from 0-31
	u32 basePriority; // 0x2d4
	u32 returnValue; // 0x2d8
	struct OSThreadQueue *queue; // 0x2dc
	struct OSThreadLink linkQueue; // 0x2e0
	struct OSThreadQueue queueJoin; // 0x2e8
	struct OSMutex *mutex; // 0x2f0; mutex currently waiting for; used for deadlock detection
	struct OSMutexQueue queueMutex; // 0x2f4
	struct OSThreadLink linkActive; // 0x2fc
	void *stackStart; // 0x304
	void *stackEnd; // 0x308
	u32 unknown; // 0x30c
	u32 threadSpecifics[2]; // 0x310
}

struct OSThreadQueue {
	struct OSThread *head;
	struct OSThread *tail;
}

struct OSThreadLink {
	struct OSThread *next;
	struct OSThread *prev;
}

struct OSMutex {
	struct OSThreadQueue waitingQueue;
	struct OSThread *holder;
	u32 timesLocked; // used if a mutex is locked multiple times by the same thread
	struct OSMutex *next;
	struct OSMutex *prev;
}

struct OSMutexQueue {
	struct OSMutex *head;
	struct OSMutex *tail;
}

struct OSThreadInfo { // fields are sometimes directly accessed
	struct OSThread initialThread;
	struct OSThreadQueue RunQueue[0x20];
	struct OSContext idleCtx;
}

When rescheduling, threads are taken from the queue corresponding to the smallest priority. Additionally, unless the rescheduling is done by OSYieldThread, the new priority must be smaller than the current one for a thread switch to occur.

Memory allocation

Memory can be allocated from a heap or the MEM1 arena.

struct OSHeapCell {
	struct OSHeapCell *prev;
	struct OSHeapCell *next;
	u32 size;
	u8 unknown[0x14];
}

struct OSHeapData {
	u32 size;
	struct OSHeapCell *free;
	struct OSHeapCell *allocated;
}

Message queues

Message queues are very similar to IOS, but with no process isolation.

struct OSMessageQueue {
	struct OSThreadQueue waitForSend;
	struct OSThreadQueue waitForReceive;
	void *buf;
	u32 messageCapacity;
	u32 rotation;
	u32 messagesEnqueued;
}

Shutdown handlers

Shutdown handlers only seem to be called when an error occurs, not on normal shutdown or return to System Menu.

struct OSShutdownFunction {
	void *func; // 2 params, unknown type
	u32 priority; // lower priority goes first
	struct OSShutdownFunction *next;
	struct OSShutdownFunction *prev;
}

Dynamic linking

REL files are loaded through OSLink. At each relocation address, the instruction is patched with information about the base address depending on the relocation type. Types 1, 3, and 4 are identical and are used for 32-bit data, while type 2 is used for absolute branching instructions, type 5 is used for 16-bit data, type 6 is used for swapped endian, types 7-9 are used for absolute conditional branches, type 10 is used for relative branches, and types 11-13 are used for relative conditional branches. There is also a type 109 (0x6d - 'm') that has an unknown purpose.

__OSModuleInit writes NULL pointers to the module linked list head and tail, but no code in main binaries seems to write real pointers here; this is presumably done by the modules themselves.