TipsAndTricks/KernelDevelopmentWithEsdk

== Overview ==
This article describes an efficient workflow for Linux kernel development using Yocto Project. The goal is to get the build, deploy and test cycle to under a minute. We will be working with the generix86-64 BSP and the Intel Minnowboard Turbot in this article but the process is the same for any platform and CPU architecture. 
The extensible SDK (eSDK) is a key part of this workflow for a number of reasons 
# It contains the target toolchain which is not easily accessible in the bitbake environment
# It contains devtool which gives you an easy way of getting the kernel source your target is using (if using linux-yocto or linux-intel)
# devtool will also automatically create patches for your kernel updates and add them to the the kernel recipe
There are two separate steps to this process
# Build or download an eSDK for your platform
# Install and use that eSDK to build your kernel
== Build Extensible SDK ==
Open a new terminal window, we'll refer to this terminal as your bitbake terminal. First we'll checkout poky and configure bitbake environment.
 $ cd ~
 $ git clone -b pyro git://git.yoctoproject.org/poky 
 $ source poky/oe-init-build-env
Now we need to do some configuration for the Minnowboard image. 
* Set MACHINE (as default is qemux86)
* Enable kernel modules (disabled by default for minimal images)
Add the following to conf/local.conf
 MACHINE = "genericx86-64"
 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules"
Now build an extensible SDK installer for the Minnowboard in the bitbake terminal
 $ bitbake core-image-minimal -c populate_sdk_ext 
The eSDK installer can be found in /path_to_build_directory/kernel-dev/tmp/deploy/sdk/
 ./tmp/deploy/sdk/poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-2.3.1.sh
== Install Extensible SDK ==
Run the installer as follows. If you do not want to use the default ~/poky_sdk directory for installation of the toolchain, use the -d option to specify a destination.
$ ./poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-2.3.1.sh
Poky (Yocto Project Reference Distro) Extensible SDK installer version 2.3.1
============================================================================
Enter target directory for SDK (default: ~/poky_sdk): 
You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed[Y/n]? Y
Extracting SDK......................................done
Setting it up...
Extracting buildtools...
Preparing build system...
Parsing recipes: 100% |#########################################################################################################| Time: 0:00:52
Initialising tasks: 100% |######################################################################################################| Time: 0:00:04
Checking sstate mirror object availability: 100% |##############################################################################| Time: 0:00:00
Parsing recipes: 100% |#########################################################################################################| Time: 0:00:33
Initialising tasks: 100% |######################################################################################################| Time: 0:00:00
done
SDK has been successfully set up and is ready to be used.
Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
 $ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux
Take note of the final line, which shows you the environment setup script you must run each time you want to use the eSDK.
== Create a Layer ==
We also need to create a layer to take the kernel patches we'll be creating. 
 $ cd ~/poky
 $ yocto-layer create my-kernel -o ../meta-my-kernel
 Please enter the layer priority you'd like to use for the layer: [default: 6] 
 Would you like to have an example recipe created? (y/n) [default: n] 
 Would you like to have an example bbappend file created? (y/n) [default: n]
 New layer created in ../meta-my-kernel.
 Don't forget to add it to your BBLAYERS (for details see ../meta-my-kernel/README).
As directed, we need to add our layer to BBLAYERS as follows:
 $ cd ~/poky/build
 $ bitbake-layers add-layer ../../meta-my-kernel
== Setup your ESDK build environment (ESDK terminal) ==
YOU MUST OPEN A NEW TERMINAL WHEN USING THE ESDK. DO NOT RE-USE YOUR BITBAKE TERMINAL.
Open a new terminal and setup your build environment. We'll refer to this terminal as your 'ESDK terminal'. Run the setup script given by the installer.
 $ source /path/to/esdk/environment-setup-core2-64-poky-linux
 "SDK environment now set up; additionally you may now run devtool to perform development tasks.
 Run devtool --help for further details.
If you see this
 WARNING: attempting to use the extensible SDK in an environment set up to run bitbake - this may lead to unexpected results. Please source this script in a 
 new shell session instead."
You didn't open a new terminal!
== Build initial image with ESDK ==
In the ESDK terminal, build the image
$ devtool build-image
Parsing recipes: 100% |##########################################| Time: 0:00:05
Parsing of 830 .bb files complete (0 cached, 830 parsed). 1299 targets, 47 skipped, 0 masked, 0 errors.
WARNING: No packages to add, building image core-image-minimal unmodified
Loading cache: 100% |############################################| Time: 0:00:00
Loaded 1299 entries from dependency cache.
NOTE: Resolving any missing task queue dependencies
Initialising tasks: 100% |#######################################| Time: 0:00:07
Checking sstate mirror object availability: 100% |###############| Time: 0:00:00
NOTE: Executing SetScene Tasks
NOTE: Executing RunQueue Tasks
NOTE: Tasks Summary: Attempted 2866 tasks of which 2604 didn't need to be rerun and all succeeded.
NOTE: Successfully built core-image-minimal. You can find output files in /path/to/esdk/tmp/deploy/images/genericx86-64
Now flash to image to USB stick, assuming USB stick is on /dev/sdd
 $ sudo dd if=tmp/deploy/images/genericx86-64/core-image-minimal-genericx86-64.wic of=/dev/sdd bs=1MB
 $ sync
Boot the Minnowboard with this image and check to be sure that everything is OK.
== Working with Yocto kernel ==
=== Checkout kernel source ===
First we must use devtool to checkout the kernel source code in its workspace. Do the following in the ESDK terminal. Note that we use the virtual kernel provider so we don't need to know the kernel recipe name. 
$ devtool modify virtual/kernel
Loading cache: 100% |########################################################################################################################| Time: 0:00:00
Loaded 1300 entries from dependency cache.
NOTE: Mapping virtual/kernel to linux-yocto
Loading cache: 100% |########################################################################################################################| Time: 0:00:00
Loaded 1300 entries from dependency cache.
NOTE: Executing RunQueue Tasks
NOTE: Executing do_fetch...
NOTE: Executing do_unpack...
NOTE: Tasks Summary: Attempted 2 tasks of which 0 didn't need to be rerun and all succeeded.
NOTE: Executing RunQueue Tasks
NOTE: Executing do_kernel_checkout...
NOTE: Tasks Summary: Attempted 3 tasks of which 2 didn't need to be rerun and all succeeded.
NOTE: Patching...
NOTE: Executing RunQueue Tasks
NOTE: Executing do_validate_branches...
NOTE: Executing do_kernel_metadata...
NOTE: Executing do_patch...
NOTE: Tasks Summary: Attempted 6 tasks of which 3 didn't need to be rerun and all succeeded.
NOTE: Generating kernel config
NOTE: Executing RunQueue Tasks
NOTE: Executing do_kernel_configme...
NOTE: Executing do_prepare_recipe_sysroot...
NOTE: Executing do_configure...
NOTE: Tasks Summary: Attempted 9 tasks of which 6 didn't need to be rerun and all succeeded.
NOTE: Copying kernel config to srctree
NOTE: Source tree extracted to /home/scottrif/poky_sdk/workspace/sources/linux-yocto
NOTE: Recipe linux-yocto now set up to build from /home/scottrif/poky_sdk/workspace/sources/linux-yocto
There is a bug that may cause error messages such as the following to be displayed. These can be ignored, the source code will be correct checked out.
 ERROR: Taskhash mismatch 2c793438c2d9f8c3681fd5f7bc819efa versus be3a89ce7c47178880ba7bf6293d7404 for /path/to/esdk/layers/poky/meta/recipes-kernel/linux/linux-yocto_4.10.bb.do_unpack
=== Edit and build driver ===
Kernel source will be in the location shown at end of the devtool modify virtual/kernel output. Let's make a trivial change to the serial driver in drivers/tty/serial/8250/8250_core.c. After the line
 pr_info("Serial: 8250/16550 driver, %d ports, IRQ sharing %sabled\n",
 nr_uarts, share_irqs ? "en" : "dis");
Add the line
 pr_info("Serial: 8250/16550 driver modified with eSDK");
To build the updated kernel source, in the SDK terminal run make in your kernel source folder. Adjust the -j option to match number of cores on your workstation.
 $ make -C workspace/sources/linux-yocto -j4
Alternatively, you can run
 $ devtool build linux-yocto
=== Create image with new kernel 2.4 Way ===
Note: There are several bugs outstanding to make this process a little easier as of 9/2017. They mostly deal with unwieldy paths and are easy to work around. I will detail the workarounds here and if it is clear that you don't need them due to the bugs getting fixed and merged, so much the better. 
Below I detail using kpartx to pull apart a wic image so you can just copy your kernel (and other artifacts if needed like a dtd) into the image to shorten turnaround time. In this section, we will exploit the new features in wic that allow us to do the same thing but easier. This does require you to install the host side mtools package, currently.
==== Image manipulation with wic to facilitate kernel development ====
* See what's in your image:
 $ wic ls /tmp/core-image-base-qemux86-64.wic 
 Num Start End Size Fstype
 1 1048576 25534463 24485888 fat16
 2 26214400 13938011135 13911796736 ext4
* See what's in your partition:
 $ wic ls /tmp/core-image-base-qemux86-64.wic:1
If you see the following error:
 ERROR: _exec_cmd: /usr/bin/mdir -i /tmp/wic-parttfokuwra ::/ returned '1' instead of 0
 output: Total number of sectors (47824) not a multiple of sectors per track (32)!
 Add mtools_skip_check=1 to your .mtoolsrc file to skip this test
Just do what it says and put 
 mtools_skip_check=1 
into your ~/.mtoolsrc file and you will get:
 $wic ls /tmp/core-image-base-qemux86-64.wic:1
 Volume in drive : is boot 
 Volume Serial Number is 6BF1-7DEC 
 Directory for ::/
 libcom32 c32 186500 2017-10-03 21:53 
 libutil c32 24148 2017-10-03 21:53 
 syslinux cfg 220 2017-10-03 21:53 
 vesamenu c32 27104 2017-10-03 21:53 
 vmlinuz 7397936 2017-10-03 21:53 
 5 files 7 635 908 bytes
 16 582 656 bytes free
* remove the old kernel from your image:
 $ wic rm /tmp/core-image-base-qemux86-64.wic:1/vmlinuz
* add in your freshly constructed kernel.
** if you built the kernel with devtool, the resulting bzImage is in the tmp/work directory as below.
 $ wic cp ~/poky_sdk/tmp/work/qemux86_64-poky-linux/linux-yocto/4.12.12+git999-r0/linux-yocto-4.12.12+git999/arch/x86/boot/bzImage /tmp/core-image-base-qemux86-64.wic:1/vmlinuz
** if you built it straight with make in the workspace/linux-yocto directory, it is in a more standard place:
 $ cp workspace/sources/linux-yocto/arch/x86/boot/bzImage /tmp/core-image-base-qemux86-64.wic:1/vmlinuz
* then you can dd your wic image onto a sd card/usb key and you can test your target.
** note: bmap-copy using the bmap tools is generally ~ 10x-20x faster than a straight dd. Docs -> Official bmaptool copy docs
=== Create image with new kernel Pre 2.4 Way ===
Normally you'd make a new image with devtool build-image but this can take several minutes or so and messes with the kernel source folder. A faster option is to use kpartx to splice the new kernel into the image you have already built. NOTE: If your build system does not have kpartx installed, be sure you install it.
First make a copy of your wic file in say /tmp
 $ cp tmp/deploy/images/genericx86-64/core-image-minimal-genericx86-64.wic /tmp
Then create loopback devices for each partition in wic file. 
NOTE: The first unused loopback device is automatically allocated. The example command output here uses a variable "X" to indicate the loopback device. The actual output you get when you run the command will list the actual loopback devices (e.g. "loop0p1", "loop0p2", and "loop0p3").
 $ sudo kpartx -v -a /tmp/core-image-minimal-genericx86-64.wic
 add map loopXp1 (253:6): 0 47446 linear /dev/loopX 2048
 add map loopXp2 (253:7): 0 119356 linear /dev/loopX 51200
 add map loopXp3 (253:8): 0 90112 linear /dev/loopX 170556
Kernel is in the first device, so let's mount /dev/mapper/loopXp1 to take a look
NOTE: Replace loopXp1 with the automatically allocated loopback device (e.g loop0p1).
 $ sudo mkdir /mnt/wic-p1
 $ sudo mount /dev/mapper/loopXp1 /mnt/wic-p1
Now copy over new kernel
 $ sudo cp workspace/sources/linux-yocto/arch/x86/boot/bzImage /mnt/wic-p1
Then unmount and unkpartx...
NOTE: Replace "loopX" with the automatically allocated loopback device from earlier (e.g "loop0").
 $ sudo umount /mnt/wic-p1
 $ sudo kpartx -d /dev/loopX
Now flash image
 $ dd if=/tmp/core-image-minimal-genericx86-64.wic of=/dev/sdd bs=1MB
 $ sync
Boot Minnowboard, log on and look in log for driver message
 # root@genericx86-64:~# dmesg | grep Serial:
 Serial: 8250/16550 driver, 4 ports, IRQ sharing disabled
 Serial: 8250/16550 driver modified with eSDK
It worked!
=== Export patches and create a bbappend file ===
To export your commits as patches and a bbappend file use the following command in the ESDK terminal. We'll target the "my-kernel" layer we created in the bitbake terminal 
 $ devtool finish linux-yocto /path/to/meta-my-kernel
The patches and the bbappend can be found in /path/to/meta-my-kernel/recipes-kernel/linux.
== Working with upstream kernel ==
Slightly different workflow where we use a kernel from kernel.org.
Content TBD
== Build image with your modified kernel ==
You can now build an image which will include your kernel patches.
Execute the following command from your build directory in the bitbake terminal
 bitbake core-image-minimal