1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
|
# jztool -- Ingenic device utility & bootloader installer
The `jztool` utility can help install, backup, and restore the bootloader on
Rockbox players based on a supported Ingenic SoC.
## FiiO M3K
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 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.
Copy the `bootloader.m3k` next to the `jztool` executable and follow the
instructions below which are appropriate to your OS.
### 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.
## TODO list
### Add better documentation and logging
There's only a bare minimum of documentation, and logging is sparse, not
really enough to debug problems.
Some of the error messages could be friendlier too.
### Integration with the Rockbox utility
Adding support to the Rockbox utility should be mostly boilerplate since the
jztool library wraps all the troublesome details.
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.
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.)
|
