Mainline Kernel Howto

This page describes how you can compile and use the Linux mainline kernel.

= Current status =

Please refer to the Linux mainlining effort page for detailed status of mainlining effort, and supported boards and driver coverage. The upstream code does not support various drivers and lacks sound, display, 3D, 2D and media support.

NAND support is also not supported at the moment. This is work in progress, but the driver that will eventually get merged will be incompatible with Allwinner's. Indeed, both use different storage format.

If you simply want a more-or-less usable device for multimedia support, then use our own 3.4 branch.

= Prerequisites =

You should not attempt anything on this page, unless you are first comfortable with our Manual build howto which uses our sunxi-3.4 kernel. This Manual build howto will guide you through setting up a full working system, and once you have that, you can start thinking about replacing the kernel with the mainline kernel. Apart from a fully set up SD-Card, this howto will also get you a working toolchain and a recent U-Boot.

While the mainline kernel should work on any bootloader (with the major exception being the A20), you'll need a recent sunxi U-boot, or even better a Mainline_U-boot. SMP, virtualization and simplefb are the features you will most likely miss.

= Kernel source =

Stable releases
The stable releases are released by Linus Torvalds. Since Linux 3.8, the Allwinner support is added gradually. It is still quite sparse, but we are making good progress. This is probably what you should choose if you are looking for stability.

git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git --depth=1

Patches merged in the next stable release
There is also a sunxi-next branch maintained with all the inclusions that have been accepted, merged and will be included in the next stable release. If you want to do some development, it's probably the best pick.

git clone git://github.com/linux-sunxi/linux-sunxi.git -b sunxi-next --depth=1

= Kernel Configuration =

To get a working kernel, just use the following for configuration make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- sunxi_defconfig

If you wish to alter configuration, run: make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- menuconfig



If you have an old relevant .config, e.g. if you installed a late debian, and now want to build the kernel, you can copy it in and run.

Enable modules
If you need certain drivers as modules, at the top level menu, enable:

[*] Enable loadable module support --->

Remember to build modules as well later on, next to zImage and dtbs. Then, also remember to install your modules into your rootfs.

Early printk
If and only if your kernel does nothing, it pays to enable early printk support.

Go to: Kernel hacking ---> Then enable: [*] Kernel debugging

To actually get early printk, you need to also enable: [*] Kernel low-level debugging functions (read help!) Kernel low-level debugging port (Kernel low-level debugging messages via sunXi UART0) ---> [*] Early printk

On all supported SoCs, a good rule of thumb is that you will need UART0, unless you are on the A13 (UART1) or the A23 (R_UART).

The Kconfig options needed are CONFIG_DEBUG_KERNEL, CONFIG_DEBUG_LL, CONFIG_EARLY_PRINTK and one of the CONFIG_DEBUG_SUNXI options, depending on your board.

simplefb
While a KMS driver still is being worked on, a quick and easy way to get a display up on a HDMI monitor is to build (upcoming) U-Boot with sunxi cfb console support.

The kernel side support can be enabled through: Device Drivers ---> And then: Graphics support ---> Followed by: Frame buffer Devices ---> Enabled frame buffer devices, and descend into that menu: [*] Support for frame buffer devices ---> Then enable simplefb: [*]  Simple framebuffer support Then return to Graphics support and select: Console display driver support ---> And check: [*] Framebuffer Console support

Don't forget to change your console in your boot.cmd/boot.scr to console=tty1 to enable the simple framebuffer driver.

= Adding a new device =

Mainly, you have to write a device description. Please send a patch to help others finding good examples.

= Kernel Compilation =

To build the kernel, run now:

ARCH=arm CROSS_COMPILE= make zImage dtbs

After the compilation ended, you should have generated both the zImage in arch/arm/boot, and a device tree blob (.dtb) in arch/arm/boot/dts.

This device tree blob (or simply dtb) gives to the kernel the description of the hardware it's currently running on. In its goal, it's pretty similar to the FEX scripts that Allwinner uses, yet far more generic. It allows to compile a single kernel image that will run on several platforms.

To identify the dtb file that you will use on your board, first look into arch/arm/boot/dts. You should see a whole bunch of them, most being irrelevant to us because targeting boards based on other ARM SoCs. All the sunxi dtb follow the pattern - - .dtb (for example sun5i-a13-olinuxino.dtb, refer to Allwinner SoC Family for an exhaustive list).

If you have configured certain drivers as modules, you need to build and install these as well:

ARCH=arm CROSS_COMPILE= INSTALL_MOD_PATH= make modules modules_install

After the build succeeds, you can find the modules in the supplied INSTALL_MOD_PATH directory.

Specific Debian kernel notes
Having installed a late debian using the arm installer, building the Debian kernel is an attractive proposition. (for Debian install, see Rikomagic_mk802 'Images' section).

Some notes on doing so (as it's not so obvious from Google): You can download the sources using apt-get linux-source. Today, Dec 2016, this will get you ~4.8.7. Given sufficient space, this can be built on device (~4 days compile time), but probably better to cross-compile. Extract the tar to a suitable location, and copy /boot/config- to .config. You may want to edit the .config comment out CONFIG_MODULE_SIG_FORCE and CONFIG_MODULE_SIG. Prepare your cross machine, and then run

(you may get some new options).

Now, the important bit. IF 'uname -a' on your target shows 'armmp' anywhere, your kernel will need to be this 'flavor'; if it is not, then your newly created .deb kernel package will not install on the device..... So, to stamp it as flavor 'armmp':

Create a file called 'localversion' in the linux-source directory, and put -armmp inside. This will then generate a kernel stamped with the version '4.8.7-armmp' rather than plain '4.8.7', and will make dpkg/flash-kernel happy on install.

Then, to make the kernel, use; substituting your cross compiler;:

Note: if you want to build, but not start from scratch, the target bindeb-pkg does not do a clean first, whereas deb-pkg does.

You should end up with a file in one folder lower called something like

To install this on the device, go to that folder, or copy it to the device, and use

and if successful, reboot...

Note from the author of this last bit: I'm no expert on this, but as it took me over a week to establish the above; I hope it helps somebody! Please feel free to enhance or correct any of the above. If you do intend to reproduce this, then please make notes as you do it; a good (accurate) from scratch description would be a bonus here.

= Boot =

SD-Card Boot partition
Like with our Manual build howto, you have to set up the boot partition. Instead of script.bin, you need to install your board-specific .dtb to the boot partition. (Above kernel compilation should generate this binary representation of the device tree automatically.)

boot.cmd
Like in the Manual build howto, create a boot.cmd with the following contents:

fatload mmc 0 0x46000000 zImage fatload mmc 0 0x49000000 .dtb

setenv bootargs console=ttyS0,115200 earlyprintk root=/dev/mmcblk0p rootwait panic=10 ${extra}

bootz 0x46000000 - 0x49000000

Replace fatload with ext2load if needed. earlyprintk is optional; if your kernel boots up just fine, you might as well remove it.

If you are using an older U-Boot (you shouldn't - ), you might require the following line, to keep the extracted kernel from overwriting the device tree configuration: setenv fdt_high ffffffff

If you wish to use an initramfs, then the bootz command becomes: bootz 0x46000000 0x 0x49000000

Now generate boot.scr. Don't forget to copy over your zImage and .dtb files as well.

eMMC boot partition
eMMC is very similar to the SD card case (see above). From a user's perspective, think of it as an "internal" memory card. Some devices are able to boot entirely from eMMC, forgoing the need for an external SD card.


 * The Linux kernel may change device numbers depending on which mmc devices are actually present.
 * For example: If your SD card corresponds to mmc0, and the eMMC is mmc1, you'll probably end up with the eMMC as mmcblk1 when a SD card is also present (with the latter being mmcblk0). But it's likely that the eMMC becomes mmcblk0 as soon as no SD card (mmc0) is present. If in doubt, check the kernel messages and adjust your partition layout / boot options accordingly.

Network boot setup
Fold in Possible setups for hacking on mainline.

=See also=
 * Manual build howto
 * Linux mainlining effort
 * Possible setups for hacking on mainline