User:Knuxify/Draft:Getting started

This page serves as an introduction to the basics of mainlining.

Prerequisites

• A computer running Linux, which will handle building the kernel.
  • If you're on Windows, you can use WSL (though flashing the kernel to your device might be a bit challenging, TODO).
  • (Note about recommended specs goes here; faster hardware is better, but only necessary bits are rebuilt on subsequent builds; also mention ccache?)
• Some familiarity with the Linux shell and C programming language syntax is recommended.

Getting to know your device and SoC

TODO: These are both topics worthy of their own page. Some things to mention here: Finding out whether the SoC is supported to mainline and, if so, how well. Finding out what components your device has (it's nice to keep a table!)

Preparing the build environment

In order to mainline a device, we need to be able to cross-compile the Linux kernel for it.

Downloading the Linux kernel source code

Depending on your SoC's support status:

• There may be an up-to-date maintained close-to mainline fork of the Linux kernel for your device's SoC; if there is one, start from it.
• If there is no dedicated fork for your device's SoC, or the fork is out of date, start with either:
  • The latest stable tag directly from Torvalds' tree (see [1] or github.com/torvalds/linux).
  • For very new SoCs with ongoing work, you may want to use the linux-next tree instead.

If you're on GitHub, you can fork the torvalds/linux repository and start from there.

Once you have your kernel cloned, switch to the latest tag, then create a new feature branch from it:

$ git checkout v6.14  # replace 6.14 with latest kernel version
$ git checkout -b codename-mainline  # git checkout -b creates a new branch based on current HEAD and checks out into it

TODO: Link to some nice guide on git here (and probably elsewhere in the page)

Cross-compiler setup

TODO: Explain cross-compiler setup; where to get toolchains (AUR for Arch users? Linaro?), postmarketOS envkernel.sh

Selecting/creating a defconfig

The kernel config dictates which drivers and platform-specific support bits (including DTBs) get built. There are a handful of pre-made configs, called defconfigs, in arch/{arm,arm64,...}/configs - use make name_defconfig to build them.

TODO: Common ARM(64) config? Which options to select/unselect? pmbootstrap kconfig check might be useful here

Adding a device tree for your device

Devices using ARM chipsets use devicetrees to describe the hardware. See Devicetree/Writing a Linux device tree for a guide.

Building the kernel

TODO: make -j$(nproc)

Packaging the kernel into a boot image

TODO: See how I do it in mainline-tools, mention pmbootstrap build --envkernel?

Then, flash the resulting kernel to the device.

Getting the kernel to boot

TODO: UART, DTBO trickery

See also

TODO: pmOS wiki has links to talks and resources