View source for Coreinit.rpl

coreinit.rpl is the the system library that provides direct access to Cafe OS services. It provides kernel calls, thread scheduling, memory management, and filesystem services. coreinit is the first RPL loaded by the loader, even before the main executable itself.

==Functions==
===Cache===
{| class="wikitable"
!Name
!Prototype
!Description
|-
|DCFlushRange
|<code>void DCFlushRange(const void *addr, size_t length);</code> 
|Flush the specified data cache blocks to memory
|-
|DCInvalidateRange
|<code>void DCInvalidateRange(void *addr, size_t length);</code> 
|Invalidate the specified data cache blocks
|-
|ICInvalidateRange
|<code>void ICInvalidateRange(const void *addr, size_t length);</code> 
|Invalidate the specified instruction cache blocks
|}

===Disassembler===
{| class="wikitable"
!Name
!Prototype
!Description
|-
|DisassemblePPCOpcode
|<code>void DisassemblePPCOpcode(uint32_t *addr, char *instr_buf, int instr_len, find_symbol_t sym_func, int flags);</code>
|Disassemble a PPC opcode at addr and place it into instr_buf (instr_len must be 0x40 or lower)
|-
|DisassemblePPCRange
|<code>void DisassemblePPCRange(uint32_t *start, uint32_t *end, printf_t printf_func, find_symbol_t sym_func, int flags);</code> 
|Disassemble PPC instructions from start to end, printing them using printf_func() with various flags applied
|}

===Dynamic Linking===
{| class="wikitable"
!Name
!Prototype
!Description
|-
|OSDynLoad_Acquire
|<code>void OSDynLoad_Acquire(const char *rplname, uint32_t *handle);</code> 
|Acquire a handle to an RPL by name
|-
|OSDynLoad_FindExport
|<code>void OSDynLoad_FindExport(uint32_t handle, bool isdata, const char *symname, void **address);</code> 
|Get a symbol address from a loaded RPL
|}

===Error===
{| class="wikitable"
!Name
!Prototype
!Description
|-
|OSFatal
|<code>void OSFatal(const char *msg);</code> 
|Print a message to the screen and halts the system
|}

===Internal===
{| class="wikitable"
!Name
!Prototype
!Description
|-
|__os_snprintf
|<code>int __os_snprintf(char *buf, size_t n, const char *format, ... );</code> 
|Format a string and place it in a buffer (just like [http://www.cplusplus.com/reference/cstdio/snprintf/ snprintf()])
|}

===Threads===
{| class="wikitable"
!Name
!Prototype
!Description
|-
|OSCreateThread
|<code>bool OSCreateThread(OSThread *thread, void (*entry)(int,void*), int argc, void *args, void *stack, size_t stack_size, int32_t priority, int16_t affinity);</code> 
|Create a (initially-paused) thread that starts at the specified entry point
|-
|OSResumeThread
|<code>void OSResumeThread(OSThread *thread);</code>
|Resume a paused thread, causing it to be scheduled
|-
|OSYieldThread
|<code>void OSYieldThread(void);</code>
|Yield control of the CPU, allowing another thread to run
|-
|OSGetCurrentThread
|<code>OSThread *OSGetCurrentThread(void);</code>
|Get the OSThread structure ptr for the current thread.
|-
|OSSetThreadAffinity
|<code>uint32_t OSSetThreadAffinity(OSThread* thread, int16_t affinity);</code>
|Sets the affinity for the specified thread. Returns 0 for failure, 1 for success.
|-
|OSGetCoreId
|<code>uint32_t OSGetCoreId(void);</code>
|Returns the PowerPC coreid this code is running on(value of spr1007).
|-
|OSGetStackPointer
|<code>uint32_t *OSGetStackPointer(void);</code>
|Returns the r1 register(aka "sp").
|}

===Codegen===
These functions are used for managing the codegen/JIT area which begins at virtual-memory address 0x01800000. The codegen area size, whether codegen can be used at all, and permissions/etc are loaded from cos.xml for the process. Hence, almost all processes which don't use WebKit don't have access to codegen. These permissions include the coreid which is allowed to use codegen at all(with [[Internet Browser]] this is core1). These permissions also seem to include whether the process is allowed to use OSCodegenCopy([[Internet Browser]] isn't allowed to use it). Certain Virtual Console titles seem to be the only applications which are allowed to use OSCodegenCopy due to cos.xml(codegen_core is set to 40000001 for these, unlike 80000001 for browser-based titles).

{| class="wikitable"
!Name
!Prototype
!Description
|-
|OSGetCodegenVirtAddrRange
|<code>void OSGetCodegenVirtAddrRange(uint32_t *outaddr, uint32_t *outsize);</code>
|This calls syscall 0x4e00 then writes the output r3/r4 from the syscall, to outaddr/outsize. The outaddr value is codegen+0, outsize is the size of the entire codegen memory that's currently mapped. When codegen isn't available, the output values are all-zero.
|-
|OSGetCodegenCore
|<code>uint32_t OSGetCodegenCore(void);</code>
|This returns (syscall_7600() & 0x3), which is the coreid that's allowed to use codegen.
|-
|OSGetCodegenMode
|<code>uint32_t OSGetCodegenMode(void);</code>
|This returns (syscall_7600() & ~0x3), which contains some of the flags used by the kernel for codegen permission checking. The only bits which the kernel can ever set here are for bitmask 0xC0000000.
|-
|OSSwitchSecCodeGenMode
|<code>uint32_t OSSwitchSecCodeGenMode(bool flag);</code>
|This adjusts the entire codegen memory permissions, if codegen is available. 0: RW- permissions. Non-zero: R-X permissions. This returns 0 for failure, non-zero for success.
|-
|OSGetSecCodeGenMode
|<code>uint32_t OSGetSecCodeGenMode(void);</code>
|This just calls syscall 0x7700. Which then returns 1 when codegen is available+mapped, 0 otherwise.
|-
|OSCodegenCopy
|<code>uint32_t OSCodegenCopy(uint32_t *dstaddr, uint32_t *srcaddr, uint32_t size);</code>
|In coreinit this just executes syscall 0x7800. This returns 0 for failure, 1 for success. The dstaddr(+size) must be within the codegen memory(integer overflow with dstaddr+size is checked for). If all of the permissions/bounds checks pass(size must not be zero), the kernel will then set the codegen permissions to RW- with code used by SwitchSecCodeGenMode internally. Then it copies the input data from userland memory to the dstaddr with the specified size. Lastly, the codegen permissions are set to R-X with the previously mentioned internal function.
|}

=== Screen ===
"bufferNum" is the screenid, see the below screen defines for that. OSScreen *only* supports values 0-1 for screenid. "colour" in the form stored in memory is RGBA8. These functions can't be used without crashing, unless OSScreen was properly initialized. The below functions will immediately return if x/y is out-of-bounds.

This uses the hardware registers via the vaddr loaded with __OSPhysicalToEffectiveUncached(0x0C200000). This is the same hardware used for normal framebuffer display with framebuffers rendered by the GPU. The coreinit register r/w access code for this will only access the registers if OSIsECOMode() returns 0(when reading it would always return value 0 if that func-call returns non-zero). Internally the coreinit reg-access functions for this use word-offsets for the registers. The registers are accessed from there with the following: above_vaddr_base + (screenid<<9) + reg_wordoffset.

OSFatal does the following for initializing the framebuffer addresses: "OSScreenSetBufferEx(0, 0xF4000000)" and "OSScreenSetBufferEx(1, 0xF4000000 + OSScreenGetBufferSizeEx(0))".

The framebuffer addresses passed to OSScreenSetBufferEx must be 0x100-byte aligned(bitmask 0xff clear). The byte-size of each scanline in the framebuffers are 0x100-byte aligned as well.

{| class="wikitable"
!Name
!Prototype
!Description
|-
|OSScreenInit
|void OSScreenInit(void)
|This is the main initialization function, this must be called before any of the other OSScreen functions. This includes register writes which will enable framebuffer display, via the same bit OSScreenEnableEx() uses.
|-
|OSScreenShutdown
|void OSScreenShutdown(void);
|This just does the following two function calls: "OSScreenEnableEx(0, 0)" and "OSScreenEnableEx(1, 0)".
|-
|OSScreenEnableEx
|void OSScreenEnableEx(int bufferNum, bool flag)
|flag0: disable framebuffer display(solid-black is displayed instead). flag1: enable framebuffer display. There's no need to call this right after OSScreenInit() for enabling framebuf display, see above.
|-
|OSScreenGetBufferSizeEx
|uint32_t OSScreenGetBufferSizeEx(int bufferNum)
|This returns the total byte-size of the primary+secondary framebuffers for the specified screen(single_framebufsize*2).
|-
|OSScreenSetBufferEx
|void OSScreenSetBufferEx(int bufferNum, uint32_t *vaddr_framebufptr)
|This sets the framebuffer addresses for the specified screen(only in coreinit state). primary_framebuf = vaddr_framebufptr+0, secondary_framebuf = vaddr_framebufptr+single_framebuf_bytesize. The physical framebuffer addresses in hardware won't get updated until OSScreenFlipBuffersEx() is called. This function must be called before using any of the other OSScreen functions with this screen(besides OSScreenEnableEx), otherwise a crash will occur due to the framebuf addrs not being initialized.
|-
|OSScreenFlipBuffersEx
|void OSScreenFlipBuffersEx(int bufferNum);
|Do a buffer-swap, which results in the buffer previously being drawn to being displayed. This flushes data-cache for the framebuffer and updates coreinit + hw-regs state.
|-
|OSScreenClearBufferEx
|void OSScreenClearBufferEx(int bufferNum, uint32_t colour);
|Fill the specified buffer with a certain color. This writes the input u32 value to coreinit screen state, then copies that u32 in state to every u32 in the single framebuffer(calculated with the total bytesize of a single framebuffer).
|-
|OSScreenPutPixelEx
|void OSScreenPutPixelEx(int bufferNum, uint32_t posX, uint32_t posY, uint32_t colour);
|Draw a pixel of a certain color to the specified coordinates. This just writes the input u32 to the target location in the framebuffer, nothing is done with the data already stored in the framebuffer.
|-
|OSScreenPutFontEx
|void OSScreenPutFontEx(int bufferNum, uint32_t posX, uint32_t posY, const char *str);
|Write text to the specified buffer; unlike OSFatal() this doesn't halt your system.
|}

== Structures ==
=== Threads ===

{| class="wikitable"
!Name
!Prototype
|-
|OSThread
|
<syntaxhighlight lang="C">
typedef struct {
    char tag[8];                     /* 0x000 "OSContxt" */
    int32_t gpr[32];                 /* 0x008 from OSDumpContext */
    uint32_t cr;                     /* 0x088 from OSDumpContext */
    uint32_t lr;                     /* 0x08c from OSDumpContext */
    uint32_t ctr;                    /* 0x090 from context switch code */
    uint32_t xer;                    /* 0x094 from context switch code */
    uint32_t srr0;                   /* 0x098 from OSDumpContext */
    uint32_t srr1;                   /* 0x09c from OSDumpContext */
    char _unknowna0[0xb8 - 0xa0];
    uint64_t fpr[32];                /* 0x0b8 from OSDumpContext */
    int16_t spinLockCount;           /* 0x1b8 from OSDumpContext */
    char _unknown1ba[0x1bc - 0x1ba]; /* 0x1ba could genuinely be padding? */
    uint32_t gqr[8];                 /* 0x1bc from OSDumpContext */
    char _unknown1dc[0x1e0 - 0x1dc];
    uint64_t psf[32];                /* 0x1e0 from OSDumpContext */
    int64_t coretime[3];             /* 0x2e0 from OSDumpContext */
    int64_t starttime;               /* 0x2f8 from OSDumpContext */
    int32_t error;                   /* 0x300 from OSDumpContext */
    char _unknown304[0x6a0 - 0x304];
} OSThread;                          /* 0x6a0 total length from RAM dumps */
</syntaxhighlight>
|}

==Filesystem==
The FS* functions appear to only be used by regular applications, while the FSA* functions appear to only be used by system rpls.
===Initialization===
{| class="wikitable"
!Name
!Prototype
!Description
!Notes
|-
|FSInit
|<code>void FSInit(void);</code> 
|Initializes the FS library.
|Must be called before anything else! Can be called multiple times safely.
|-
|FSShutdown
|<code>void FSShutdown(void);</code>
|This is just a "return;".
|
|-
|FSAddClient
|<code>FSStatus FSAddClient(FSClient *client, FSRetflag flag);</code>
|Registers a new client for use.
|Returns OK or MAX_CLIENTS(-3). Client size is 0x1700 bytes, should be 0x20 byte padded.
|-
|FSDelClient
|<code>FSStatus FSDelClient(FSClient *client, FSRetflag flag);</code>
|Unregisters an existing client.
|Returns OK. See above for data size.
|-
|FSGetClientNum
|<code>int FSGetClientNum(void);</code>
|Gets the number of registered clients.
|
|}

===Command Blocks===
{| class="wikitable"
!Name
!Prototype
!Description
!Notes
|-
|FSInitCmdBlock
|<code>void FSInitCmdBlock(FSCmdBlock *block);</code>
|Initializes a command block for use.
|Command Block size is 0xA80 bytes, should be 0x20 byte padded.
|-
|FSCancelCommand
|<code>void FSCancelCommand(FSClient *client, FSCmdBlock *block);</code>
|Cancels the pending command
|Cannot cancel an ongoing command, it has to complete.
|-
|FSCancelAllCommands
|<code>void FSCancelAllCommands(FSClient *client);
|Cancels all pending commands for the passed client.
|Cannot cancel an ongoing command, it has to complete.
|-
|FSSetUserData
|<code>void FSSetUserData(FSCmdBlock *block, void *user_data);</code>
|Sets the user data for the passed command block
|
|-
|FSGetUserData
|<code>void* FSGetUserData(FSCmdBlock *block);</code>
|Returns pointer to the user data
|Can return NULL if invalid, please error check.
|-
|FSSetCmdPriority
|<code>void FSSetCmdPriority(FSCmdBlock *block, uint8_t priority);</code>
|Sets the priority for the passed command block
|Priority 0 is highest, 31 is lowest, 16 is default.
|-
|FSGetCmdPriority
|<code>int FSGetCmdPriority(FSCmdBlock *block);</code>
|Gets the priority for the passed command block
|Priority 0 is highest, 31 is lowest, 16 is default.
|-
|FSGetCurrentCmdBlock
|<code>FSCmdBlock* FSGetCurrentCmdBlock(FSClient *client);
|Returns a pointer to the command block being processed.
|May return NULL if invalid client or if nothing's processed, please error check.
|}

===Defines===
<syntaxhighlight lang="C">
#define FS_CLIENT_BUFFER_SIZE   (5888) /* 0x1700 */
#define FS_CMD_BLOCK_SIZE       (2688) /* 0xA80 */

#define FS_STATUS_OK                0 /* Everything looks good */

#define FS_STATUS_BASE              (0)

#define FS_STATUS_CANCELED          (FS_STATUS_BASE - 1)
#define FS_STATUS_END               (FS_STATUS_BASE - 2)

#define FS_STATUS_MAX               (FS_STATUS_BASE - 3)
#define FS_STATUS_ALREADY_OPEN      (FS_STATUS_BASE - 4)
#define FS_STATUS_EXISTS            (FS_STATUS_BASE - 5)
#define FS_STATUS_NOT_FOUND         (FS_STATUS_BASE - 6)
#define FS_STATUS_NOT_FILE          (FS_STATUS_BASE - 7)
#define FS_STATUS_NOT_DIR           (FS_STATUS_BASE - 8)
#define FS_STATUS_ACCESS_ERROR      (FS_STATUS_BASE - 9)
#define FS_STATUS_PERMISSION_ERROR  (FS_STATUS_BASE -10)
#define FS_STATUS_FILE_TOO_BIG      (FS_STATUS_BASE -11)
#define FS_STATUS_STORAGE_FULL      (FS_STATUS_BASE -12)
#define FS_STATUS_JOURNAL_FULL      (FS_STATUS_BASE -13)
#define FS_STATUS_UNSUPPORTED_CMD   (FS_STATUS_BASE -14)

#define FS_STATUS_MEDIA_NOT_READY   (FS_STATUS_BASE -15)
#define FS_STATUS_INVALID_MEDIA     (FS_STATUS_BASE -16)
#define FS_STATUS_MEDIA_ERROR       (FS_STATUS_BASE -17)
#define FS_STATUS_DATA_CORRUPTED    (FS_STATUS_BASE -18)
#define FS_STATUS_WRITE_PROTECTED   (FS_STATUS_BASE -19)

#define FS_STATUS_FATAL_ERROR       (FS_STATUS_BASE -1024)

#define FS_RET_NO_ERROR         0x0000
#define FS_RET_MAX              0x0001
#define FS_RET_ALREADY_OPEN     0x0002
#define FS_RET_EXISTS           0x0004
#define FS_RET_NOT_FOUND        0x0008
#define FS_RET_NOT_FILE         0x0010
#define FS_RET_NOT_DIR          0x0020
#define FS_RET_ACCESS_ERROR     0x0040
#define FS_RET_PERMISSION_ERROR 0x0080
#define FS_RET_FILE_TOO_BIG     0x0100
#define FS_RET_STORAGE_FULL     0x0200
#define FS_RET_UNSUPPORTED_CMD  0x0400
#define FS_RET_JOURNAL_FULL     0x0800

#define FS_ERROR_BASE                   (-196608)           /* 0xFFFD0000 */
#define FS_ERROR_LIB_NOT_INIT           (FS_ERROR_BASE - 1)
#define FS_ERROR_INVALID_CLIENT_HANDLE  (FS_ERROR_BASE -37) /* ??? */

typedef struct {uint8_t buffer[FS_CLIENT_BUFFER_SIZE];} FSClient;
typedef struct {uint8_t buffer[FS_CMD_BLOCK_SIZE];} FSCmdBlock;

typedef enum {
    FS_VOLSTATE_INITIAL = 0,
    FS_VOLSTATE_READY,
	
    FS_VOLSTATE_NO_MEDIA,
	
    FS_VOLSTATE_INVALID_MEDIA,
    FS_VOLSTATE_DIRTY_MEDIA,
    FS_VOLSTATE_WRONG_MEDIA,
    FS_VOLSTATE_MEDIA_ERROR,
    FS_VOLSTATE_DATA_CORRUPTED,
    FS_VOLSTATE_WRITE_PROTECTED,
	
    FS_VOLSTATE_JOURNAL_FULL,
    FS_VOLSTATE_FATAL,
	
    FS_VOLSTATE_INVALID
} FSVolumeState;
</syntaxhighlight>

== Defines ==
=== Disassembler ===
printf_func() and find_symbol() have the following types:
<syntaxhighlight lang="C">
typedef int (*printf_t)(char *fmt, ...);
typedef uint32_t (*find_symbol_t)(uint32_t addr, char *name_buf, int name_len);
</syntaxhighlight>

The flags argument of DisassemblePPCRange() and DisassemblePPCOpcode() is a bitmask of the following options:
<syntaxhighlight lang="C">
#define DISASM_OMIT_ADDR      0x40     /* Don't print the address of the instruction */
#define DISASM_OMIT_OPCODE    0x80     /* Don't print the opcode of the instruction */
#define DISASM_GETSYM         0x100    /* Print the nearest symbol and the instruction's offset from it */
</syntaxhighlight>

=== Screen ===
{| class="wikitable"
!Name
!Value
!Description
|-
|SCREEN_BUF_TV
|0
|The buffer number for the TV
|-
|SCREEN_BUF_DRC0
|1
|The buffer number for the first Gamepad
|}