1# OpenBMC kernel development 2 3The OpenBMC project maintains a fork of upstream Linux for patches that are not yet in the upstream kernel. The general policy is that code must be upstream first. Exceptions can be made on a case-by-case basis. If in doubt, start a dicsusion on the mailing list. 4 5The kernel tree hosted at https://github.com/openbmc/linux contains the set of patches that we carry. Ideally there would be no patches carried, as everything should be upstream. 6 7Your code will make it into the OpenBMC tree in these ways, from most to least desirable: 81. When the OpenBMC kernel moves to a new upstream release 92. By backporting upstream commits from a newer kernel version to the OpenBMC kernel 103. Patches included in the OpenBMC tree temporarily 11 12## TL;DR 13 14If you require a patch added to the tree, follow these steps: 15 161. Submit your patch upstream. It doesn't need to be upstream, but it should be on it's way 172. Use ```git format-patch --subject-prefix="PATCH linux dev-4.7" --to=openbmc@lists.ozlabs.org --to=joel@jms.id.au``` to create a formatted patch 18 19## Developing a new driver 20 21When 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` tree, check upstream, and if you do not find support there ask on the mailing list. 22 23Once 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 appropraite. Be sure to follow the (upstream development process)[https://www.kernel.org/doc/Documentation/SubmittingPatches]. 24 25In the past patches underwent 'pre-review' on the OpenBMC mailing list. While this is useful for developers who are not familiar with writing kenrel code, it has lead to confusion about the upstreaming process, so now we do all of our development in the community. 26 27Once 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 kenrel team can decide how best to include your code in the OpenBMC tree. 28 29### Exceptions 30 31There 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 chose to carry the patches in the OpenBMC tree while the upstream development is ongoing. 32 33Another 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 `dtbs`. The board file should go away when we get drivers written for all of the functionaltiy; for now it contains some hacks relating to LPC and early init. 34 35## Getting existing code in the tree 36 37The OpenBMC kernel is currently based on the 4.7 series. If there is upstream code you would like backported, send it to hte list. Be sure to include the upstream commit SHA in the commit message. 38 39## Testing 40 41When moifying the tree we currently test on the following platforms: 42 43 - Palmetto, an OpenPower Power8 box containing an ast2400 with NCSI networking 44 - ast2500-evb, the Aspeed dev board with two PHYs 45 - Witherspoon, an OpenPower Power9 box containing an ast2500 with NCSI networking 46 - qemu-plametto and qemu-romulus 47 48Before submitting patches it is recommended you boot test on at least the Qemu platforms, and whatever hardware you have availaible. 49 50# Tips and Tricks 51 52Some general hints for kernel development 53 54## Out-of-tree builds 55 56You can build a kernel out of the yocto environment, by using the initramfs 57(from a pre-existing yocto build) directly: 58 59``` 60make ARCH=arm \ 61 O=obj \ 62 CROSS_COMPILE=arm-linux-gnueabihf- \ 63 CONFIG_INITRAMFS_SOURCE=/path/tp/obmc-phosphor-image-palmetto.cpio.gz 64``` 65 66(adjust `O` and `CROSS_COMPILE` parameters as appropriate). 67 68You'll need to use `aspeed_defconfig` as your base kernel configuration. 69 70The cpio can be found in the following yocto output directory: 71 72``` 73 build/tmp/deploy/images/palmetto/ 74``` 75 76## Building a uImage 77 78To build a uImage (for example, to netboot): 79 80``` 81# build a zImage using the obmc rootfs 82make ARCH=arm \ 83 O=obj \ 84 CROSS_COMPILE=arm-linux-gnueabihf- \ 85 CONFIG_INITRAMFS_SOURCE=/path/tp/obmc-phosphor-image-palmetto.cpio.gz 86 87# create a combined zImage + DTB image 88cat obj/arch/arm/boot/zImage \ 89 obj/arch/arm/boot/dts/aspeed-bmc-opp-palmetto.dtb \ 90 > obj/aspeed-zimage 91 92# create a uImage 93./scripts/mkuboot.sh -A arm -O linux -C none -T kernel \ 94 -a 0x40008000 -e 0x40008000 -n $USER-`date +%Y%m%d%H%M` \ 95 -d obj/aspeed-zimage obj/uImage 96``` 97