There are two paths to booting Linux on the POWER9 Functional Simulator, one
using the simulated RTAS layer, the other using skiboot. Of these two methods,
using skiboot is considered the more supported option because bare-metal RTAS
support in the upstream Linux kernel is not actively being worked on any more
so it may cease to function correctly at some point in the future. As such
we'll cover using skiboot first.


-------------------------------------------------------------------------------
Using skiboot

When booting Linux using skiboot you will need three things:
1. a suitable disk image
2. a suitable powerpc kernel
3. a suitable skiboot lid

=== Quickstart ===

We have provided three scripts to get users up and running quickly:
* fetch_disk_image.sh         - downloads and decompresses a LE disk image
* fetch_vmlinux.sh            - downloads the powerpc kernel (vmlinux)
* fetch_skiboot.sh            - downloads the skiboot lid

As part of the Software Development Toolkit for PowerLinux, a little endian
disk image based on Debian is provided. fetch_disk_image.sh will download and
decompress this disk image, which will inflate to 10G. You can resize this
image using the following steps (here we resize it to 5GB):
  1. e2fsck -f debian-ppc64le.img
  2. resize2fs debian-ppc64le.img 5G

NOTE: The root user's password for this disk image is "mambo".

The SDK for PowerLinux also provides a pre-compiled little-endian Linux kernel
that has been patched to include two simulator-specific out-of-tree kernel
drivers: systemsim_bd and systemsim_net, affectionately known as bogus_disk
and bogus_net. Download this pre-compiled kernel with fetch_vmlinux.sh.

The last piece of the puzzle, the skiboot lid, is also thoughtfully provided
by the SDK team. Download it using fetch_skiboot.sh.

Once you have all three components in place you can use the provided
boot-linux-le-skiboot.tcl from run/p9/linux/ to boot your simulated POWER9
system. This tcl script expects the disk image to be called disk.img, so
you'll need to either rename your disk image to be disk.img or create a
symlink to it called disk.img.

See the sections below for more information on skiboot, and the Linux kernel.


-------------------------------------------------------------------------------
Using simulated RTAS

When booting Linux using the simulated RTAS functionality you will need just
two things:
1. a suitable disk image
2. a suitable powerpc kernel

=== Quickstart ===

Of the three scripts outlined above, you will only need to use the first two:
* fetch_disk_image.sh         - downloads and decompresses the LE disk image
* fetch_vmlinux.sh            - downloads the powerpc kernel (vmlinux)

Once you have downloaded the disk image and the pre-compiled kernel, using
fetch_disk_image.sh and fetch_vmlinux.sh respectively, you can you can use
the boot-linux-le-rtas.tcl from run/p9/linux/ to boot your simulated POWER9
system. This tcl script also expects the disk image to be called disk.img, so
you'll need to either rename your disk image to be disk.img or create a
symlink to it called disk.img.

See the sections below for more information on skiboot, and the Linux kernel.


-------------------------------------------------------------------------------
More Detail: kernel

A suitable powerpc kernel is one that has two out-of-tree kernel drivers
compiled in: systemsim_bd and systemsim_net, affectionately known as
bogus_disk and bogus_net.

The quickest way to a kernel with these drivers compiled in is to use the
fetch script outlined in the Quickstart sections above.

If you would like to compile your own kernel from source, a patched upstream
source tree can be found here:
https://github.com/rafaelsene/linux

It's easiest to start with pseries_le_defconfig and then ensure that the
CONFIG_PPC_SYSTEMSIM platform has been enabled so that you can build the
CONFIG_BLK_DEV_SYSTEMSIM and CONFIG_SYSTEMSIM_NET into the kernel (don't
build them as modules or you'll also need to load in an initrd).

-------------------------------------------------------------------------------
More Detail: skiboot

The quickest way to a skiboot lid is to use the fetch script outlined in the
Quickstart section above.

If you would like to compile your own skiboot lid, you can do so using the
source code found here:
https://github.com/open-power/skiboot
