The 920-0614-03 is seemingly a development/prototype iPod Nano 4G (or possibly iPod Touch 2G board?). It appeared on a bunch of eBay auctions around September 2023.

== Specs ==

'''SoC''': S5L8729

'''Flash''': Usually desoldered

'''DRAM''': To be checked

== UART ==

The boards has at least two ways to access UART:

# Over DE9 connector.

# Over USB/Serial bridge.

# Over 30-pin connector.

'''TODO''': Figure out which serial is which, and document reanimating DE9/USB.

== Power ==

The board runs from either the 30-pin connector by itself (although it can sometimes be unstable) or from 5V over a DC power jack (which provides a 4v-ish supply which simulates the devices' battery).

== JTAG ==

[[JTAG]] is available over the 30 pin connector, but is also seemingly locked out as on production devices.

== Getting code to run ==

[[wInd3x]] works on the device. On devices without Flash attempting to run the standard WTF causes a reset.

== Differences from production device ==

So far, it seems like the SoC present on the board is no different from production SoCs.

=== CHIPID ===

Seems like a perfectly standard S5L8720:

<pre>
3d100000: 0100 0000 0100 0011 0f18 2087 104f 6d76 .......... ..Omv
3d100010: d700 0000 0300 0000 0000 0000 0000 0000 ................
</pre>

== Pins ==

As the board has clearly labeled and accessible GPIO pins / configuration straps, it's a good candidate to reverse engineer pin functionality as used in the production device.

{| class="wikitable"
|-
! S5L8720 GPIO !! Function on board
|-
| 91 || 'DFU' button
|}

2023-02-25T09:58:24Z

Q3k: RetailOS -> 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. <ref>https://twitter.com/johnwhitley/status/1451952369248264201</ref>

== 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 [[RetailOS_Options|Options]].

== RTXC ==

=== Documentation ===

This seems to be the best public document available about RTXC 3.2: [https://web.archive.org/web/20230218212424/https://datasheet.datasheetarchive.com/originals/library/Datasheets-AS2/DSAAXSA0003458.pdf DSAAXSA0003458.pdf]. It contains example code for most services, but unfortunately is still missing any structure definitions.

There's also some training slides available: [https://ia801800.us.archive.org/26/items/manualzilla-id-5752851/5752851.pdf 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.

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

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 ===

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

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

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:

{| class="wikitable"
|-
! Number !! Name !! Description
|-
| 0x01 || PIXORESQ ||
|-
| 0x02 || PIXOSEMAQ ||
|-
| 0x03 || POSIXRESQ ||
|-
| 0x04 || POSIXSEMAQ ||
|}

=== Mailboxes ===

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

{| class="wikitable"
|-
! 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:

{| class="wikitable"
|-
! 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 ==

* [https://web.archive.org/web/19990220054659/http://www.rtxc.com/Products/RTXC/Services.htm RTXC Kernel Services (1999)]

Hardware

2023-02-23T17:32:12Z

Q3k:

This is just a basic comparison of each generation's main components. For a detailed hardware analysis of a generation, click on it's link.

{| class="wikitable"
! Generation !! CPU !! RAM !! NOR/Utility Flash !! Codename
|-
|[[Nano 1G]]
|PP5021C-TDF
|[http://www.samsung.com/global/business/semiconductor/productInfo.do?fmly_id=753&partnum=K4M56163PG K4M56163PG] (32MiB)
|[http://www.sst.com/products/?inode=41856 SST39WF400A] (512KiB)
|
|-
|[[Nano 2G]]
|S5L8701
|[http://www.samsung.com/global/business/semiconductor/productInfo.do?fmly_id=753&partnum=K4M56163PG K4M56163PG] (32MiB)
|[http://www.sst.com/products/?inode=41422 SST39WF800A] (1MiB)
|
|-
|[[Nano 3G]]
|S5L8702
|[http://www.samsung.com/global/system/business/semiconductor/product/2007/11/13/236652ds_k4x56163pi.pdf K4X56163PI] (32MiB)
|[http://www.sst.com/products/?inode=41340 SST25VF080B] (1MiB)
| N46
|-
|[[Nano 4G]]
|S5L8720
|Integrated (32MiB)
| ''none''
| N58
|-
|[[Nano 5G]]
|S5L8730
|Integrated (64MiB)
| ''none''
| N33
|-
|[[Nano 6G|Nano 6G]]
|S5L8723
|Integrated
| ''none''
| N20
|-
|[[Nano 7G|Nano 7G]]
|S5L8740
|Integrated
| ''none''
| N31
|-
|[[Classic 1G]]
|S5L8702
|[http://www.samsung.com/global/system/business/semiconductor/product/2007/11/13/236652ds_k4x56163pi.pdf K4X56163PI] (64MiB)
|[http://www.sst.com/products/?inode=41340 SST25VF080B] (1MiB)
|
|-
|[[Classic 2G]]
|S5L8702
|[http://www.samsung.com/global/system/business/semiconductor/product/2007/11/13/236652ds_k4x56163pi.pdf K4X56163PI] (64MiB)
|[http://www.sst.com/products/?inode=41340 SST25VF080B] (1MiB)
|
|-
|[[Classic 3G]]
|S5L8702
|[http://www.samsung.com/global/system/business/semiconductor/product/2007/11/13/236652ds_k4x56163pi.pdf K4X51163PE] (64MiB)
|[http://www.sst.com/products/?inode=41340 SST25VF080B] (1MiB)
|
|}

Concerning the detailed generation pages: If you can prove or disprove any of these chip names, please let us know: [[Contact]]

==Helpful pages==
Chip analyses
*http://www2.electronicproducts.com/Apple_iPod_Touch-whatsinside-57.aspx
*http://www2.electronicproducts.com/Apple_iPhone-whatsinside-4.aspx
Additional information
*http://dendrites.blog.163.com/blog/static/165376178201082112922174/