OpenInkpot porting to new device HOWTO

Basics

In order to make OpenInkpot work on new device you need to work on the following pieces of code:

• Kernel
• Bootloader
• Userspace
• Firmware builder

Kernel

FIXME

Why there's separate kernel binary for every device?

FIXME

What's the use of vendor's kernel?

Source code supplied by vendor may be used as a reference manual for the device innards and as a source of drivers not yet appearing in mainline kernel. Note that vendor kernels are typically quite old and any code taken from it should be adapted heavily.

Can't we use vendor kernel with OpenInkpot?

First and foremost, such port can't be part of OpenInkpot unless vendor's kernel is truly free software. Even if it is, it is time-consuming to maintain two kernels in distribution, so merging drivers and platform support back to main OpenInkpot kernel is preferable.

Additionally, vendor kernels feature all kinds of bizarre behaviour and interfaces. OpenInkpot expects the following interfaces, so if vendor kernel provides some weird ioctl instead, userspace modification won't be allowed:

• Battery is expected to provide usual power_supply interface, not the weird ioctl provided by every vendor.
• ePaper screen is expected to behave as frame buffer possibly backed by deferred_io, not the weird ioctl provided by every vendor.
• All hardware keys are expected to be exported as evdev device, including "power" and other "unusual" keys. This device should feature sane keysyms. ioctl or signal-based brain-damaged keyboard handling as provided by vendors is not sane and can't be used.
• Sound device is expected to be ALSA device, not the weird new character device with weird set of ioctls.
• Touchscreen is expected to be evdev device, not the weird character device with weird set of ioctls.

Bootloader

There are three main scenarios of booting OpenInkpot:

• Replacing original bootloader with U-Boot or barebox
• Using original bootloader
• Loading OpenInkpot from the original firmware

New U-Boot or barebox

This variant is cleanest amongst the proposed, still riskiest, as failed bootloader update may result in bricked device for users. OTOH if device features emergency reflash circuitry (like USBboot in Ingenic JZ CPU on Device/N516) it is recommended mode as it means only OpenInkpot code is running on device.

Everything said in kernel porting section applies here.

Using original bootloader

This variant uses original bootloader to load OpenInkpot kernel. It is recommended variant if bootloader itself contains firmware upgrade code (like on Device/V3) and there are no other user-accessible reflash modes.

In this case kernel need to be prepared and placed onto flash in format understandable by bootloader (e.g. zImage instead of uImage). Note that original bootloaders may "feature" some restrictions and bugs:

• It may limit size of kernel to be loaded
• It may not be able to load separate initrd
• It may pass hardwired init string to kernel

It is also possible to chainload bootloader by letting original bootloader execute U-Boot or barebox compiled as zImage and placed in location of original kernel, and then proceed as in previous section.

Loading OpenInkpot from original firmware

If replacing original bootloader or kernel is too risky due to lack of emergency restore procedures then is possible to chainload whole OS boot, by using either kexec syscall if supported by original kernel, or loading kernel module providing kexec-like functionality. Such kernel is hardware-dependent, and there are  several  modules  ready for a few devices. It isn't hard to adapt such module to new device, as it borrows heavily from in-kernel kexec implementation.

Such chainloading requires either storing OpenInkpot root filesystem in file on existing filesystem (which means kernel should have built-in code for flash and fs in question), or use spare block device such as second memory card (like MemoryStick on PRS-505). In any case kernel itself and initrd if necessary are stored as files on original filesystem.

Userspace

FIXME

Firmware builder

FIXME