Skip to content

kernel-development.md

Latest commit

 

History

History
166 lines (124 loc) · 6.76 KB

kernel-development.md

File metadata and controls

166 lines (124 loc) · 6.76 KB
Raw

OpenBMC kernel and u-boot development

Important

The kernel development philosophy described below also applies to OpenBMC's u-boot fork, with the additional rules described in U-Boot.

The OpenBMC project maintains a kernel tree for use by the project. The tree's general development policy is that code must be upstream first. This is strongly desirable but not a hard requirement, and exceptions may be made on a case-by-case basis. If in doubt, start a discussion on the mailing list.

The OpenBMC kernel tree is hosted at https://github.com/openbmc/linux and contains the set of patches that we carry. Ideally there would be no patches carried, as everything should be upstream.

Your code will make it into the OpenBMC tree in these ways, from most to least desirable:

  1. When the OpenBMC kernel moves to a new upstream release
  2. By backporting upstream commits from a newer kernel version to the OpenBMC kernel
  3. Patches included in the OpenBMC tree temporarily

TL;DR

If you require a patch added to the OpenBMC tree, follow these steps:

  1. Submit your patch upstream. It doesn't need to be upstream, but it should be on it's way, and not have any unresolved design concerns
  2. If the patch has been applied to upstream, then cherry pick the commit to the OpenBMC tree using git cherry-pick -x -s ${COMMIT_HASH}. This way, the original commit hash will be added to the commit message
  3. Use git format-patch --subject-prefix="PATCH linux ${BRANCH}" --to=openbmc@lists.ozlabs.org --to=andrew@codeconstruct.com.au --to=tan.siewert@9elements.com --cc=joel@jms.id.au to create a formatted patch. For u-boot, use PATCH u-boot as subject prefix

Developing a new driver

When developing a new driver, your goal is to have the code accepted upstream. The first step should be to check that there is no existing driver for the hardware you wish to support. Check the OpenBMC dev- branches, check upstream, and if you do not find support there ask on the mailing list.

Once you are sure a driver needs to be written, you should develop and test the driver, before sending it upstream to the relevant maintainers. You should feel welcome to cc the OpenBMC list when sending upstream, so other kernel developers can provide input where appropriate. Be sure to follow the (upstream development process)[https://www.kernel.org/doc/Documentation/process/submitting-patches.rst].

In the past patches underwent 'pre-review' on the OpenBMC mailing list. While this is useful for developers who are not familiar with writing kernel code, it has lead to confusion about the upstreaming process, so now we do all of our development in the community.

Once the driver has been accepted upstream, send the good news to the OpenBMC list with a reference to the upstream tree. This may be Linus' tree, or it might be one of the subsystem maintainers. From there the OpenBMC kernel team can decide how best to include your code in the OpenBMC tree.

Exceptions

There are cases where waiting for upstream acceptance will delay the bring-up of a new system. This should be avoided through careful planning and early development of the features upstream, but where this has not happened we can choose to carry the patches in the OpenBMC tree while upstream development continues.

Another exception to the upstream first rule is where patches are modifying files that are not upstream. This currently includes the aspeed board file arch/arm/mach-aspeed/aspeed.c, and the device tree source files dts. The board file should go away when we get drivers written for all of the functionality; for now it contains some hacks relating to LPC and early init.

If you find yourself adding to arch/arm/mach-aspeed/aspeed.c, first send an email to the OpenBMC list to get the opinion of the kernel developers. Patches to aspeed.c will be treated with some prejudice as the file will be removed once we have drivers for all of the Aspeed peripherals.

U-Boot

OpenBMC maintains its own u-boot fork at https://github.com/openbmc/u-boot.

The v2019.04-aspeed-openbmc branch is heavily diverged from upstream v2019.04, mostly because of the ASPEED support it carries, and is not compatible with the latest upstream u-boot. As a consequence, functionality that exists in current upstream u-boot may not be available, and may not be possible to be backported.

Which tree a patch belongs in depends on the SoC:

  • ASPEED AST2600 and earlier: patches go to the diverged v2019.04 tree. Sending the change upstream as well is welcome, but we cannot guarantee that the upstream code will work on these platforms.
  • ASPEED AST2700 and later: patches must be maintained upstream. They will not be backported to v2019.04.
  • Non-ASPEED SoCs: same rule as AST2700, patches must be maintained upstream. SoC support will not be backported to v2019.04.

Device trees

Device trees in u-boot are a special case. Unlike the kernel, u-boot on OpenBMC usually only needs to bring up enough hardware to load the kernel, and the default EVB device tree is usually sufficient for that.

Only send a machine-specific device tree for u-boot if it is genuinely required, for example when u-boot itself is used for netbooting and needs a correctly described network or storage path, or when your platform requires ECC or similar.

Testing

Before submitting patches it is recommended you boot test on at least the Qemu platforms, and whatever hardware you have available.

Tips and Tricks

Some general hints for kernel development

Out-of-tree builds

You can build a kernel out of the yocto environment, by using the initramfs (from a pre-existing yocto build) directly:

make ARCH=arm \
    O=obj \
    CROSS_COMPILE=arm-linux-gnueabihf- \
    CONFIG_INITRAMFS_SOURCE=.../obmc-phosphor-image-palmetto.cpio.gz

(adjust O and CROSS_COMPILE parameters as appropriate).

You'll need to use a relevant BMC defconfig (e.g. aspeed_g4_defconfig or aspeed_g5_defconfig) as your base kernel configuration.

The cpio can be found under the relevant machine directory in the following yocto output directory:

 build/tmp/deploy/images/

Building a uImage

To build a uImage (for example, to netboot):

# build a zImage using the obmc rootfs
make ARCH=arm \
    O=obj \
    CROSS_COMPILE=arm-linux-gnueabihf- \
    CONFIG_INITRAMFS_SOURCE=/path/tp/obmc-phosphor-image-palmetto.cpio.gz

# create a combined zImage + DTB image
cat obj/arch/arm/boot/zImage \
    obj/arch/arm/boot/dts/aspeed-bmc-opp-palmetto.dtb \
        > obj/aspeed-zimage

# create a uImage
./scripts/mkuboot.sh -A arm -O linux -C none -T kernel \
    -a 0x40008000 -e 0x40008000 -n $USER-`date +%Y%m%d%H%M` \
    -d obj/aspeed-zimage obj/uImage

Note that some systems may have upgraded to a FIT-based u-boot, where the old uImage format is no longer accepted.