RetailOS

The stock operating system running on non-iOS iPods. It runs everything from device drivers to the clickwheel user interface.

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.

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.

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.

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.

Boot chain

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.

eApp Signing

Not yet documented fully. Each game seems to ship with a Manifest.plist.p7p which is a PKCS#7 signature for the main Manifest.plist.

Options

We have found some 'secret' options that can be set by creating specially named files. See Options.

RTXC

Documentation

This seems to be the best public document available about RTXC 3.2: DSAAXSA0003458.pdf. It contains example code for most services, but unfortunately is still missing any structure definitions.

There's also some training slides available: 5752851.pdf. These introduce the general architecture and concept of RTXC 3.2.

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.

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.

Name	Number	Description
void KS_pend(SEMA sema)	0x03	Semaphore DONE -> PENDING.
RTXCMSG *KS_receive(MBOX mailbox, TASK task)	0x05	Receive from mailbox.
KSRC KS_enqueue[w](QUEUE queue, void *entry)	0x0c	Push into FIFO (and block if full with 'w' variant).
void KS_dequeue[w](QUEUE queue, void *dest)	0x0d	Pop from FIFO (and block if empty with 'w' variant).
KSRC KS_lock(RESOURCE resource)	0x0e	Lock a resource.
KSRC KS_lockt(RESOURCE resource, TICKS timoeut)	0x0e	Lock a resource with timeout.
KSRC KS_unlock(RESOURCE resource)	0x0f	Unlock an owned resource.
CLKBLK *KS_alloc_timer(void)	0x10	Allocate next free timer from pool.
CLKBLK *KS_start_timer(CLKBLK *timer, TICKS initial_period, TICKS cycle_time, SEMA sema)	0x12	Start timer.
KSRC KS_stop_timer(CLKBLK *timer)	0x13	Stop timer.
void KS_delay(TASK task, TICKS period)	0x14	Block specified task for a period of time.
void KS_execute(TASK task)	0x15	Start a task from its beginning address.
KSRC KS_deftask(TASK task, PRIORITY priority, char *stack, size_t stacksize, void (*entry)(void))	0x16	Define the attributes of an inactive task.
TASK KS_alloc_task(void)	0x17	Allocate the next available Task Control Block from the pool of free TCBs.
void KS_terminate(TASK task)	0x18	Stop a task by setting it to INACTIVE.
void KS_suspend(TASK task)	0x19	Suspend a task until resumed or re-executed.
void KS_defpriority(TASK task, PRIORITY priority)	0x1b	Define or set priority of task.
void KS_yield(void)	0x1c	Voluntary release of control to any other task of the same priority.
SEMA KS_waitm(SEMA *semalist)	0x22	Wait on multiple semaphores.
time_t KS_inqtime(void)	0x24	Get current time-of-day.
void KS_deftime(time_t time)	0x25	Set current time-of-day.
TASK KS_inqres(RESOURCE resource)	0x26	Get owner of resource.
KSRC KS_defres(RESOURCE resource, RESATTR condition)	0x27	Define priority inversion on resource.
void *KS_inqtask_arg(TASK task)	0x28	Get environment arguments of task.
void KS_deftask_arg(TASK task, void *arg)	0x29	Set environment arguments for task.
KSRC KS_defqueue(QUEUE queue, size_t width, int depth, void *body, int currsize)	0x2e	Define queue.
int KS_user(int (*func) (void *), void *arg)	0x30	Execute function as if it were kernel service.

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

Semaphores

The following semaphores are defined in the Nano 3G RetailOS:

Number	Name	Description
0x01	S_FW_PWR_CHANGE
0x02	S_BAT_PWR_CHANGE
0x03	S_USB_PWR_CHANGE
0x04	S_CNA_CHANGE
0x05	S_WHEEL_CHANGE
0x06	S_DISKMGRQ
0x07	S_TOPPLUG_SWITCH
0x08	S_RTCTIMERMGR
0x09	S_ALARM_01
0x0a	S_ALARM_02
0x0b	S_ALARM_03
0x0c	S_WATCHDOG
0x0d	S_CPUMGRQ
0x0e	S_PCFPOWERMGR
0x0f	S_POWER_STATE_AC
0x10	S_CGR_STATE_TMR
0x11	S_DEEPSLEEP
0x12	S_ALARM_DONE
0x13	S_PIEZOMGR
0x14	S_PIEZOMGRSNDR
0x15	S_PIEZODONE
0x16	S_ACCPOWER
0x17	S_ACC_REINIT
0x18	S_TOPPLUGSENSER
0x19	S_TOPPLUGCHANGE
0x1a	S_BTMCONNECT
0x1b	S_BTMPLUGCHANGE
0x1c	S_BTMREVERIFY
0x1d	S_BTMREVERTIMED
0x1e	S_BTMVERCOMP
0x1f	S_TOPACCPKTRCVD
0x20	S_BTMACCPKTRCVD
0x21	S_SERIALIDRCVD
0x22	S_UARTATXEMPTY
0x23	S_UARTBTXEMPTY
0x24	S_HDDSCANCOMP
0x25	S_BL_ON
0x26	S_BL_OFF
0x27	S_BL_RAMPDOWN
0x28	S_BL_RAMPUP
0x29	S_BL_TIMESUP
0x2a	S_BATT_TIMESUP
0x2b	S_BATT_AC_PWR
0x2c	S_BATT_TMR_RST
0x2d	S_GRAPHMGR
0x2e	S_VBL
0x2f	S_DTVRECOVERY
0x30	S_CM_HEADPHONE
0x31	S_CM_EXTPOWER
0x32	S_CM_ACCATTACHED
0x33	S_CM_DAC_SETUP
0x34	S_ATAWRKLPRDY
0x35	S_RTXCBUG
0x36	S_BLOCKDEVICE
0x37	S_BLOCKDEVICEQ
0x38	S_DISPLAY
0x39	S_ARB_READY
0x3a	S_I2C_DONE
0x3b	S_VSYNC

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).

Queues

The following queues are defined in the Nano 3G RetailOS:

Number	Name	Description
0x01	PIXORESQ
0x02	PIXOSEMAQ
0x03	POSIXRESQ
0x04	POSIXSEMAQ

Mailboxes

The following mailboxes are defined in the Nano 3G RetailOS:

Number	Name	Description
0x01	M_DISKMGR
0x02	M_PIEZOMGR
0x03	M_GRAPHMGR
0x04	M_BLOCKDEVICE
0x05	M_DISPLAY

Resources

The following lockable resources are defined in the Nano 3G RetailOS:

Number	Name	Description
0x01	GPIO_REG_WRITE
0x02	GPIO_INT_INIT
0x03	RTC_TIME_ADJUST
0x04	RTC_ALARM_ADJUST
0x05	I2C_MASTER
0x06	USB_GRANT
0x07	USB_RESP_INIT
0x08	USB_RESPONDER
0x09	DISKPWRMGRSEND
0x0a	PIEZOMGRSEND
0x0b	SERIALVERIFIER
0x0c	RESISTORVERIFIER
0x0d	FW_IRAM
0x0e	ACCPOWER
0x0f	UARTA
0x10	UARGB
0x11	PMU_LOCK
0x12	ADC_LOCK
0x13	DTV_ENC_INIT
0x14	BACKLIGHT

External links

• RTXC Kernel Services (1999)

https://twitter.com/johnwhitley/status/1451952369248264201