This README file contains information on the contents of the
meta-raspberry-pi-xen layer.

Please see the corresponding sections below for details.

Dependencies
============

  URI: git://git.yoctoproject.org/poky
  branch: dunfell
 
  URI: git://git.yoctoproject.org/meta-virtualization
  branch: dunfell

  URI: git://git.yoctoproject.org/meta-raspberrypi
  branch: dunfell

Patches
=======

Please submit any patches against the meta-raspberry-pi-xen layer to
the maintainer:

Maintainer: Corey Minyard <cminyard@mvista.com>

Table of Contents
=================

  I. Adding the meta-raspberry-pi-xen layer to your build
 II. Using the Montavista 5.4 kernel
III. Misc


I. Adding the meta-raspberry-pi-xen layer to your build
=======================================================

The easiest way to use this layer is to use the MontaVista OpenCGX
releases.  Go to
https://github.com/MontaVista-OpenSourceTechnology/opencgx-rasberrypi
and follow the instructions for installation.

Then get this layer via git and add it to bblayers

  git clone https://github.com/MontaVista-OpenSourceTechnology/meta-raspberrypi-xen.git ../layers/meta-raspberrypi-xen
  (cd $TOPDIR/layers/meta-raspberrypi-xen; git checkout dunfell)
  bitbake-layers add-layer $TOPDIR/layers/meta-raspberrypi-xen

Add the following to your local.conf:

  MACHINE = "raspberrypi4-64-xen"
  IMAGE_FSTYPES = "tar.xz ext3 rpi-sdimg"

If you are using lvm (like will be shown below) add:

IMAGE_INSTALL_append = " lvm2 kernel-module-linear kernel-module-dm-mod"

plus whatever else you need and build away:

  bitbake <imagename>

Where <imagename> is the image you want to build, like core-image-minimal or
whatever.  Then put in your microsd card, unmount any directories that get
mounted from it, and do the following command:

  sudo dd if=tmp/deploy/images/raspberrypi4-64-xen/<imagename>-raspberrypi4-64-xen.rpi-sdimg of=/dev/mmcblk0 bs=1M

If you want, you can resize the root filesystem to take some or all of the mmc
device.  To do that, use fdisk to make the second partition bigger, and use
resize2fs to resize the filesystem.  Make sure that the start sector does not
change, and don't make it smaller.  Something like:

  $ sudo fdisk /dev/mmcblk0
  Welcome to fdisk (util-linux 2.31.1).
  Changes will remain in memory only, until you decide to write them.
  Be careful before using the write command.

  Command (m for help): p
  Disk /dev/mmcblk0: 58.5 GiB, 62851645440 bytes, 122757120 sectors
  Units: sectors of 1 * 512 = 512 bytes
  Sector size (logical/physical): 512 bytes / 512 bytes
  I/O size (minimum/optimal): 512 bytes / 512 bytes
  Disklabel type: dos
  Disk identifier: 0x33b29282

  Device         Boot Start     End Sectors  Size Id Type
  /dev/mmcblk0p1 *     8192   90111   81920   40M  c W95 FAT32 (LBA)
  /dev/mmcblk0p2      90112 1433599 1343488  656M 83 Linux

  Command (m for help): d
  Partition number (1,2, default 2): 2

  Partition 2 has been deleted.

  Command (m for help): n
  Partition type
     p   primary (1 primary, 0 extended, 3 free)
     e   extended (container for logical partitions)
  Select (default p): p
  Partition number (2-4, default 2): 
  First sector (2048-122757119, default 2048): 90112
  Last sector, +sectors or +size{K,M,G,T,P} (90112-122757119, default 122757119): +10G

  Created a new partition 2 of type 'Linux' and of size 10 GiB.
  Partition #2 contains a ext3 signature.

  Do you want to remove the signature? [Y]es/[N]o: n

  Command (m for help): w

  The partition table has been altered.
  Calling ioctl() to re-read partition table.
  Syncing disks.

  $ sudo resize2fs /dev/mmcblk0p2 
  resize2fs 1.44.1 (24-Mar-2018)
  Resizing the filesystem on /dev/mmcblk0p2 to 15333376 (4k) blocks.
  The filesystem on /dev/mmcblk0p2 is now 15333376 (4k) blocks long.

  $ sync

Note that I created a 10GB partition and left the rest of the space
for the domU targets.  What you need to do on the size may vary
depending on how you configure the disk space for domU.  The
instructions below will show how to do lvm.

Then remove the mmc, put it in your Pi and boot on the serial console.
If you include e2fsprogs-resize2fs in your image, you can do the above
process on the target itself.

Add a bridge named xenbr0.  First do:

  ifdown eth0

Then edit /etc/network/interfaces, comment out anything to do with
eth0, then add:

  auto xenbr0
  iface xenbr0 inet dhcp
          pre-up bridge-ifupdown eth0
          post-down bridge-ifupdown eth0

Then you can do:

  ifup xenbr0

and you will have a working bridge.  Obviously, you should do this on
a serial console.  Note that this is different than the (more or less)
standard way of doing it, with bridge_ports, but it's easier to use
and bridge_ports is not enabled on yocto.

For lvm, use fdisk to add a 3rd partition with the rest of the space
on the mmc device and run:

  # pvcreate /dev/mmcblk0p3
    Failed to clear hint file.
    Physical volume "/dev/mmcblk0p3" successfully created.
  # vgcreate vg01 /dev/mmcblk0p3
    Failed to clear hint file.
    Volume group "vg01" successfully created

Build a domU
============

The Raspberry Pi kernel cannot be used for booting on a Xen domU, and
the dom0 filesystem has lots of packages that are useless outside of
dom0.  So instead, let's build another image.  Open another window and
cd to just below your current projects directory.  Then do:

  source setup.sh project-domU

Now edit conf/local.conf in your new project and add:

  MACHINE = "qemuarm64"
  IMAGE_FSTYPES = "tar.xz"
  IMAGE_INSTALL_append = " openssh"
  KERNEL_FEATURES += "xen.scc"

Now save and run:

  bitbake core-image-minimal

Now copy the filesystem and kernel for the domU instances onto the
target system dom0 using ssh.  These files will be:
  tmp/deploy/images/qemuarm64/core-image-minimal-qemuarm64.tar.xz
  tmp/deploy/images/qemuarm64/Image-qemuarm64.bin

I'm putting these files in /xen on the target dom0.

Configure domU on the target
============================

Now we are set to configure xen-tools.  Edit /etc/xen-tools/xen-tools.conf
to do this.

* Uncomment the line that says "lvm = vg0" and change vg0 to vg01

* Change install-method to be tar

* Set install-source to /xen/core-image-minimal-qemuarm64.tar.xz

* set tar-cmd to /bin/tar -xJf $src

* set dist to yocto-3.1

* Uncomment "dhcp = 1"

* Change kernel to /xen/Image-qemuarm64.bin and comment out
  initrd.

* You might want to adjust the size, memory, etc options.  Check the
  other options, you may want to change other things.  The file has
  fairly clear documentation.

Now run xen-create-image --hostname=<name>

where <name> is something like dom1.home.net, or whatever.  This will
create an lvm image based on your configuration and create
/etc/xen/dom1.home.net.  It will also print out something like:

Installation Summary
---------------------
Hostname        :  dom1.minyard.net
Distribution    :  yocto-3.1
MAC Address     :  00:16:3E:B5:22:13
IP Address(es)  :  dynamic
Root Password   :  JGyu8sFkHSsyQvaarNq8kRY

That root password is pretty important, save it for now.

You can then run:

  xl create -c /etc/xen/dom1.home.net

and the new kernel should start up in a Xen domain.  You can log in
with the given password, and then you are set.  Networking should come
up normally, so you can ssh into the domain (if you get the IP
address).

To leave the console, type ^].  The domain is still running, you can
reconnect with

  xl console dom1.home.net

Powering off in the subdomain will shut down the domain.  If you need
to destroy it because you can't do that, you can do:

  xl destroy dom1.home.net

II. Using the MontaVista 5.4 kernel
===================================

By default this will use the Raspberry Pi 4.19 standard kernel.  If
you want to use the MontaVista supported 5.4 kernel, you need to
follow the instructions for the meta-montavista-raspberrypi layer at
https://github.com/MontaVista-OpenSourceTechnology/meta-montavista-raspberrypi

Make sure to add:
PREFERRED_PROVIDER_virtual/kernel = "linux-mvista"
to your local.conf, or you won't get the new kernel.

III. Misc
=========

You cannot use the Raspberry Pi Xen kernel image in DomU.

Only the serial console is currently supported.  So you must have a compatible
serial interface.  I use the TTL-232R-RPi (you can search on Mouser, DigiKey,
or whatever for it).  Be careful with getting the pins right, make sure to look
for the square pad (pin 1) for reference.  Sometime vendors are showing the
bottom of the board.

The standard MontaVista tools will not automatically update this particular
repository added this way.  If you need to update, you will need to cd to
$TOPDIR/layers/meta-raspberrypi-xen and do a "git pull".  This will be better
integrated in the future.

The dom0 kernel gets 256M by default.  You can change this with

  RPI_DOM0_MEM = "xxxM"

in your local.conf

Reboot should be working now; changes were made in Xen to support this.