View source for IPC (SDK)

'''IPC''' is the [[SDK]] library that provides functions for communication with [[IOS]]. It seems to also mirror some [[IOS/Syscalls|IOS syscalls]], suggesting that IOS was originally planned to run on the [[Broadway]].

== Public functions ==
{| class="wikitable sortable"
! Signature
! Description
|-
| <code>int IPCCltInit(void)</code>
| Initializes the library. Returns an error code.
|-
| <code>int IOS_OpenAsync(char *path, int mode, void (*callback)(int, void *), void *userData)</code>
| Calls IOS_Open, calling <code>callback</code> when a response is received. May return an error code if something fails before sending the request. Unlike the IOS syscall, this does not block, although because the IPC thread in IOS blocks, no other requests will go through until the device is opened.
|-
| <code>int IOS_Open(char *path, int mode)</code>
| Calls IOS_Open and blocks until a response is received. Returns an error code, or an FD for the opened file.
|-
| <code>int IOS_CloseAsync(int fd, void (*callback)(int, void *), void *userData)</code>
| Calls IOS_Close, calling <code>callback</code> when a response is received. May return an error code if something fails before sending the request.
|-
| <code>int IOS_Close(int fd)</code>
| Calls IOS_Close and blocks until a response is received. Returns an error code.
|-
| <code>int IOS_ReadAsync(int fd, char *data, int len, void (*callback)(int, void *), void *userData)</code>
| Calls IOS_Read, calling <code>callback</code> when a response is received. May return an error code if something fails before sending the request.
|-
| <code>int IOS_Read(int fd, char *data, int len)</code>
| Calls IOS_Read and blocks until a response is received. Returns an error code.
|-
| <code>int IOS_WriteAsync(int fd, char *data, int len, void (*callback)(int, void *), void *userData)</code>
| Calls IOS_Write, calling <code>callback</code> when a response is received. May return an error code if something fails before sending the request.
|-
| <code>int IOS_Write(int fd, char *data, int len)</code>
| Calls IOS_Write and blocks until a response is received. Returns an error code.
|-
| <code>int IOS_SeekAsync(int fd, int offset, SeekMode mode, void (*callback)(int, void *), void *userData)</code>
| Calls IOS_Seek, calling <code>callback</code> when a response is received. May return an error code if something fails before sending the request.
|-
| <code>int IOS_IoctlAsync(int fd, int request, char *in, int inSize, char *out, int outSize, void (*callback)(int, void *), void *userData)</code>
| Calls IOS_Ioctl, calling <code>callback</code> when a response is received. May return an error code if something fails before sending the request.
|-
| <code>int IOS_Ioctl(int fd, int request, char *in, int inSize, char *out, int outSize)</code>
| Calls IOS_Ioctl and blocks until a response is received. Returns an error code.
|-
| <code>int IOS_IoctlvAsync(int fd, int request, int inCount, int ioCount, struct IOVector *vectors, void (*callback)(int, void *), void *userData)</code>
| Calls IOS_Ioctlv, calling <code>callback</code> when a response is received. May return an error code if something fails before sending the request.
|-
| <code>int IOS_Ioctlv(int fd, int request, int inCount, int ioCount, struct IOVector *vectors)</code>
| Calls IOS_Ioctlv and blocks until a response is received. Returns an error code.
|-
| <code>int IOS_IoctlvReboot(int fd, int request, int inCount, int ioCount, struct IOVector *vectors)</code>
| Calls IOS_Ioctlv, but expects 2 acknowledgements instead of 1. Exclusively used by ES_LaunchTitle, where an acknowledgement is received from both the old IOS and the new IOS.
|-
| <code>int iosCreateHeap(void *ptr, int size)</code>
| Creates a heap and returns the <code>heapId</code>.
|-
| <code>void *iosAllocAligned(int heapId, int size, int align)</code>
| Allocates <code>size</code> bytes from heap <code>heapId</code>, plus however many are needed for the base pointer to be aligned to <code>align</code> bytes. <code>align</code> must be a power of 2. Returns the base pointer.
|-
| <code>int iosFree(int heapId, void *ptr)</code>
| Frees <code>ptr</code> back into heap <code>heapId</code>. Returns an error code.
|}

== Error codes ==
In addition to these error codes, any error returned by IOS can be returned from a blocking function.

{| class="wikitable sortable"
! Number
! Description
|-
| 0
| No error. This is returned from async functions if the request was successfully sent.
|-
| -4
| General memory error. Returned when there is not enough stack space, or when improperly freeing memory.
|-
| -22
| Not enough memory in the heap
|}

All of the IPC functions include code to return error -4 if the heap does not have enough memory, but the error -22 code takes priority over it; this probably means error -22 was added later.

== Message wrapper ==
IPC wraps IOS messages around a wrapper to store user data.

<pre>
struct IOSRequestWrapper {
	struct IOSRequest request;
	void (*callback)(int, void *); // NULL for synchronous requests
	void *userData; // NULL for synchronous requests
	u32 relaunch; // always 0 or 1
	struct OSThreadQueue waitingQueue;
	u32 padding[3]; // pad to 0x40 so this struct can be 32-aligned
}
</pre>

== Memory allocation ==
Memory used by IPC and [[NAND (SDK)|NAND]] is mainly allocated with <code>iosAllocAligned</code>, which allocates from one of 8 heaps, each with the following structure:
<pre>
struct HeapBlockHeader {
	u16 magic;                    // always 0xbabe
	u16 status;                   // 0 means free, 1 means it is allocated, 2 means it is an aligned alias for another block stored in prev.
	u32 size;
	struct HeapBlockHeader *prev; // NULL for the beginning of the heap or for status 1, points to the main block for status 2.
	struct HeapBlockHeader *next; // NULL for the end of the heap or if this heap block is allocated
}

struct Heap {
	void *base;
	u32 owner; // See note below
	u32 size;
	struct HeapBlockHeader *freeList;
}
</pre>

<code>processId</code> is probably only present to match the struct used by IOS; it is never set or checked by IPC, but it may be used by IOS's memory management.

[[Category:SDK]]