From c876d3bbefe0dc00c27ca0c12d29da5874946962 Mon Sep 17 00:00:00 2001 From: Dominik Riebeling Date: Wed, 15 Dec 2021 21:04:28 +0100 Subject: rbutil: Merge rbutil with utils folder. rbutil uses several components from the utils folder, and can be considered part of utils too. Having it in a separate folder is an arbitrary split that doesn't help anymore these days, so merge them. This also allows other utils to easily use libtools.make without the need to navigate to a different folder. Change-Id: I3fc2f4de19e3e776553efb5dea5f779dfec0dc21 --- utils/jztool/README.md | 135 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 135 insertions(+) create mode 100644 utils/jztool/README.md (limited to 'utils/jztool/README.md') diff --git a/utils/jztool/README.md b/utils/jztool/README.md new file mode 100644 index 0000000000..72c630c6c3 --- /dev/null +++ b/utils/jztool/README.md @@ -0,0 +1,135 @@ +# 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 (currently only the X1000). + +## Running jztool + +### Getting a bootloader + +To use `jztool` you need to compile or download a bootloader for your player. +It's recommended to use only official released bootloaders, since bootloaders +compiled from Git are not tested and might be buggy. + +You can download released bootloaders from . + +The bootloader file is named after the target: for example, the FiiO M3K +bootloader is called `bootloader.m3k`. The FiiO M3K is used as an example +here, but the instructions apply to all X1000-based players. + +Use `jztool --help` to find out the model name of your player. + +### Entering USB boot mode + +USB boot mode is a low-level mode provided by the CPU which allows a computer +to load firmware onto the device. You need to put your player into this mode +manually before using `jztool` (unfortunately, it can't be done automatically.) + +To connect the player in USB boot mode, follow these steps: + +1. Ensure the player is fully powered off. +2. Plug one end of the USB cable into your player. +3. Hold down your player's USB boot key (see below). +4. Plug the other end of the USB cable into your computer. +5. Let go of the USB boot key. + +The USB boot key depends on your player: + +- FiiO M3K: Volume Down +- Shanling Q1: Play +- Eros Q: Menu + +### 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 your player 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 . 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. All X1000-based players use the same USB ID while in USB boot +mode, 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 +``` + +## Using the recovery menu + +If `jztool` runs successfully your player will display the Rockbox bootloader's +recovery menu. If you want to permanently install Rockbox to your device, copy +the bootloader file you downloaded to the root of your SD card, insert the SD +card to your player, and 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 `PLAYER-boot.bin`, where `PLAYER` is the model name. +(Example: `fiiom3k-boot.bin`.) + +You can restore the backup later by putting it on the root of your SD card and +selecting "Restor bootloader" in the recovery menu. + +After installing the Rockbox bootloader, you can access the recovery menu by +holding a key while booting: + +- FiiO M3K: Volume Up +- Shanling Q1: Next (button on the lower left) +- Eros Q: Volume Up + +### 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.) -- cgit v1.2.3