1 files changed, 84 insertions, 34 deletions

diff --git a/rbutil/jztool/README.md b/rbutil/jztool/README.md
index 6a9b78f8d7..2c4dd4992c 100644
--- a/rbutil/jztool/README.md
+++ b/rbutil/jztool/README.md
@@ -1,28 +1,90 @@
 # jztool -- Ingenic device utility & bootloader installer
 
-The `jztool` utility can install, backup, and restore the bootloader on
+The `jztool` utility can help install, backup, and restore the bootloader on
 Rockbox players based on a supported Ingenic SoC.
 
 ## FiiO M3K
 
-To use `jztool` on the FiiO M3K you have to connect the player to your
-computer in USB boot mode.
+First, get a copy of the `bootloader.m3k` file, either by downloading it
+from <https://rockbox.org>, or by compiling it yourself (choose 'B'ootloader
+build when configuring your build).
 
-The easiest way to do this is by plugging in the microUSB cable to the M3K
-and holding the volume down button while plugging the USB into your computer.
-If you entered USB boot mode, the button light will turn on but the LCD will
-turn off.
+The first time you install Rockbox, you need to load the Rockbox bootloader
+over USB by entering USB boot mode. The easiest way to do this is by plugging
+in the microUSB cable to the M3K and holding the VOL- button while plugging
+the USB into your computer. If you entered USB boot mode, the button light
+will turn on but the LCD will remain black.
 
-To install or update the Rockbox bootloader on the M3K, use the command
-`jztool fiiom3k install`. It is recommended that you take a backup of your
-current bootloader so you can restore it in case of any problems.
+Copy the `bootloader.m3k` next to the `jztool` executable and follow the
+instructions below which are appropriate to your OS.
 
-After any operation finishes, you will have to force a power off of the M3K
-by holding down the power button for at least 10 seconds. This must be done
-whether the operation succeeds or fails. Just don't power off or unplug the
-device in the middle of an operation -- that might make bad things happen.
+### Running jztool
+
+#### Linux/Mac
+
+Run the following command in a terminal. Note that on Linux, you will need to
+have root access to allow libusb to access the USB device.
+
+```sh
+# Linux / Mac
+# NOTE: root permissions are required on Linux to access the USB device
+#       eg. with 'sudo' or 'su -c' depending on your distro.
+$ ./jztool fiiom3k load bootloader.m3k
+```
+
+#### Windows
+
+To allow `jztool` access to the M3K in USB boot mode, you need to install
+the WinUSB driver. The recommended way to install it is using Zadig, which
+may be downloaded from its homepage <https://zadig.akeo.ie>. Please note
+this is 3rd party software not maintained or supported by Rockbox developers.
+(Zadig will require administrator access on the machine you are using.)
+
+When running Zadig you must select the WinUSB driver; the other driver options
+will not work properly with `jztool`. You will have to select the correct USB
+device in Zadig -- the name and USB IDs of the M3K in USB boot mode are listed
+below. NOTE: the device name may show only as "X" and a hollow square in Zadig.
+The IDs will not change, so those are the most reliable way to confirm you have
+selected the correct device.
+
+```
+Name:   Ingenic Semiconductor Co.,Ltd X1000
+USB ID: A108 1000
+```
+
+Assuming you installed the WinUSB driver successfully, open a command prompt
+in the folder containing `jztool`. Administrator access is not required for
+this step.
+
+Type the following command to load the Rockbox bootloader:
+
+```sh
+# Windows
+$ jztool.exe fiiom3k load bootloader.m3k
+```
+
+### Further instructions
+
+After running `jztool` successfully your M3K will display the recovery menu
+of the Rockbox bootloader. If you want to permanently install Rockbox to your
+M3K, copy `bootloader.m3k` to the root of an SD card, insert it to your device,
+then choose "Install/update bootloader" from the menu.
+
+It is _highly_ recommended that you take a backup of your existing bootloader
+in case of any trouble -- choose "Backup bootloader" from the recovery menu.
+The backup file is called "fiiom3k-boot.bin" and will be saved to the root of
+the SD card. If you need to restore it, simply place the file at the root of
+your SD card and select "Restore bootloader".
+
+In the future if you want to backup, restore, or update the bootloader, you
+can access the Rockbox bootloader's recovery menu by holding VOL+ when booting.
+
+### Known issues
+
+- When using the bootloader's USB mode, you may get stuck on "Waiting for USB"
+  even though the cable is already plugged in. If this occurs, unplug the USB
+  cable and plug it back in to trigger the connection.
 
-See `jztool --help` for info.
 
 ## TODO list
 
@@ -38,23 +100,11 @@ Some of the error messages could be friendlier too.
 Adding support to the Rockbox utility should be mostly boilerplate since the
 jztool library wraps all the troublesome details.
 
-Getting appropriate privileges to access the USB device is the main issue.
-Preferably, the Rockbox utility should not run as root/admin/etc.
-
-- Windows: not sure
-- Linux: needs udev rules or root privileges
-- Mac: apparently does not need privileges
-
-### Porting to Windows
-
-Windows wants to see a driver installed before we can access the USB device,
-the easiest way to do this is by having the user run Zadig, a 3rd party app
-which can install the WinUSB driver. WinUSB itself is from Microsoft and
-bundled with Windows.
-
-Zadig's homepage: https://zadig.akeo.ie/
-
-### Porting to Mac
+Permissions are an issue on Linux because by default only root can access
+"raw" USB devices. If we want to package rbutil for distro we can install
+a udev rule to allow access to the specific USB IDs we need, eg. allowing
+users in the "wheel" group to access the device.
 
-According to the libusb wiki, libusb works on Mac without any special setup or
-privileges, presumably porting there is easy.
+On Windows and Mac, no special permissions are needed to access USB devices
+assuming the drivers are set up. (Zadig does require administrator access
+to run, but that's external to the Rockbox utility.)