mirror of
https://github.com/Rockbox/rockbox.git
synced 2026-10-10 08:03:04 -04:00
aed1945c5d
Registers the Nano 3G (platform ipodnano3g, model number 117, "nn3g"
header) so mks5lboot can build DFU installers and uninstallers for it,
adds its original bootloader to the dualboot code, and lists the
platform in the usage text and the README.
The target has to be named ipodnano3g rather than nano3g: the dualboot
Makefile derives the source directory and the piezo driver's file name
from it.
The per-target OF hash table is the substantive change. identify_fw()
decrypts the IM3 header's data_sign with the hardware UKEY and looks it
up in of_sha[], and anything not listed is taken to be a Rockbox
bootloader. The table held only iPod Classic firmware, so on a Nano 3G
the installer took Apple's own bootloader for a Rockbox one and gave up,
and the uninstaller would have refused to restore it. Both bail out
before writing, so nothing is damaged, but neither can work. The table
is now per target, and lists the bootloader of every Nano 3G firmware
release, 1.0.1 to 1.1.3.
The decrypted data_sign is the first 16 bytes of the SHA-1 of the
plaintext bootloader, so it is the same on every unit. Each release's
updater image (aupd, GID-encrypted, in the ipsw) carries that bootloader,
0x1f800 bytes, at the start of a NOR image. The aupd of each release was
decrypted on a Nano 3G with the hardware GID key and hashed on the host.
For 1.1.3 the result matches the data_sign read from a 4GB unit (model
MA978) whose NOR had never been written to, and the bootloader in its
aupd is byte-identical to the decrypted copy the installer relocated on
that unit. 1.1.2 and 1.1.3 ship the same bootloader.
dualboot.c is generated, and only the Nano 3G arrays are added. The iPod
Classic arrays are left byte-for-byte as they were: rebuilding them with
a different compiler changes their bytes, which would ship an untested
installer to Classic users for no reason.
The dualboot Makefile did not build from the current tree for any
target, which the committed blobs, older than both problems, had hidden.
config.h needs autoconf.h, which tools/configure generates per target,
so each target now takes a CONFIGDIR_<target> pointing at a configured
bootloader build for it, e.g.
make CONFIGDIR_ipod6g=../../../build-ipod6g-bl \
CONFIGDIR_ipodnano3g=../../../build-nano3g-bl
And the linker script is preprocessed with __ASSEMBLER__ defined, under
which config.h now emits the ldmpc/ldrpc assembler macros that ld
rejects; the sed that cleans it now also drops .macro, .endm and .syntax
lines and the macro bodies. Before these fixes the iPod Classic build
failed first on the missing autoconf.h and then with a linker syntax
error; with them it builds both blobs.
Tested on that unit, with s5l8702pwnage delivering the images through
Apple's DFU, and again with mks5lboot's own --bl-inst and --bl-uninst:
the installer put Rockbox in NOR, the unit then booted
Rockbox, and holding MENU booted Apple's firmware from the relocated
original bootloader; the uninstaller restored it and the unit booted
Apple's firmware again. Those images carried a table holding only the
1.1.3 entry. The Nano 3G blobs in dualboot.c were then rebuilt with the
Makefile for the full table - with the one-entry table the rebuild was
byte-identical to what the tested images carried - and mks5lboot
--bl-inst with them installed Rockbox on the same unit, which booted
Rockbox and, holding MENU, Apple's firmware. The uninstaller built with
the full table has not been run, and no firmware other than 1.1.3 has
been installed to or uninstalled from on hardware. For the iPod Classic,
the uninstaller DFU this builds is byte-identical to the one built
before this change.
AI provenance: developed with Claude Opus 5 (Anthropic), used through
Claude Code. The model wrote most of the code and this message under
Andrew Rice's direction. Any hardware testing described above was
carried out by Andrew Rice, who is responsible for this change.
Change-Id: I4b2fa692ac4110192ccbde0f1790b0ae2d1c73f5
236 lines
9.2 KiB
Text
236 lines
9.2 KiB
Text
mks5lboot
|
|
---------
|
|
|
|
A tool to install/uninstall a dual bootloader into a s5l8702 based
|
|
device:
|
|
|
|
- iPod Classic 6G
|
|
- iPod Nano 3G
|
|
|
|
Nano 3G support is currently limited to 4GB units with the tested Hynix
|
|
A514D3AD NAND configuration. The installer cannot identify the NAND while
|
|
the device is in DFU mode; see the Rockbox manual's Nano 3G installation
|
|
section before installing. Other configurations are rejected by the
|
|
bootloader rather than enabled with untested geometry or programming modes.
|
|
|
|
|
|
Usage
|
|
-----
|
|
|
|
mks5lboot --bl-inst <bootloader.ipod> [-p <pid>] [--single]
|
|
--bl-uninst <platform> [-p <pid>]
|
|
--dfuscan [--loop [<sec>]] [-p <pid>]
|
|
--dfusend <infile.dfu> [-p <pid>]
|
|
--dfureset [--loop [<sec>]] [-p <pid>]
|
|
--mkdfu-inst <bootloader.ipod> <outfile.dfu> [--single]
|
|
--mkdfu-uninst <platform> <outfile.dfu>
|
|
--mkdfu-raw <filename.bin> <outfile.dfu>
|
|
|
|
Commands:
|
|
--bl-inst Install file <bootloader.ipod> into an iPod device
|
|
(same as --mkdfu-inst and --dfusend).
|
|
--bl-uninst Remove a bootloader from an iPod device (same as
|
|
--mkdfu-uninst and --dfusend).
|
|
|
|
--dfuscan scan for DFU USB devices and outputs the status.
|
|
--dfusend send DFU image <infile.dfu> to the device.
|
|
--dfureset reset DFU USB device bus.
|
|
|
|
--mkdfu-inst Build a DFU image containing an installer for
|
|
<bootloader.ipod>, save it as <outfile.dfu>.
|
|
--mkdfu-uninst Build a DFU image containing an uninstaler for
|
|
<platform> devices, save it as <outfile.dfu>.
|
|
--mkdfu-raw Build a DFU image containing raw executable
|
|
code, save it as <outfile.dfu>. <infile.bin>
|
|
is the code you want to run, it is loaded at
|
|
address 0x2200030c and executed.
|
|
|
|
<bootloader.ipod> is the rockbox bootloader that you want to
|
|
install (previously scrambled with tools/scramble utility).
|
|
|
|
<platform> is the name of the platform (type of device) for
|
|
which the DFU uninstaller will be built. Currently supported
|
|
platform names are:
|
|
ipod6g: iPod Classic 6G
|
|
ipodnano3g: iPod Nano 3G
|
|
|
|
Options:
|
|
-p, --pid <pid> Use a specific <pid> (Product Id) USB device,
|
|
if this option is ommited then it uses the
|
|
first USB DFU device found.
|
|
-l, --loop <sec> Run the command every <sec> seconds, default
|
|
period (<sec> ommited) is 1 seconds.
|
|
-S, --single Be careful using this option. The bootloader
|
|
is installed for single boot, the original
|
|
Apple NOR boot is destroyed (if it exists),
|
|
and only Rockbox can be used.
|
|
|
|
|
|
Dual bootloader installation
|
|
----------------------------
|
|
|
|
Prerequisites:
|
|
|
|
- An iPod Classic 6th or iPod Nano 3G with Apple firmware installed and
|
|
running, current supported FW versions for existing models:
|
|
|
|
Classic 6th 80/160 Late 2007 (1G): 1.1.2
|
|
Classic 6th 120 Late 2008 (2G): 2.0.1
|
|
Classic 6th 160 Late 2009 (3G): 2.0.4
|
|
Classic 6th 160 Late 2012 (4G): 2.0.5
|
|
Nano 3G 4GB: 1.0.1 to 1.1.3
|
|
|
|
- If your iPod is formated using Apple partitions you must convert this
|
|
ipod to FAT32 format (aka a "winpod"), see http://www.rockbox.org/
|
|
wiki/IpodConversionToFAT32
|
|
|
|
- It is recommended to install the RB firmware before installing the dual
|
|
bootloader for the first time. Install Rockbox using RockboxUtility or
|
|
download the latest daily build and uncompress it into the root folder
|
|
of the iPod.
|
|
|
|
Windows only:
|
|
|
|
- If iTunes is installed:
|
|
. Configure iTunes: Summary -> Options -> check "Enable disk use".
|
|
|
|
- If iTunes is not installed:
|
|
. You need a DFU USB driver for your device. To check if there is a
|
|
valid USB driver installed, put your device on DFU mode and choose
|
|
one of either:
|
|
a) Use Windows Device Manager to verify if you USB DFU device is
|
|
present.
|
|
b) Use mks5lboot tool running "mks5lboot --dfuscan", common output:
|
|
. When the DFU device is found and a valid driver is installed:
|
|
[INFO] DFU device state: 2
|
|
. When the device is found but there is no driver installed:
|
|
[ERR] Could not open USB device: LIBUSB_ERROR_NOT_SUPPORTED
|
|
. When the device is found but driver is not valid (probably a
|
|
libusb-win32 driver is installed):
|
|
[ERR] Could not set USB configuration: LIBUSB_ERROR_NOT_FOUND
|
|
. If there is no valid DFU driver installed, try one of these:
|
|
a) Use Zadig (http://zadig.akeo.ie/) to build and install a WinUSB
|
|
(libusb.info) or libusbK driver for your device. Note that
|
|
libusb-win32 (libusb0) drivers are not valid for mks5lboot.
|
|
b) Use Apple Mobile Device USB driver (included with iTunes). To
|
|
install this driver without iTunes see https://www.freemyipod.org
|
|
/wiki/EmCORE_Installation/iPodClassic/InstalliTunesDrivers
|
|
|
|
Command line install:
|
|
|
|
- If you are using iTunes on Windows, close iTunes and kill (or pause)
|
|
iTunesHelper.exe before entering DFU mode.
|
|
|
|
- If you are using iTunes on Mac, quit iTunes and kill (or pause) the
|
|
iTunesHelper process before entering DFU mode.
|
|
You can use "ps x | grep iTunesHelper" to locate the process <PID>,
|
|
use "kill -STOP <PID>" to suspend the process and "kill -CONT <PID>"
|
|
to resume it once the bootloader is installed.
|
|
|
|
- Put you device on DFU mode by pressing and holding SELECT+MENU buttons
|
|
for about 12 seconds.
|
|
|
|
You can notice when the device enters DFU mode running the next command
|
|
to scan the USB bus every second (press Ctrl-C to abort the scan):
|
|
./mks5lboot --dfuscan --loop
|
|
|
|
- To install or update a bootloader, build the DFU installer and send it
|
|
to the device:
|
|
./mks5lboot --bl-inst path/to/bootloader-ipod6g.ipod
|
|
|
|
When the DFU image is loaded and executed, the device emits an 'alive'
|
|
tone (2000Hz/100ms). When the bootloader is successfully installed then
|
|
a dual tone beep sounds (1000Hz/100ms+2000Hz/150ms) and the device
|
|
reboots. If something went bad then 330Hz/500ms tone is emited and the
|
|
device reboots. When three 330Hz tones sounds, it means that the NOR
|
|
got corrupted and the device must be restored using iTunes (should not
|
|
happen).
|
|
|
|
- To remove a previously installed bootloader, build the DFU uninstaler
|
|
and send it to the device:
|
|
./mks5lboot --bl-uninst ipod6g
|
|
|
|
Notes:
|
|
|
|
- If USB access is denied, try to run the mks5lboot tool using a privileged
|
|
user (i.e. Administrator or root).
|
|
|
|
- On Windows, use 'mks5lboot' or 'mks5lboot.exe' instead of './mks5lboot'.
|
|
|
|
|
|
|
|
Dual-Boot
|
|
---------
|
|
|
|
The purpose of this program is to provide dual-boot between the original
|
|
firmware and the new (rockbox) firmware.
|
|
|
|
The button press check is done ~800 ms. after power-up or reboot, then:
|
|
|
|
SELECT + MENU: resets the device after ~5 seconds, then if SELECT+MENU
|
|
remains pressed the device enters DFU mode after an
|
|
additional period of ~8 seconds.
|
|
SELECT + LEFT: enter OF diagnostics (after ~7 seconds).
|
|
SELECT + PLAY: enter OF diskmode (after ~7 seconds).
|
|
SELECT + RIGHT: enter bootloader USB mode.
|
|
MENU: enter OF
|
|
Hold Switch locked: enter OF (see below for details).
|
|
Any other combination: launch Rockbox.
|
|
|
|
Switch current firmware:
|
|
|
|
Tries to behave like ipod Video, see http://download.rockbox.org/manual/
|
|
rockbox-ipodvideo/rockbox-buildch3.html#x5-290003.1.3
|
|
|
|
Apple is the current FW:
|
|
- Stop playback and wait a few seconds for hard disk spin-down.
|
|
- Press and hold SELECT+MENU, after ~5 seconds the player hard resets,
|
|
release the buttons when the screen goes black.
|
|
|
|
Rockbox is the current FW:
|
|
- Shut down the device using "Long Play" key press.
|
|
- Once the device is powered off, there are three ways to enter OF:
|
|
1) Press and hold MENU button for at least ~800 ms.
|
|
2) Turn on the Hold switch immediately after turning the player on,
|
|
it must be done before "Loading Rockbox..." message appears (~3
|
|
seconds from power-on). Be careful, if the hold switch is locked
|
|
when Rockbox starts then your RB settings will be cleared!
|
|
3) You can also load the original firmware by shutting down the
|
|
device, then clicking the Hold switch on and connecting the iPod
|
|
to your computer.
|
|
|
|
|
|
Single-Boot
|
|
-----------
|
|
|
|
Use --single option if the Apple firmware is not installed on your iPod
|
|
and/or you want to force the installation of the bootloader to use Rockbox
|
|
as unique firmware. The single-boot installer writes the bootloader on the
|
|
NOR with no previous check, the original Apple NOR boot is destroyed if it
|
|
exists.
|
|
|
|
To build the DFU single-boot installer and send it to the device:
|
|
mks5lboot --bl-inst --single /path/to/bootloader-ipod6g.ipod
|
|
|
|
|
|
Build
|
|
-----
|
|
|
|
To build type 'make'.
|
|
|
|
Linux needs libusb >= 1.0, use your package manager to install libusb.
|
|
|
|
For Windows, to build with libusb support type 'make USE_LIBUSBAPI=1'.
|
|
|
|
Tested on:
|
|
Linux: gcc-4.9.2 + libusb-1.0.19
|
|
Windows XP: mingw32-gcc-4.8.1 + libusbx-1.0.15
|
|
OS X 10.11: clang-7.3.0 + libusb-1.0.20
|
|
MXE: i686-w64-mingw32.static-gcc 5.4.0 + libusb-1.0.21
|
|
|
|
|
|
Hacking
|
|
-------
|
|
|
|
See comments in mkdfu.c, ipoddfu.c, dualboot.c and bootloader/ipod6g.c for
|
|
more information.
|