diff options
Diffstat (limited to 'rbutil/jztool/README.md')
-rw-r--r-- | rbutil/jztool/README.md | 118 |
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 @@ | |||
1 | # jztool -- Ingenic device utility & bootloader installer | 1 | # jztool -- Ingenic device utility & bootloader installer |
2 | 2 | ||
3 | The `jztool` utility can install, backup, and restore the bootloader on | 3 | The `jztool` utility can help install, backup, and restore the bootloader on |
4 | Rockbox players based on a supported Ingenic SoC. | 4 | Rockbox players based on a supported Ingenic SoC. |
5 | 5 | ||
6 | ## FiiO M3K | 6 | ## FiiO M3K |
7 | 7 | ||
8 | To use `jztool` on the FiiO M3K you have to connect the player to your | 8 | First, get a copy of the `bootloader.m3k` file, either by downloading it |
9 | computer in USB boot mode. | 9 | from <https://rockbox.org>, or by compiling it yourself (choose 'B'ootloader |
10 | build when configuring your build). | ||
10 | 11 | ||
11 | The easiest way to do this is by plugging in the microUSB cable to the M3K | 12 | The first time you install Rockbox, you need to load the Rockbox bootloader |
12 | and holding the volume down button while plugging the USB into your computer. | 13 | over USB by entering USB boot mode. The easiest way to do this is by plugging |
13 | If you entered USB boot mode, the button light will turn on but the LCD will | 14 | in the microUSB cable to the M3K and holding the VOL- button while plugging |
14 | turn off. | 15 | the USB into your computer. If you entered USB boot mode, the button light |
16 | will turn on but the LCD will remain black. | ||
15 | 17 | ||
16 | To install or update the Rockbox bootloader on the M3K, use the command | 18 | Copy the `bootloader.m3k` next to the `jztool` executable and follow the |
17 | `jztool fiiom3k install`. It is recommended that you take a backup of your | 19 | instructions below which are appropriate to your OS. |
18 | current bootloader so you can restore it in case of any problems. | ||
19 | 20 | ||
20 | After any operation finishes, you will have to force a power off of the M3K | 21 | ### Running jztool |
21 | by holding down the power button for at least 10 seconds. This must be done | 22 | |
22 | whether the operation succeeds or fails. Just don't power off or unplug the | 23 | #### Linux/Mac |
23 | device in the middle of an operation -- that might make bad things happen. | 24 | |
25 | Run the following command in a terminal. Note that on Linux, you will need to | ||
26 | have root access to allow libusb to access the USB device. | ||
27 | |||
28 | ```sh | ||
29 | # Linux / Mac | ||
30 | # NOTE: root permissions are required on Linux to access the USB device | ||
31 | # eg. with 'sudo' or 'su -c' depending on your distro. | ||
32 | $ ./jztool fiiom3k load bootloader.m3k | ||
33 | ``` | ||
34 | |||
35 | #### Windows | ||
36 | |||
37 | To allow `jztool` access to the M3K in USB boot mode, you need to install | ||
38 | the WinUSB driver. The recommended way to install it is using Zadig, which | ||
39 | may be downloaded from its homepage <https://zadig.akeo.ie>. Please note | ||
40 | this is 3rd party software not maintained or supported by Rockbox developers. | ||
41 | (Zadig will require administrator access on the machine you are using.) | ||
42 | |||
43 | When running Zadig you must select the WinUSB driver; the other driver options | ||
44 | will not work properly with `jztool`. You will have to select the correct USB | ||
45 | device in Zadig -- the name and USB IDs of the M3K in USB boot mode are listed | ||
46 | below. NOTE: the device name may show only as "X" and a hollow square in Zadig. | ||
47 | The IDs will not change, so those are the most reliable way to confirm you have | ||
48 | selected the correct device. | ||
49 | |||
50 | ``` | ||
51 | Name: Ingenic Semiconductor Co.,Ltd X1000 | ||
52 | USB ID: A108 1000 | ||
53 | ``` | ||
54 | |||
55 | Assuming you installed the WinUSB driver successfully, open a command prompt | ||
56 | in the folder containing `jztool`. Administrator access is not required for | ||
57 | this step. | ||
58 | |||
59 | Type the following command to load the Rockbox bootloader: | ||
60 | |||
61 | ```sh | ||
62 | # Windows | ||
63 | $ jztool.exe fiiom3k load bootloader.m3k | ||
64 | ``` | ||
65 | |||
66 | ### Further instructions | ||
67 | |||
68 | After running `jztool` successfully your M3K will display the recovery menu | ||
69 | of the Rockbox bootloader. If you want to permanently install Rockbox to your | ||
70 | M3K, copy `bootloader.m3k` to the root of an SD card, insert it to your device, | ||
71 | then choose "Install/update bootloader" from the menu. | ||
72 | |||
73 | It is _highly_ recommended that you take a backup of your existing bootloader | ||
74 | in case of any trouble -- choose "Backup bootloader" from the recovery menu. | ||
75 | The backup file is called "fiiom3k-boot.bin" and will be saved to the root of | ||
76 | the SD card. If you need to restore it, simply place the file at the root of | ||
77 | your SD card and select "Restore bootloader". | ||
78 | |||
79 | In the future if you want to backup, restore, or update the bootloader, you | ||
80 | can access the Rockbox bootloader's recovery menu by holding VOL+ when booting. | ||
81 | |||
82 | ### Known issues | ||
83 | |||
84 | - When using the bootloader's USB mode, you may get stuck on "Waiting for USB" | ||
85 | even though the cable is already plugged in. If this occurs, unplug the USB | ||
86 | cable and plug it back in to trigger the connection. | ||
24 | 87 | ||
25 | See `jztool --help` for info. | ||
26 | 88 | ||
27 | ## TODO list | 89 | ## TODO list |
28 | 90 | ||
@@ -38,23 +100,11 @@ Some of the error messages could be friendlier too. | |||
38 | Adding support to the Rockbox utility should be mostly boilerplate since the | 100 | Adding support to the Rockbox utility should be mostly boilerplate since the |
39 | jztool library wraps all the troublesome details. | 101 | jztool library wraps all the troublesome details. |
40 | 102 | ||
41 | Getting appropriate privileges to access the USB device is the main issue. | 103 | Permissions are an issue on Linux because by default only root can access |
42 | Preferably, the Rockbox utility should not run as root/admin/etc. | 104 | "raw" USB devices. If we want to package rbutil for distro we can install |
43 | 105 | a udev rule to allow access to the specific USB IDs we need, eg. allowing | |
44 | - Windows: not sure | 106 | users in the "wheel" group to access the device. |
45 | - Linux: needs udev rules or root privileges | ||
46 | - Mac: apparently does not need privileges | ||
47 | |||
48 | ### Porting to Windows | ||
49 | |||
50 | Windows wants to see a driver installed before we can access the USB device, | ||
51 | the easiest way to do this is by having the user run Zadig, a 3rd party app | ||
52 | which can install the WinUSB driver. WinUSB itself is from Microsoft and | ||
53 | bundled with Windows. | ||
54 | |||
55 | Zadig's homepage: https://zadig.akeo.ie/ | ||
56 | |||
57 | ### Porting to Mac | ||
58 | 107 | ||
59 | According to the libusb wiki, libusb works on Mac without any special setup or | 108 | On Windows and Mac, no special permissions are needed to access USB devices |
60 | privileges, presumably porting there is easy. | 109 | assuming the drivers are set up. (Zadig does require administrator access |
110 | to run, but that's external to the Rockbox utility.) | ||