IPC - Revision history

Dropbear at 09:41, 21 April 2025

2025-04-21T07:41:54Z

← Older revision		Revision as of 11:41, 21 April 2025
Line 5:		Line 5:
	=== Sessions ===		=== Sessions ===

	Sessions are communication channels consisting of a client and server, through which data can be exchanged in the form of a request and response, respectively. Through sessions, the standard [[#~~Command~~ Structure\|IPC command protocol]] is implemented. Clients use their client session handle to send IPC commands to the server using svcSendSyncRequest, while servers use svcReplyAndReceive to reply. Client sessions can't be used with svcReplyAndReceive. In both cases, the kernel takes care of transferring IPC command data from the [[Thread Local Storage]] of the sending thread to the TLS of the receiving thread. Sessions can be created through svcCreateSession, which provides the caller with the client and server handles.		Sessions are communication channels consisting of a client and server, through which data can be exchanged in the form of a request and response, respectively. Through sessions, the standard [[#Message Structure\|IPC command protocol]] is implemented. Clients use their client session handle to send IPC commands to the server using svcSendSyncRequest, while servers use svcReplyAndReceive to reply. Client sessions can't be used with svcReplyAndReceive. In both cases, the kernel takes care of transferring IPC command data from the [[Thread Local Storage]] of the sending thread to the TLS of the receiving thread. Sessions can be created through svcCreateSession, which provides the caller with the client and server handles.

	Sessions are used in their raw form to implement [[FS:OpenFile\|file handles]]. In this case, fs-module creates a raw session using svcCreateSession, and provides the "fs:USER" client with the resulting client session handle, keeping the server session handle for its own use. These sessions expose their [[Filesystem services#File service\|own set of IPC commands]] which act on the file that was opened through fs:USER.		Sessions are used in their raw form to implement [[FS:OpenFile\|file handles]]. In this case, fs-module creates a raw session using svcCreateSession, and provides the "fs:USER" client with the resulting client session handle, keeping the server session handle for its own use. These sessions expose their [[Filesystem services#File service\|own set of IPC commands]] which act on the file that was opened through fs:USER.

Kynex7510 at 13:07, 19 January 2025

2025-01-19T12:07:30Z

← Older revision		Revision as of 15:07, 19 January 2025
Line 99:		Line 99:
	\|-		\|-
	\| 4		\| 4
	\| If set, the handles are closed for the caller~~. Interaction with bit5 unknown~~.		\| If set, the handles are closed for the caller.
	\|-		\|-
	\| 5		\| 5
Line 108:		Line 108:
	\|}		\|}

	Usage examples:		Setting both bit4 and bit5 causes a kernel panic. Usage examples:

	{\| class="wikitable" border="1"		{\| class="wikitable" border="1"
	\|-		\|-

Sorunome: /* Buffer Mapping Translation */ correct incorrect statement

2024-12-01T20:07:23Z

Buffer Mapping Translation: correct incorrect statement

← Older revision		Revision as of 23:07, 1 December 2024
Line 219:		Line 219:
	\| 0x0000000E <nowiki>\|</nowiki> (size<<4)		\| 0x0000000E <nowiki>\|</nowiki> (size<<4)
	<ptr>		<ptr>
	\| The corresponding value contains a ptr to a buffer of said size. The buffer specified by the source process must have read permission during cmd-request handling(write permission is checked during cmd-reply handling for the original buffer). ~~This isn't known~~ to ~~be used by any processes~~. When handling command requests this is handled the same way as 0x0000000A, and for handling command replies this is handled the same way as 0x0000000C(besides the descriptor type written into the dst cmdbuf for both of these).		\| The corresponding value contains a ptr to a buffer of said size. The buffer specified by the source process must have read permission during cmd-request handling(write permission is checked during cmd-reply handling for the original buffer). Some calls like [[CECDU:WriteMessageWithHMAC]] use it, however it is unsure as to why. When handling command requests this is handled the same way as 0x0000000A, and for handling command replies this is handled the same way as 0x0000000C(besides the descriptor type written into the dst cmdbuf for both of these).
	\|}		\|}

Tekito256: Fix source code missing

2023-10-21T07:33:02Z

Fix source code missing

← Older revision		Revision as of 11:33, 21 October 2023
Line 267:		Line 267:

	while (true) {		while (true) {
	Result res = svcReplyAndReceive(&requesting_index, &handles, 1 + connected_clients, reply_target);		Result res = svcReplyAndReceive(&requesting_index, handles, 1 + connected_clients, reply_target);

	if (res == 0xC920181A) {		if (res == 0xC920181A) {

Piepie62: Fix PXI buffer size shift

2020-02-27T18:07:11Z

Fix PXI buffer size shift

← Older revision		Revision as of 21:07, 27 February 2020
Line 231:		Line 231:
	\|-		\|-
	\| 2		\| 2
	\| 0x00000004 <nowiki>\|</nowiki> (size<<14) <nowiki>\|</nowiki> (static_buffer_id<<4)		\| 0x00000004 <nowiki>\|</nowiki> (size<<8) <nowiki>\|</nowiki> (static_buffer_id<<4)
	<ptr>		<ptr>
	\| This is typically used for RW buffers over PXI, but any process can use this. The address written to the destination cmd-buf is a phys-addr for a table located in the corresponding static buffer of the receiving process (which must be provided by the latter, otherwise the kernel dereferences NULL). Each static buffer needs to be page-aligned and musn't exceed a page's length (kernelpanic otherwise). This table contains the phys-addrs for the actual data, the array entries have the following format: {u32 *datachunk_physaddr, u32 datachunk_bytesize}.		\| This is typically used for RW buffers over PXI, but any process can use this. The address written to the destination cmd-buf is a phys-addr for a table located in the corresponding static buffer of the receiving process (which must be provided by the latter, otherwise the kernel dereferences NULL). Each static buffer needs to be page-aligned and musn't exceed a page's length (kernelpanic otherwise). This table contains the phys-addrs for the actual data, the array entries have the following format: {u32 *datachunk_physaddr, u32 datachunk_bytesize}.
	\|-		\|-
	\| 3		\| 3
	\| 0x00000006 <nowiki>\|</nowiki> (size<<14) <nowiki>\|</nowiki> (static_buffer_id<<4)		\| 0x00000006 <nowiki>\|</nowiki> (size<<8) <nowiki>\|</nowiki> (static_buffer_id<<4)
	<ptr>		<ptr>
	\| Same as above except for read-only buffer. Prior(?) to the kernel version which implemented memory-permission checking for PXI buffers, this was unused and hence triggered a kernelpanic.		\| Same as above except for read-only buffer. Prior(?) to the kernel version which implemented memory-permission checking for PXI buffers, this was unused and hence triggered a kernelpanic.

Jroweboy: spelling

2017-06-24T01:36:46Z

spelling

← Older revision		Revision as of 05:36, 24 June 2017
Line 250:		Line 250:

	In a single operation, sends a IPC reply and waits for a new request. <code>handles</code> should be a pointer to an array of <code>handleCount</code> handles.<sup>TODO: Are only port/session handles supported?</sup>		In a single operation, sends a IPC reply and waits for a new request. <code>handles</code> should be a pointer to an array of <code>handleCount</code> handles.<sup>TODO: Are only port/session handles supported?</sup>
	<code>replyTarget</code> should contain a handle to the session to send the reply to. (This us usually the session from which we received the previous request.)		<code>replyTarget</code> should contain a handle to the session to send the reply to. (This is usually the session from which we received the previous request.)
	If <code>replyTarget</code> is 0, no reply and the call will simply wait for an incoming event.<sup>TODO: It doesn't seem like the 0xFFFF0000 command id mentioned in the above sections is necessary, but needs confirmation.</sup>		If <code>replyTarget</code> is 0, no reply and the call will simply wait for an incoming event.<sup>TODO: It doesn't seem like the 0xFFFF0000 command id mentioned in the above sections is necessary, but needs confirmation.</sup>

Yuriks: Add some usage info for svcReplyAndReceive

2017-06-20T04:08:33Z

Add some usage info for svcReplyAndReceive

← Older revision		Revision as of 08:08, 20 June 2017
Line 240:		Line 240:
	\| Same as above except for read-only buffer. Prior(?) to the kernel version which implemented memory-permission checking for PXI buffers, this was unused and hence triggered a kernelpanic.		\| Same as above except for read-only buffer. Prior(?) to the kernel version which implemented memory-permission checking for PXI buffers, this was unused and hence triggered a kernelpanic.
	\|}		\|}


			== SVCs ==

			=== svcReplyAndReceive ===

			'''Signature:'''
			Result ReplyAndReceive(s32* index, Handle* handles, s32 handleCount, Handle replyTarget)

			In a single operation, sends a IPC reply and waits for a new request. <code>handles</code> should be a pointer to an array of <code>handleCount</code> handles.<sup>TODO: Are only port/session handles supported?</sup>
			<code>replyTarget</code> should contain a handle to the session to send the reply to. (This us usually the session from which we received the previous request.)
			If <code>replyTarget</code> is 0, no reply and the call will simply wait for an incoming event.<sup>TODO: It doesn't seem like the 0xFFFF0000 command id mentioned in the above sections is necessary, but needs confirmation.</sup>

			Upon returning, <code>index</code> will contain an index into <code>handles</code> specifying which object changed state.
			If it's a server port endpoint, it means that there is a new incoming connection on that port which should be accepted using svcAcceptSession.
			If it's a server session endpoint it means that we received a request from that session and should process and then reply to it by calling svcReplyAndReceive again with <code>replyTarget</code> set to that session's handle.

			An example of a server svcReplyAndReceive loop is:

			#define MAX_CLIENTS 4
			Handle server_port = ...;
			s32 requesting_index;
			Handle handles[1 + MAX_CLIENTS] = { server_port };
			s32 connected_clients = 0;
			Handle reply_target = 0;

			while (true) {
			Result res = svcReplyAndReceive(&requesting_index, &handles, 1 + connected_clients, reply_target);

			if (res == 0xC920181A) {
			// Session was closed by remote
			// TODO: Handle disconnects
			reply_target = 0;
			continue;
			}

			if (requesting_index == 0) {
			// New connection in server_port
			ASSERT(connected_client < MAX_CLIENTS);
			svcAcceptSession(&handles[1 + connected_clients++], server_port);
			reply_target = 0;
			continue;
			}

			reply_target = handles[requesting_index];

			// Handle command here and write reply to command buffer
			}

Yuriks: Fix heading levels ("Skip Level 1, it is page name level." https://www.mediawiki.org/wiki/Help:Formatting)

2017-06-20T03:45:05Z

Fix heading levels ("Skip Level 1, it is page name level." https://www.mediawiki.org/wiki/Help:Formatting)

← Older revision		Revision as of 07:45, 20 June 2017
Line 1:		Line 1:
	The 3DS software stack follows a server/client architecture, where common functionality is provided by global server processes through interfaces called ''ports'' and ''services''. Applications can access this functionality by creating ''sessions'' to the provided services. Technically, this is implemented using ''interprocess communication'' (IPC).		The 3DS software stack follows a server/client architecture, where common functionality is provided by global server processes through interfaces called ''ports'' and ''services''. Applications can access this functionality by creating ''sessions'' to the provided services. Technically, this is implemented using ''interprocess communication'' (IPC).

	= Concepts =		== Concepts ==

	== Sessions ==		=== Sessions ===

	Sessions are communication channels consisting of a client and server, through which data can be exchanged in the form of a request and response, respectively. Through sessions, the standard [[#Command Structure\|IPC command protocol]] is implemented. Clients use their client session handle to send IPC commands to the server using svcSendSyncRequest, while servers use svcReplyAndReceive to reply. Client sessions can't be used with svcReplyAndReceive. In both cases, the kernel takes care of transferring IPC command data from the [[Thread Local Storage]] of the sending thread to the TLS of the receiving thread. Sessions can be created through svcCreateSession, which provides the caller with the client and server handles.		Sessions are communication channels consisting of a client and server, through which data can be exchanged in the form of a request and response, respectively. Through sessions, the standard [[#Command Structure\|IPC command protocol]] is implemented. Clients use their client session handle to send IPC commands to the server using svcSendSyncRequest, while servers use svcReplyAndReceive to reply. Client sessions can't be used with svcReplyAndReceive. In both cases, the kernel takes care of transferring IPC command data from the [[Thread Local Storage]] of the sending thread to the TLS of the receiving thread. Sessions can be created through svcCreateSession, which provides the caller with the client and server handles.
Line 9:		Line 9:
	Sessions are used in their raw form to implement [[FS:OpenFile\|file handles]]. In this case, fs-module creates a raw session using svcCreateSession, and provides the "fs:USER" client with the resulting client session handle, keeping the server session handle for its own use. These sessions expose their [[Filesystem services#File service\|own set of IPC commands]] which act on the file that was opened through fs:USER.		Sessions are used in their raw form to implement [[FS:OpenFile\|file handles]]. In this case, fs-module creates a raw session using svcCreateSession, and provides the "fs:USER" client with the resulting client session handle, keeping the server session handle for its own use. These sessions expose their [[Filesystem services#File service\|own set of IPC commands]] which act on the file that was opened through fs:USER.

	== Ports ==		=== Ports ===

	Ports are interfaces for managing multiple client sessions to the same high-level server. Ports are created through svcCreatePort, and can be global or private. A global port is created by passing a name for the port to svcCreatePort. Clients can start IPC sessions to global ports by connecting to the port using svcConnectToPort, passing the desired port name. If the port is private, it is not possible to create a session through svcConnectToPort - sessions can only be created if one has a handle to the port itself, obtained from the call to svcCreatePort. When a client wishes to connect to a port (i.e. create a session), the server must accept the new session using svcAcceptSession. The kernel notifies the server whenever a new session is incoming via the server's port handle. The server can wait for this notification through svcWaitSynchronization or svcReplyAndReceive.		Ports are interfaces for managing multiple client sessions to the same high-level server. Ports are created through svcCreatePort, and can be global or private. A global port is created by passing a name for the port to svcCreatePort. Clients can start IPC sessions to global ports by connecting to the port using svcConnectToPort, passing the desired port name. If the port is private, it is not possible to create a session through svcConnectToPort - sessions can only be created if one has a handle to the port itself, obtained from the call to svcCreatePort. When a client wishes to connect to a port (i.e. create a session), the server must accept the new session using svcAcceptSession. The kernel notifies the server whenever a new session is incoming via the server's port handle. The server can wait for this notification through svcWaitSynchronization or svcReplyAndReceive.
Line 15:		Line 15:
	The two global ports usually found on retail are "srv:" ([[Services\|service manager]]) and "err:f" ([[ErrDisp]]).		The two global ports usually found on retail are "srv:" ([[Services\|service manager]]) and "err:f" ([[ErrDisp]]).

	== Services ==		=== Services ===

	Services are an abstraction of ports that are managed by service manager. Services cannot be connected to through svcConnectToPort, as the underlying port is a private port. The service name is instead entirely handled by service manager, and the kernel is not aware of it. Clients are instead expected to open a session to a service using the "srv:" port command [[SRV:GetServiceHandle\|GetServiceHandle]]. The client process must pass an access permission check for each service (by name) that it attempts to request a session with. These permissions are granted in the "service access control" of the title's [[NCCH/Extended Header#ARM11 Local System Capabilities\|extended header]]. A service is registered with service manager using the command [[SRV:RegisterService\|RegisterService]].		Services are an abstraction of ports that are managed by service manager. Services cannot be connected to through svcConnectToPort, as the underlying port is a private port. The service name is instead entirely handled by service manager, and the kernel is not aware of it. Clients are instead expected to open a session to a service using the "srv:" port command [[SRV:GetServiceHandle\|GetServiceHandle]]. The client process must pass an access permission check for each service (by name) that it attempts to request a session with. These permissions are granted in the "service access control" of the title's [[NCCH/Extended Header#ARM11 Local System Capabilities\|extended header]]. A service is registered with service manager using the command [[SRV:RegisterService\|RegisterService]].
Line 23:		Line 23:
	The majority of 3DS inter-process communication is implemented as services.		The majority of 3DS inter-process communication is implemented as services.

	== Shared Memory ==		=== Shared Memory ===

	Communication through port/service requests and replies may incur a big bottleneck when exchanging large amounts of data because the kernel needs to transfer the data between the two involved processes. There is hence a complementary feature to share the same physical memory between two processes. For this purpose, one process needs to create a block of shared memory using svcCreateMemoryBlock such that the other process can map it into its own virtual memory address space using svcMapMemoryBlock. The memory block handle for the latter is provided using a regular IPC command.		Communication through port/service requests and replies may incur a big bottleneck when exchanging large amounts of data because the kernel needs to transfer the data between the two involved processes. There is hence a complementary feature to share the same physical memory between two processes. For this purpose, one process needs to create a block of shared memory using svcCreateMemoryBlock such that the other process can map it into its own virtual memory address space using svcMapMemoryBlock. The memory block handle for the latter is provided using a regular IPC command.
Line 29:		Line 29:
	Many services use shared memory as a secondary command interface (e.g. [[GSP_Shared_Memory\|GSP]]), the processing of which is triggered through an IPC request (cf. [[GSPGPU:TriggerCmdReqQueue]]).		Many services use shared memory as a secondary command interface (e.g. [[GSP_Shared_Memory\|GSP]]), the processing of which is triggered through an IPC request (cf. [[GSPGPU:TriggerCmdReqQueue]]).

	= Message Structure =		== Message Structure ==

	IPC requests are written to the [[Thread Local Storage]] at offset 0x80 and submitted using [[SVC\|svcSendSyncRequest]]. If the kernel was able to dispatch the request, the server reply will be written to TLS+0x80 before svcSendSyncRequest returns. By convention, the second word of the response data is an error code (or 0 on success). IPC requests and IPC replies follow the same structure.		IPC requests are written to the [[Thread Local Storage]] at offset 0x80 and submitted using [[SVC\|svcSendSyncRequest]]. If the kernel was able to dispatch the request, the server reply will be written to TLS+0x80 before svcSendSyncRequest returns. By convention, the second word of the response data is an error code (or 0 on success). IPC requests and IPC replies follow the same structure.
Line 90:		Line 90:
	For replies, only 0, 1, 5, 6, 7 are allowed. In other words any type 2 fields must be zeroed before calling svcReplyAndReceive on the server-side. For replies, type 0, 1, and 2 are ignored. Types 5, 6, and 7 do something with the mem pointer upon reply. The type 0 descriptor can be used to ignore parameters. The number of parameters covered by a type-0 descriptor is (desc >> 26) + 1.		For replies, only 0, 1, 5, 6, 7 are allowed. In other words any type 2 fields must be zeroed before calling svcReplyAndReceive on the server-side. For replies, type 0, 1, and 2 are ignored. Types 5, 6, and 7 do something with the mem pointer upon reply. The type 0 descriptor can be used to ignore parameters. The number of parameters covered by a type-0 descriptor is (desc >> 26) + 1.

	== Handle Translation ==		=== Handle Translation ===

	Translation type 0 is used to send handles across processes. The corresponding translation descriptor has the following structure:		Translation type 0 is used to send handles across processes. The corresponding translation descriptor has the following structure:
Line 135:		Line 135:
	\|}		\|}

	== Static Buffer Translation ==		=== Static Buffer Translation ===

	Each thread may set up up to 16 static buffer descriptors in their [[Thread Local Storage]] at offset 0x180. These contain information about buffers in the thread's memory space that may be used for information exchange for communication with other processes. In particular, a static buffer descriptor encodes the address and size of a buffer.		Each thread may set up up to 16 static buffer descriptors in their [[Thread Local Storage]] at offset 0x180. These contain information about buffers in the thread's memory space that may be used for information exchange for communication with other processes. In particular, a static buffer descriptor encodes the address and size of a buffer.
Line 171:		Line 171:
	\|}		\|}

	== Buffer Mapping Translation ==		=== Buffer Mapping Translation ===

	The IPC subsystem can temporarily map a whole buffer of the sender's memory into the receiver's memory space. This is useful for large buffers, for which the overhead of copying static buffer data around would be too expensive.		The IPC subsystem can temporarily map a whole buffer of the sender's memory into the receiver's memory space. This is useful for large buffers, for which the overhead of copying static buffer data around would be too expensive.
Line 222:		Line 222:
	\|}		\|}

	== Usage Examples for other Translation Types ==		=== Usage Examples for other Translation Types ===

	{\| class="wikitable" border="1"		{\| class="wikitable" border="1"

Yellows8: /* Sessions */

2017-02-09T15:41:47Z

Sessions

← Older revision		Revision as of 18:41, 9 February 2017
Line 5:		Line 5:
	== Sessions ==		== Sessions ==

	Sessions are communication channels consisting of a client and server, through which data can be exchanged in the form of a request and response, respectively. Through sessions, the standard [[#Command Structure\|IPC command protocol]] is implemented. Clients use their client session handle to send IPC commands to the server using svcSendSyncRequest, while servers use svcReplyAndReceive to reply. In both cases, the kernel takes care of transferring IPC command data from the [[Thread Local Storage]] of the sending thread to the TLS of the receiving thread. Sessions can be created through svcCreateSession, which provides the caller with the client and server handles.		Sessions are communication channels consisting of a client and server, through which data can be exchanged in the form of a request and response, respectively. Through sessions, the standard [[#Command Structure\|IPC command protocol]] is implemented. Clients use their client session handle to send IPC commands to the server using svcSendSyncRequest, while servers use svcReplyAndReceive to reply. Client sessions can't be used with svcReplyAndReceive. In both cases, the kernel takes care of transferring IPC command data from the [[Thread Local Storage]] of the sending thread to the TLS of the receiving thread. Sessions can be created through svcCreateSession, which provides the caller with the client and server handles.

	Sessions are used in their raw form to implement [[FS:OpenFile\|file handles]]. In this case, fs-module creates a raw session using svcCreateSession, and provides the "fs:USER" client with the resulting client session handle, keeping the server session handle for its own use. These sessions expose their [[Filesystem services#File service\|own set of IPC commands]] which act on the file that was opened through fs:USER.		Sessions are used in their raw form to implement [[FS:OpenFile\|file handles]]. In this case, fs-module creates a raw session using svcCreateSession, and provides the "fs:USER" client with the resulting client session handle, keeping the server session handle for its own use. These sessions expose their [[Filesystem services#File service\|own set of IPC commands]] which act on the file that was opened through fs:USER.

Yellows8: /* Buffer Mapping Translation */

2016-12-15T15:02:08Z

Buffer Mapping Translation

← Older revision		Revision as of 18:02, 15 December 2016
Line 178:		Line 178:

	Buffers will get mapped at virtual address 0x04000000+ in the destination process. When this translation descriptor is submitted to the kernel through svcReplyAndReceive, the given buffer will be unmapped from the sending process(otherwise the buffer will be left mapped after the cmd-reply is finished). Regardless of the descriptor used here, the MMU-table entries for the source-process(from svcSendSyncRequest) buffers are not changed: memory permissions are left at the original while commands are being processed. The memory permissions for buffers at 0x04000000+ is always RW-, regardless of the actual memory permissions for the source-process buffer. Bitmask 0xFFF(low 12-bits) of the start address of each buffer for 0x04000000+ is the same as bitmask 0xFFF from the source-process buffer address.		Buffers will get mapped at virtual address 0x04000000+ in the destination process. When this translation descriptor is submitted to the kernel through svcReplyAndReceive, the given buffer will be unmapped from the sending process(otherwise the buffer will be left mapped after the cmd-reply is finished). Regardless of the descriptor used here, the MMU-table entries for the source-process(from svcSendSyncRequest) buffers are not changed: memory permissions are left at the original while commands are being processed. The memory permissions for buffers at 0x04000000+ is always RW-, regardless of the actual memory permissions for the source-process buffer. Bitmask 0xFFF(low 12-bits) of the start address of each buffer for 0x04000000+ is the same as bitmask 0xFFF from the source-process buffer address.

			The buffer address written into the destination cmdbuf by the kernel with svcSendSyncRequest is the allocated 0x04000000+ buffer. When doing the same with svcSendSyncRequest, the buffer address is the same one from the source cmdbuf(0x04000000+).

	The first and last pages of the buffer at 0x04000000+ are allocated under the BASE memregion(with data being copied to/from the original source-process buffer as needed), with the rest being mapped to the original buffer physmem. When the source-process buffer is 0x1000-byte aligned, the first page for 0x04000000+ is mapped directly into the original buffer physmem instead of allocating BASE memory(likewise for the last page when the buffer size is 0x1000-byte aligned).		The first and last pages of the buffer at 0x04000000+ are allocated under the BASE memregion(with data being copied to/from the original source-process buffer as needed), with the rest being mapped to the original buffer physmem. When the source-process buffer is 0x1000-byte aligned, the first page for 0x04000000+ is mapped directly into the original buffer physmem instead of allocating BASE memory(likewise for the last page when the buffer size is 0x1000-byte aligned).