Multiboot Firmware - Load Rockbox from SD card

Purpose

Multiboot allows SD card boot on players that normally boot from internal flash.

Since March 2022 multiboot supports root redirect, a feature that allows you to run Rockbox from a subdirectory of your SD card instead of the root. This allows you to swap a card between multiple players by giving each player its own root folder. It also makes it easier to run different versions of Rockbox side by side on the same player.

Supported players

Currently only for select players. The list of supported players may eventually be expanded.

• Sansa Clip+, Clip Zip, Fuze+, Fuze(V1), FuzeV2, and E200(V1)
• FiiO M3K
• Shanling Q1
• AIGO Eros Q & clones

Supported versions

• 2019-11-15: Initial multiboot support for Sansa players
• 2022-03-07: Added root redirect
• 2022-03-27: Added support for M3K / Q1 / Eros Q

Multiboot features generally require support from both the Rockbox firmware and the bootloader, and both of them need to be new enough to support a feature for it to work.

Usage

To use multiboot / root redirect, create a redirect file on the SD card. Each player uses a different file extension for the redirect file so that the redirection for different players does not conflict.

Player	Redirect file
Sansa Clip+	rockbox_main.clip+
Sansa Clip Zip	rockbox_main.clipzip
Sansa Fuze+	rockbox_main.fuze+
Sansa Fuze V1	rockbox_main.fuze
Sansa Fuze V2	rockbox_main.fuze2
Sansa E200	rockbox_main.e200
FiiO M3K	rockbox_main.fiio_m3k
Shanling Q1	rockbox_main.shanling_q1
AIGO Eros Q	rockbox_main.aigo_erosqn

The contents of the redirect file must be a single line listing the path to the chosen root directory, which must be relative to the volume containing the redirect file. For example, for a Sansa Fuze+, if your installation was at /<microSD1>/.fuze the redirect file must be placed on <microSD1> and named rockbox_main.fuze+ with the contents

 
/.fuze

The path must be absolute, otherwise it is ignored and the file is treated as if it were empty. To use the root of the containing volume (= SD card containing the redirect file) use a single slash "/" or leave the file empty.

Note that using a subfolder requires a recent bootloader and firmware version. If you are using a Sansa with an older multiboot bootloader, you can only redirect to the volume root, not a subfolder. all multiboot bootloaders support this; older firmware versions do not support subfolder redirects --Bilgus

Folder structure

Your root directory should contain a .rockbox directory as if it were the root of your SD card. Do not move the contents of .rockbox into the redirect folder. Your folder structure should look like this example:

.fuze/
  .rockbox/
     backdrops/
     codecs/
     [...]
     rockbox.sansa

Stop using multiboot

To stop using multiboot and go back to the default .rockbox location (ie. internal storage on Sansas) simply delete the redirect file from your SD card.

Known limitations

On Sansa players a redirect file on the internal storage is ignored, only redirect files on the SD card are accepted. This is by design, as a safety feature in case the internal storage goes read only.

Reloading the firmware with ROLO will not work correctly if multiboot is used; you need to power off and reboot the player.

Tips and tricks

Change the default file browser directory

If you want to see the root of your SD card when you open the file browser instead of the redirected root, highlight the entry for your SD card (<microSD#>) and select Start File Browser Here from the context menu. The next time you open the file browser it will start there instead of the redirect folder.

Change the playlist catalogue and recording directories

The playlist catalogue and recording directories will appear in the redirected root by default. To change this to a more convienient folder you can open the context menu on your preferred folder in the file browser, and select Playlist Catalogue > Set as Playlist Catalogue Directory or Set as Recording Directory.

Advanced

How does it work?

The bootloader searches for a redirect file starting at the highest numbered volume which is usually the external SD card. When a redirect file is found it will read the file and look for the rockbox firmware in the specified directory. If the firmware was loaded successfully and is compatible with multiboot, the boot volume (the one where the redirect file was found) is copied into the firmware's multiboot header in memory and the bootloader passes control to the firmware. If the firmware is not found or does not support multiboot then that redirect is skipped and the bootloader will try again on the next volume. If firmware has still not been loaded after trying redirect files on each volume, a final attempt is made to load it from the default location (.rockbox on volume 0).

Once control is passed to the Rockbox firmware it will check its multiboot header during the init process. If the boot data is present, the firmware will read the redirect file on the boot volume to find the correct root directory. That directory will then be mounted as the filesystem root. If boot data was not filled in by the bootloader, ie. because the firmware was loaded by a non-multiboot bootloader, then the firmware will mount the root of volume 0 as root.

Future directions

Using a CRC for the multiboot header seems unnecessary. The header is part of the firmware binary, why do we need a special CRC check for one tiny part of the binary? Is it somehow more likely to get corrupted than other parts? I don't think so. To deal with non-multiboot-aware bootloaders the multiboot header should simply be initialized with suitable default values so there is no difference between multiboot and non-multiboot cases from a firmware perspective.

Now that root redirect is supported, the boot volume is not enough information for the firmware to find its root. Ideally the bootloader should copy the path it loaded the firmware from into the multiboot header; obviously this will require extending the header but it looks like this can be done in a safe, backward compatible way. Supplying the path would allow the firmware to skip parsing redirect files a second time. It would also allow ROLO to work as expected.

-- AidanMacDonald - 16 Apr 2022