1# OpenBMC kernel development 2 3> [!IMPORTANT] 4> 5> The kernel development philosphy described below also applies to OpenBMC's 6> u-boot fork. 7 8The OpenBMC project maintains a kernel tree for use by the project. The tree's 9general development policy is that code must be upstream first. This is strongly 10desirable but not a hard requirement, and exceptions may be made on a 11case-by-case basis. If in doubt, start a discussion on the mailing list. 12 13The OpenBMC kernel tree is hosted at <https://github.com/openbmc/linux> and 14contains the set of patches that we carry. Ideally there would be no patches 15carried, as everything should be upstream. 16 17Your code will make it into the OpenBMC tree in these ways, from most to least 18desirable: 19 201. When the OpenBMC kernel moves to a new upstream release 212. By backporting upstream commits from a newer kernel version to the OpenBMC 22 kernel 233. Patches included in the OpenBMC tree temporarily 24 25## TL;DR 26 27If you require a patch added to the tree, follow these steps: 28 291. Submit your patch upstream. It doesn't need to be upstream, but it should be 30 on it's way, and not have any unresolved design concerns 312. Use 32 `git format-patch --subject-prefix="PATCH linux ${BRANCH}" --to=openbmc@lists.ozlabs.org --to=joel@jms.id.au --to=andrew@codeconstruct.com.au` 33 to create a formatted patch 34 35## Developing a new driver 36 37When developing a new driver, your goal is to have the code accepted upstream. 38The first step should be to check that there is no existing driver for the 39hardware you wish to support. Check the OpenBMC `dev-` branches, check upstream, 40and if you do not find support there ask on the mailing list. 41 42Once you are sure a driver needs to be written, you should develop and test the 43driver, before sending it upstream to the relevant maintainers. You should feel 44welcome to cc the OpenBMC list when sending upstream, so other kernel developers 45can provide input where appropriate. Be sure to follow the (upstream development 46process)[https://www.kernel.org/doc/Documentation/process/submitting-patches.rst]. 47 48In the past patches underwent 'pre-review' on the OpenBMC mailing list. While 49this is useful for developers who are not familiar with writing kernel code, it 50has lead to confusion about the upstreaming process, so now we do all of our 51development in the community. 52 53Once the driver has been accepted upstream, send the good news to the OpenBMC 54list with a reference to the upstream tree. This may be Linus' tree, or it might 55be one of the subsystem maintainers. From there the OpenBMC kernel team can 56decide how best to include your code in the OpenBMC tree. 57 58### Exceptions 59 60There are cases where waiting for upstream acceptance will delay the bring-up of 61a new system. This should be avoided through careful planning and early 62development of the features upstream, but where this has not happened we can 63choose to carry the patches in the OpenBMC tree while upstream development 64continues. 65 66Another exception to the upstream first rule is where patches are modifying 67files that are not upstream. This currently includes the aspeed board file 68`arch/arm/mach-aspeed/aspeed.c`, and the device tree source files `dts`. The 69board file should go away when we get drivers written for all of the 70functionality; for now it contains some hacks relating to LPC and early init. 71 72If you find yourself adding to `arch/arm/mach-aspeed/aspeed.c`, first send an 73email to the OpenBMC list to get the opinion of the kernel developers. Patches 74to `aspeed.c` will be treated with some prejudice as the file will be removed 75once we have drivers for all of the Aspeed peripherals. 76 77## Testing 78 79Before submitting patches it is recommended you boot test on at least the Qemu 80platforms, and whatever hardware you have available. 81 82## Tips and Tricks 83 84Some general hints for kernel development 85 86### Out-of-tree builds 87 88You can build a kernel out of the yocto environment, by using the initramfs 89(from a pre-existing yocto build) directly: 90 91```sh 92make ARCH=arm \ 93 O=obj \ 94 CROSS_COMPILE=arm-linux-gnueabihf- \ 95 CONFIG_INITRAMFS_SOURCE=.../obmc-phosphor-image-palmetto.cpio.gz 96``` 97 98(adjust `O` and `CROSS_COMPILE` parameters as appropriate). 99 100You'll need to use a relevant BMC defconfig (e.g. `aspeed_g4_defconfig` or 101`aspeed_g5_defconfig`) as your base kernel configuration. 102 103The cpio can be found under the relevant machine directory in the following 104yocto output directory: 105 106```sh 107 build/tmp/deploy/images/ 108``` 109 110### Building a uImage 111 112To build a uImage (for example, to netboot): 113 114```sh 115# build a zImage using the obmc rootfs 116make ARCH=arm \ 117 O=obj \ 118 CROSS_COMPILE=arm-linux-gnueabihf- \ 119 CONFIG_INITRAMFS_SOURCE=/path/tp/obmc-phosphor-image-palmetto.cpio.gz 120 121# create a combined zImage + DTB image 122cat obj/arch/arm/boot/zImage \ 123 obj/arch/arm/boot/dts/aspeed-bmc-opp-palmetto.dtb \ 124 > obj/aspeed-zimage 125 126# create a uImage 127./scripts/mkuboot.sh -A arm -O linux -C none -T kernel \ 128 -a 0x40008000 -e 0x40008000 -n $USER-`date +%Y%m%d%H%M` \ 129 -d obj/aspeed-zimage obj/uImage 130``` 131 132Note that some systems may have upgraded to a FIT-based u-boot, where the old 133uImage format is no longer accepted. 134