add layer meta-netboot to enable network boot over NBD (Network Block Device)

To enable the build of network bootable images, the following line must be
added to conf/local.conf:

   INHERIT += "netboot"

This layer contains recipes for the following components:
* busybox: activate the built-in NBD client
* initramfs-netboot: contains the init script started by the kernel,
  responsible for mounting the remote root filesystem then pivoting and
  exec'ing systemd
* initramfs-netboot-image: image to specify for building the initrd

More details are available in meta-netboot/README.

Bug-AGL: SPEC-175

Change-Id: Id2328dd9233d238cde77311e64e58344be244988
Signed-off-by: Stephane Desneux <stephane.desneux@iot.bzh>

1 files changed, 64 insertions, 0 deletions

diff --git a/meta-netboot/README b/meta-netboot/README
new file mode 100644
index 000000000..130477751
--- /dev/null
+++ b/meta-netboot/README
@@ -0,0 +1,64 @@
+meta-netboot
+============
+
+This layer contains some recipes and configuration adjustments to allow network boot through NBD (network block device).
+
+Content and usage
+-----------------
+
+This layer creates a new supplementary initrd image which can be downloaded through TFTP with the kernel.
+At boot time, the init script will try to mount the rootfs based on the following kernel command line parameters:
+* nbd.server: IP address to reach the NBD server
+* nbd.port: TCP port on which server is listening (default: 10809)
+* nbd.dev: nbd device to use (default: /dev/nbd0)
+* nbd.debug: activate debug mode (init script is then interruptible)
+
+The layer meta-netboot contains recipes for the following components:
+* busybox: activate the built-in NBD client
+* initramfs-netboot: contains the init script started by the kernel: basically, this script mounts the real root filesystem, then pivot_root on it and finally exec systemd.
+* initramfs-netboot-image: image to specify for building the initrd
+
+To enable the build of the netboot initrd and ext4 rootfs, add the following line in conf/local.conf:
+
+INHERIT += "netboot"
+
+
+Server side
+-----------
+
+On the server side (assuming that the build dir is stored in $BUILD) we can run:
+
+* a TFTP server, for example tftpd-hpa started with $BUILD/tmp/deploy/images as the TFTP dir:
+
+  /usr/sbin/in.tftpd --listen --user tftp --address 0.0.0.0:69 --secure $BUILD/tmp/deploy/images
+
+* a NBD server, for example xnbd-server, used to expose the whole ext4 rootfs as a network block device:
+
+  xnbd-server --target --lport 10809 $BUILD/tmp/deploy/images/$MACHINE/agl-demo-platform-$MACHINE.ext4
+
+
+Target side
+-----------
+
+On the target board, a specific setup should also be done. For example, for Renesas Porter board, the following U-boot environment could be used (adjust IP addresses !):
+
+------------------------------------------------------------------
+setenv 'bootkfile' 'uImage+dtb'
+setenv 'bootkaddr' '0x40007fc0'
+setenv 'bootifile' 'initramfs-netboot-image-porter.ext4.gz.u-boot'
+setenv 'bootiaddr' '0x50000000'
+setenv 'ipaddr' '<board_IP>'
+setenv 'serverip' '<server_IP>'
+
+setenv 'bootargs_console' 'console=ttySC6,38400 ignore_loglevel'
+setenv 'bootargs_video' 'vmalloc=384M video=HDMI-A-1:1280x960-32@60'
+setenv 'bootargs_extra' 'rw rootfstype=ext4 rootwait rootdelay=2'
+setenv 'bootargs_root' 'root=/dev/ram0 ramdisk_size=16384 ip=dhcp'
+setenv 'bootkload_net' 'tftp ${bootkaddr} porter/${bootkfile}'
+setenv 'bootiload_net' 'tftp ${bootiaddr} porter/${bootifile}'
+setenv 'bootcmd' 'setenv bootargs ${bootargs_console} ${bootargs_video} ${bootargs_root} ${bootargs_extra} nbd.server=${serverip}; run bootkload_net; run bootiload_net; bootm ${bootkaddr} ${bootiaddr}'
+
+saveenv # optional: saves env in flash
+run bootcmd # boots the board, executed automatically after power up
+------------------------------------------------------------------
+