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