RetailOS - Revision history

760ceb3b9c0ba4872cadf3ce35a7a494: update display title to retailOS

2025-06-21T04:39:46Z

update display title to retailOS

← Older revision		Revision as of 04:39, 21 June 2025
Line 1:		Line 1:
			{{DISPLAYTITLE:retailOS}}
	The stock operating system running on non-iOS iPods. It runs everything from device drivers to the clickwheel user interface.		The stock operating system running on non-iOS iPods. It runs everything from device drivers to the clickwheel user interface.

760ceb3b9c0ba4872cadf3ce35a7a494: /* Security */

2025-06-21T04:39:24Z

Security

← Older revision		Revision as of 04:39, 21 June 2025
Line 13:		Line 13:
	== Security ==		== Security ==

	As evidenced by the success of the [[Notes vulnerability]], ~~at least up to Nano 4G there was~~ no ~~kind of~~ security hardening, and in fact all processes, including games, seem to be running in ARM system mode~~. This should make exploitation of newer retailOS bugs trivial~~.		As evidenced by the success of the [[Notes vulnerability]] and [[ipod_sun]], retailOS has no security hardening, and in fact all processes, including games, seem to be running in ARM system mode.

	=== Boot chain ===		=== Boot chain ===

LemonJesus: add a RTXC 3.2 training manual I found on archive.org

2024-05-09T19:44:04Z

add a RTXC 3.2 training manual I found on archive.org

← Older revision		Revision as of 19:44, 9 May 2024
Line 444:		Line 444:

	* [https://web.archive.org/web/19990220054659/http://www.rtxc.com/Products/RTXC/Services.htm RTXC Kernel Services (1999)]		* [https://web.archive.org/web/19990220054659/http://www.rtxc.com/Products/RTXC/Services.htm RTXC Kernel Services (1999)]
			* [https://archive.org/details/manualzilla-id-5752851 RTXC 3.2 Training Manual]

LemonJesus: Un-dead the Twitter link talking about Pixo.

2024-05-09T19:31:34Z

Un-dead the Twitter link talking about Pixo.

← Older revision		Revision as of 19:31, 9 May 2024
Line 9:		Line 9:
	retailOS is a small, embedded, single-user, single-binary, real time operating system. With time it acquire more and more complex functionality, like PowerVR drivers and being able to load external applications ('eApps') which are used for games.		retailOS is a small, embedded, single-user, single-binary, real time operating system. With time it acquire more and more complex functionality, like PowerVR drivers and being able to load external applications ('eApps') which are used for games.

	The core of the system is based on RTXC 3.2, with the end-user interface based on intellectual property from a company called Pixo. <ref>https://twitter.com/johnwhitley/status/1451952369248264201</ref>		The core of the system is based on RTXC 3.2, with the end-user interface based on intellectual property from a company called Pixo. <ref>https://web.archive.org/web/20230224105131/https://twitter.com/johnwhitley/status/1451952369248264201</ref>

	== Security ==		== Security ==

Q3k at 13:38, 22 October 2023

2023-10-22T13:38:13Z

← Older revision		Revision as of 13:38, 22 October 2023
Line 28:		Line 28:

	We have found some 'secret' options that can be set by creating specially named files. See [[RetailOS_Options\|Options]].		We have found some 'secret' options that can be set by creating specially named files. See [[RetailOS_Options\|Options]].

			== Analysis / Memory Layout ==

			Loading RetailOS correctly into a decompiler/disassembler is tricky, as the contents of the IMG1 image are a binary blob which self-relocates to the correct places in memory.

			These are the memory segments within RetailOS that we know of (at least on Nano 5G):

			{\| class="wikitable"
			\|-
			! Name !! Marker !! Location in memory !! Description
			\|-
			\| sram.text \|\| n/a \|\| SRAM 0x22000000 \|\| SRAM-resident code, most of RTXC lives here.
			\|-
			\| sram.bss \|\| n/a \|\| SRAM 0x22030000 \|\| SRAM-resident zero data.
			\|-
			\| sram.data \|\| n/a \|\| SRAM 0x22030000 + sram_bss_size \|\| SRAM-resident data.
			\|-
			\| dram.textdata \|\| hibe \|\| DRAM 0x08000000 \|\| Combined .text and .data which lives in DRAM. Bulk of code lives here.
			\|-
			\| dram.frameworks \|\| miscTBD \|\| DRAM 0x08000000 + dram_textdata_size \|\| 'Framework' system of some kind, interfaces used by eApps.
			\|-
			\| dram.bss \|\| n/a \|\| DRAM 0x08000000 + dram_textdata_size + dram_frameworks_size \|\| DRAM-resident zero data.
			\|}

			And here's how the segments are built up within the RetailOS binary blob:

			{\| class="wikitable"
			\|-
			! Address !! Name !! Size
			\|-
			\| Start \|\| sram.text \|\| sram_text_size
			\|-
			\| \|\| sram.bss \|\| sram_bss_size
			\|-
			\| \|\| sram.data \|\| sram_data_size
			\|-
			\| \|\| dram.text \|\| dram_text_size
			\|-
			\| End \|\| dram.frameworks \|\| dram_frameworks_size
			\|}

			(yes, the firmware blob ships a sram.bss physically in the file)

			So the goal to be able to load the binary is to figure out the segment sizes and then load them into a decompiler/disassembler.

			Here, we'll show how to figure out the segment sizes for N5G. First, load the RetailOS body (without the header!) at 0x22000000 in a decompiler. We load it there (intead of into DRAM as it is done on the device) as the stub relocates to this address first by performing the SRAM .text/.data copies very early in the process, and the code is position independent for only a short time.

			Then, look at the start function (follow the reset vector):

			<pre>
			void start(void) { // 0x2200505c
			offs = relocation_offset();
			/* ... peeks/pokes to bus matrix periph at 0x3ff00000 ... */
			if (offs != 0) {
			relocate(offs);
			}
			(*0x22000000) = 0xea000007;
			zero_bss();
			}
			</pre>

			relocation_offset will return 0 if the stub is already at 0x22000000, so will return 0 for the way we've loaded it. On a real device, this will be 0x22000000 - 0x08000000 ==
			0x1a000000, as the real device loads RetailOS into DRAM first. Thus, relocate() will be called:

			<pre>
			void relocate(int offs) { // 0x22005ec8
			int iVar1 = -offs;
			void *blob_start = iVar1 + 0x22000000;
			memmove(0x22000000, blob_start, 0xe27c); // copy sram.text
			memzero(0x22000000 + 0xe27c, 0xbc4); // zero out sram.bss within blob
			memmove(0x22030000, 0x22000000 + 0xe27c + iVar1, 0x20000); // copy sram.bss + sram.data
			jump_offset(offs);
			memmove(0x08000000, 0x22000000 + 0xe27c + 0x20000 + iVar1, 0x6c3768); // copy dram.textdata
			memmove(0x08000000 + 0x6c3768, iVar1 + 0x22000000 + 0xe27c + 0x20000 + 0x6c3768), 0xc40); // copy dram.frameworks
			start();
			return;
			}
			</pre>

			The above listing shows reconstituted address calculations - in a plain decompilation, all the additions will of course be simplified to a single constant. But you should be able to figure out the following:

			# sram_text_size is 0xe27c
			# sram_bss_size is 0xbc4
			# sram_bss_size + sram_data_size is 0x20000
			# dram_textdata_size is 0x6c3768
			# dram_frameworks_size is 0xc40

			Then, in zero_bss we can find the size of dram.bss:

			<pre>
			void zero_bss(void) { // 0x22005fec
			memzero(0x2200e27c, 0xbc4); // zero out sram.bss
			// inlined memzero:
			void *start = 0x08000000 + 0x6c3768 + 0xc40;
			int size = 0x790a84;
			// ...
			}
			</pre>

			From which we can figure out that the dram.bss segment size is 0x790a84.

			Thus we can load the file like so (combining sram.bss and sram.data) into a 'clean' decompiler/disassembler session:

			{\| class="wikitable"
			\|-
			! Name !! Memory Address !! File Offset
			\|-
			\| sram.text \|\| 0x22000000 \|\| 0x00000000
			\|-
			\| sram.bssdata \|\| 0x22030000 \|\| 0x0000e27c
			\|-
			\| dram.textdata \|\| 0x08000000 \|\| 0x0002e27c (0xe27c + 0x20000)
			\|-
			\| dram.frameworks \|\| 0x086c3768 \|\| 0x006f19e4 (0xe27c + 0x20000 + 0x6c3768)
			\|-
			\| dram.bss \|\| 0x086c43a \|\| n/a (0x790a84 zeroes)
			\|}

			Writing an automated converter into ELF from arbitrary RetailOS blobs is an exercise left to the reader.

	== RTXC ==		== RTXC ==

Q3k: RetailOS -> retailOS

2023-02-25T09:58:24Z

RetailOS -> retailOS

← Older revision		Revision as of 09:58, 25 February 2023
Line 3:		Line 3:
	== Naming ==		== Naming ==

	The only 'official' name seems to be '~~RetailOS~~', found in the [[Nano 3G]] WTF. It is also referred to as 'osos' per the file name in the resource partition of the firmware bundle.		The only 'official' name seems to be 'retailOS', found in the [[Nano 3G]] WTF. It is also referred to as 'osos' per the file name in the resource partition of the firmware bundle.

	== Architecture ==		== Architecture ==

	~~RetailOS~~ is a small, embedded, single-user, single-binary, real time operating system. With time it acquire more and more complex functionality, like PowerVR drivers and being able to load external applications ('eApps') which are used for games.		retailOS is a small, embedded, single-user, single-binary, real time operating system. With time it acquire more and more complex functionality, like PowerVR drivers and being able to load external applications ('eApps') which are used for games.

	The core of the system is based on RTXC 3.2, with the end-user interface based on intellectual property from a company called Pixo. <ref>https://twitter.com/johnwhitley/status/1451952369248264201</ref>		The core of the system is based on RTXC 3.2, with the end-user interface based on intellectual property from a company called Pixo. <ref>https://twitter.com/johnwhitley/status/1451952369248264201</ref>
Line 13:		Line 13:
	== Security ==		== Security ==

	As evidenced by the success of the [[Notes vulnerability]], at least up to Nano 4G there was no kind of security hardening, and in fact all processes, including games, seem to be running in ARM system mode. This should make exploitation of newer ~~RetailOS~~ bugs trivial.		As evidenced by the success of the [[Notes vulnerability]], at least up to Nano 4G there was no kind of security hardening, and in fact all processes, including games, seem to be running in ARM system mode. This should make exploitation of newer retailOS bugs trivial.

	=== Boot chain ===		=== Boot chain ===

	~~RetailOS~~ is loaded by the second-stage bootloader (stored on NOR/NAND depending on the device generation), from NAND into DRAM.		retailOS is loaded by the second-stage bootloader (stored on NOR/NAND depending on the device generation), from NAND into DRAM.

	While other stages of the boot chain (eg. the bootloader, WTF mode in newer devices, the diagnostics tool) are based around EFI firmware volumes and an EFI runtime, ~~RetailOS~~ is a single binary blob without any built-in modularity.		While other stages of the boot chain (eg. the bootloader, WTF mode in newer devices, the diagnostics tool) are based around EFI firmware volumes and an EFI runtime, retailOS is a single binary blob without any built-in modularity.

	=== eApp Signing ===		=== eApp Signing ===
Line 39:		Line 39:
	=== Services / Syscalls ===		=== Services / Syscalls ===

	While RTXC documentation speaks mostly of 'kernel services' (which are defined as C function signatures/symbols), we like to talk about 'syscalls' and 'syscall numbers' when reverse engineering ~~RetailOS~~. All service functions go through a central dispatch function and that's the easiest point to start reverse engineering the kernel service interface.		While RTXC documentation speaks mostly of 'kernel services' (which are defined as C function signatures/symbols), we like to talk about 'syscalls' and 'syscall numbers' when reverse engineering retailOS. All service functions go through a central dispatch function and that's the easiest point to start reverse engineering the kernel service interface.

	The dispatcher receives a saved caller state which contains a pointer to a serialized syscall request in its saved R0. The syscall request is a trivial structure containing a syscall number and arguments. The dispatcher is executed with interrupts enabled (and thus is non-preemptable) and performs actual work on kernel structures. There is no privilege-granting 'gate' mechanism, all caller code is just as privileged as the kernel code.		The dispatcher receives a saved caller state which contains a pointer to a serialized syscall request in its saved R0. The syscall request is a trivial structure containing a syscall number and arguments. The dispatcher is executed with interrupts enabled (and thus is non-preemptable) and performs actual work on kernel structures. There is no privilege-granting 'gate' mechanism, all caller code is just as privileged as the kernel code.
Line 45:		Line 45:
	Service functions in turn prepare the syscall request structure (including syscall number), and then call an intermediary state saving function which then calls the dispatcher after disabling interrupts. Some syscall numbers are used by multiple service functions, with some extra arguments in the request being used to decide on the behaviour of the service call (eg. blocking/nonblocking).		Service functions in turn prepare the syscall request structure (including syscall number), and then call an intermediary state saving function which then calls the dispatcher after disabling interrupts. Some syscall numbers are used by multiple service functions, with some extra arguments in the request being used to decide on the behaviour of the service call (eg. blocking/nonblocking).

	The following table comes from cross-referencing ~~RetailOS~~, publicly available RTXC PDFs and publicly availble RTXC binaries with debug symbols.		The following table comes from cross-referencing retailOS, publicly available RTXC PDFs and publicly availble RTXC binaries with debug symbols.

	{\| class="wikitable"		{\| class="wikitable"
Line 106:		Line 106:
	\|}		\|}

	The RTXC memory allocation facilities (<code>KS_alloc/free/create_part/alloc_part/defpart/free_part</code>) are ''not'' used by ~~RetailOS~~ and not built into the service dispatcher, at least on [[Nano 5G]].		The RTXC memory allocation facilities (<code>KS_alloc/free/create_part/alloc_part/defpart/free_part</code>) are ''not'' used by retailOS and not built into the service dispatcher, at least on [[Nano 5G]].

	=== Semaphores ===		=== Semaphores ===

	The following semaphores are defined in the [[Nano 3G]] ~~RetailOS~~:		The following semaphores are defined in the [[Nano 3G]] retailOS:

	{\| class="wikitable"		{\| class="wikitable"
Line 239:		Line 239:
	=== Queues ===		=== Queues ===

	The following queues are defined in the [[Nano 3G]] ~~RetailOS~~:		The following queues are defined in the [[Nano 3G]] retailOS:

	{\| class="wikitable"		{\| class="wikitable"
Line 256:		Line 256:
	=== Mailboxes ===		=== Mailboxes ===

	The following mailboxes are defined in the [[Nano 3G]] ~~RetailOS~~:		The following mailboxes are defined in the [[Nano 3G]] retailOS:

	{\| class="wikitable"		{\| class="wikitable"
Line 275:		Line 275:
	=== Resources ===		=== Resources ===

	The following lockable resources are defined in the [[Nano 3G]] ~~RetailOS~~:		The following lockable resources are defined in the [[Nano 3G]] retailOS:

	{\| class="wikitable"		{\| class="wikitable"

Q3k: /* RTXC */

2023-02-19T16:14:13Z

RTXC

@@ Line 271: / Line 271: @@
 |-
 | 0x05 || M_DISPLAY ||
 |}

Q3k at 11:35, 19 February 2023

2023-02-19T11:35:49Z

@@ Line 236: / Line 236: @@
 There are three more semaphores (0x3c, 0x3d, 0x3e) that have no name defined and are likely unused. Anything 0x3f and up is a 'Dynamic' semaphore defined at runtime (which we haven't reversed yet).
 == External links ==
 * [https://web.archive.org/web/19990220054659/http://www.rtxc.com/Products/RTXC/Services.htm RTXC Kernel Services (1999)]

Q3k: /* RTXC */

2023-02-19T11:31:39Z

RTXC

@@ Line 107: / Line 107: @@
 The RTXC memory allocation facilities (<code>KS_alloc/free/create_part/alloc_part/defpart/free_part</code>) are ''not'' used by RetailOS and not built into the service dispatcher, at least on [[Nano 5G]].
 == External links ==
 * [https://web.archive.org/web/19990220054659/http://www.rtxc.com/Products/RTXC/Services.htm RTXC Kernel Services (1999)]

Q3k: /* RTXC */

2023-02-18T21:54:48Z

RTXC

← Older revision		Revision as of 21:54, 18 February 2023
Line 39:		Line 39:
	=== Services / Syscalls ===		=== Services / Syscalls ===

	~~This~~ table comes from cross-referencing RetailOS, publicly available RTXC PDFs and publicly availble RTXC binaries with debug symbols.		While RTXC documentation speaks mostly of 'kernel services' (which are defined as C function signatures/symbols), we like to talk about 'syscalls' and 'syscall numbers' when reverse engineering RetailOS. All service functions go through a central dispatch function and that's the easiest point to start reverse engineering the kernel service interface.

			The dispatcher receives a saved caller state which contains a pointer to a serialized syscall request in its saved R0. The syscall request is a trivial structure containing a syscall number and arguments. The dispatcher is executed with interrupts enabled (and thus is non-preemptable) and performs actual work on kernel structures. There is no privilege-granting 'gate' mechanism, all caller code is just as privileged as the kernel code.

			Service functions in turn prepare the syscall request structure (including syscall number), and then call an intermediary state saving function which then calls the dispatcher after disabling interrupts. Some syscall numbers are used by multiple service functions, with some extra arguments in the request being used to decide on the behaviour of the service call (eg. blocking/nonblocking).

			The following table comes from cross-referencing RetailOS, publicly available RTXC PDFs and publicly availble RTXC binaries with debug symbols.

	{\| class="wikitable"		{\| class="wikitable"