Porting Rockbox to New Platforms

These steps below are of course a rough guide and just a few suggestions. The actual procedure will depend a lot on your own experience and skill, and what challenges the hardware you work with offers. Also, if you go for a target that is similar to an already supported device you may very well be able to take shortcuts.

Is this really how all new devices have been ported?

Yes. Nearly every device that Rockbox now runs on has gone through this process in some form or another. Someone has arrived at the Rockbox website, seen that Rockbox doesn't run on their favourite player, and has done all this work to change that. No currently supported device has received a Rockbox port just because it was asked for.

Am I up to the task?

Face it, if you want Rockbox ported, be prepared to do most of the ground work yourself. You will need skills in electronics and embedded programming in C and assembler. It is not feasible to work on a port without significant skill in embedded software development. If you do not have these skills, you can still gather information and documentation that would be helpful to subsequent developers, but the port will not be able to progress beyond that stage.

Has anything already been done?

Check the Target Status wiki page to see what, if anything, has already been done.

Who will help you?

First, don't ask Rockbox developers when they are going to port Rockbox to your platform. Ports are made by people who want to port, they are not done on request.

Then, assume that only actual owners of the target devices will be involved and interested enough to actually contribute to the down-to-metal porting. Nobody can port Rockbox to a device he/she doesn't have. (Though you could make someone an owner by giving him a device - this has proven fruitful at least once.)

Porting Rockbox can be everything from hard work to extremely hard and time consuming work. Try to gather as many interested friends and fans as possible so that the whole burden isn't put on one single human.

The Rockbox developers can and will try to help out with development, advice, hints and other general things, but only as much as they can and if they have the time.

Is it upgradable?

Can you upgrade the firmware at all? Is the firmware loaded from disk/flash? If not, there's a risk that the device simply isn't possible to upgrade. This will increase the difficulty level by orders of magnitudes to get Rockbox running on the unit.

Take it apart

However trivial this may sound, this is step 1 and it may require various degrees of violence.

Scan the PCBs

Preferably with a flatbed scanner. Digital cameras just never are good enough. They often can't produce the same resolution and you often get problems with reflections from the flash.

Publish the scans in the Wiki

Setup a dedicated port page in the Rockbox wiki where you gather all the facts and pictures.

Identify the components

Using your scans, contact your electronic savvy friends and use search engines to track down what every chip on the PCB is. Of course, as soon as you know what they are you should start gather datasheets and other docs for the chips and related info.

Figure out how to recover from a bad flash

Its nearly impossible for anyone to get everything right on the first try. You'll need to figure out a way to recover the player so that you don't brick it every time you make a mistake. On some DAPs this can be as simple as a bootloader USB mode. On others, recovering has required developing complicated software. On (luckily few) DAPs no method has been ever found and a single error can be fatal.

Figure out how to do a Firmware Upgrade

On most players we track down how the upgrade procedure and fileformat is made, and then we produce a "fake" update image when we flash the bootloader to the unit. On some models flashing isn't even required but the loading of the firmware is done from disk (Archos and iPod style). Unfortunately, many DAPs have a hash check or require firmware to be encrypted with a certain algorithm. Try disassembling the retail firmware to see if its encrypted, and if not try editing a string to see if theres a hash check.

If needed, trace the connections with a multimeter and draw schematics

This may require that you remove circuits from the board, which may or may not be possible without totally destroying your unit. We recommend considering doing this on an already broken unit. On some targets, this step has been skipped in favor of disassembling the retail firmware.

If needed, connect a BDM/JTAG emulator

If your hardware/CPU have the ability to connect a hardware emulator, be it BMD or JTAG, it certainly increases the chances of you understanding the existing firmware and being able to testrun your own first attempts easier.

Reverse Engineering

Depending on your success to get schematics, docs and hardware emulator, the need for actual reverse engineering of existing firmware will vary.

Start developing a boot loader

This of course requires at least some basic working drivers for LCD, buttons and storage.

Create a new build target

See PortingHowTo for details