1 files changed, 228 insertions, 0 deletions

diff --git a/utils/mks5lboot/README b/utils/mks5lboot/README
new file mode 100644
index 0000000000..c424f7e617
--- /dev/null
+++ b/utils/mks5lboot/README
@@ -0,0 +1,228 @@
+mks5lboot
+---------
+
+A tool to install/uninstall a dual bootloader into a s5l8702 based
+device:
+
+  - iPod Classic 6G
+  - iPod Nano 3G (WIP)
+
+
+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
+
+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 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
+
+  - 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.