6 files changed, 191 insertions, 0 deletions
diff --git a/doc/func/autoboot.rst b/doc/func/autoboot.rst
new file mode 100644
index 0000000..a6379f9
--- /dev/null
+++ b/doc/func/autoboot.rst
@@ -0,0 +1,32 @@
+.. _auto-boot:
+
+Auto Boot Order
+===============
+
+With autoboot enabled Petitboot will consider the relative priority of each new default boot option it discovers to determine what should be booted automatically.
+
+Note that a boot option must be marked for autoboot ("default") in its own configuration file for Petitboot to autoboot it. For example:
+
+.. code-block:: none
+
+   default linux
+
+   label linux
+   kernel ./pxe/de-ad-de-ad-be-ef.vmlinuz
+   append command line initrd=./pxe/de-ad-de-ad-be-ef.initrd
+
+Boot Priority
+-------------
+
+Petitboot can prioritise boot options based on the following attributes:
+
+* Device type (Disk, Network, USB..)
+* Partition (eg, sda2)
+* Interface name (eg. eth0)
+* LVM logical-volume name (eg. "rhel7-boot-lv")
+
+Once started Petitboot will begin to countdown from the configured timeout (default 10 seconds). During this time any default boot option that is discovered is compared against the configured priority list and the current option with the highest priority. If the new option has a higher priority based on the boot order than the current option then it becomes the current option and will be booted once the countdown completes.
+
+Note that unlike some other bootloaders Petitboot does *not* wait for devices in the boot order. For example if the boot order was "Network, Disk" with a 10 second default and a disk option was found but a hypothetic network option would take longer than 10 seconds to be found (eg. slow network or DHCP server), then Petitboot won't know about it and will boot the disk option. In most cases the appropriate solution if a user runs into this is to increase the timeout value to a suitable length of time for their environment.
+
+Note that :ref:`ipmi` overrides will take precedence over any configured boot order.
diff --git a/doc/func/ipmi.rst b/doc/func/ipmi.rst
new file mode 100644
index 0000000..8f9fa05
--- /dev/null
+++ b/doc/func/ipmi.rst
@@ -0,0 +1,29 @@
+.. _ipmi:
+
+IPMI
+====
+
+Petitboot uses inband-IPMI_ on platforms that support it to report information or modify booting behaviour:
+
+.. _inband-IPMI: https://en.wikipedia.org/wiki/Intelligent_Platform_Management_Interface
+
+Platform Information
+--------------------
+
+Basic BMC information is read via the "Get Device ID" and "Get LAN Configuration Parameters" commands and shown in the System Information screen. On some platforms with an AMI BMC the OEM command "Get Device ID Golden" will also be issued to get the BMC's secondary side information.
+
+Just before successful boot Petitboot will set the OS boot sensor (command `0x30`) to notify the BMC of a successful boot.
+
+Boot Device Overrides
+---------------------
+
+Petitboot supports IPMI boot device overrides. These can be set on the BMC to temporarily override the autoboot behaviour. These are limited to the broad types of "Network", "Disk", "Safe", "CDROM", and "Setup".
+
+If a boot option matches one of these options it receives the highest priority regardless of the boot order. The exceptions are "Setup" which temporarily disables autoboot, and "Safe" which does the same and also enters "safe mode" which prevents setting up any devices until the user issues a "Rescan" command.
+
+Boot Initiator Mailbox
+----------------------
+
+Petitboot also supports the "Boot Initiator Mailbox" parameter which behaves similarly to an override but lets a full replacement boot order be set. Support for this on the BMC side is relatively limited so far, but more details can be found here_.
+
+.. _here: https://sthbrx.github.io/blog/2018/12/19/ipmi-initiating-better-overrides/
diff --git a/doc/func/parsers.rst b/doc/func/parsers.rst
new file mode 100644
index 0000000..92281bd
--- /dev/null
+++ b/doc/func/parsers.rst
@@ -0,0 +1,18 @@
+Configuration Parsers
+=====================
+
+Petitboot can read a variety of configuration formats. Generally it does this in one of two ways:
+
+Bison/Flex Parsers
+------------------
+
+The "grub2" and "native" parsers are implemented with the Bison parser and Flex lexer combo to define a grammar describing the configuration format. These parsers can hook into other Petitboot or C code as needed but for most scenarios just need a way to resolve resources (resource.h) and create boot options (device-handler.h).
+
+Writing a parser/grammar this way can be a bit more difficult at first but does lend itself to a more robust solution in the long term.
+
+Process-Pair Parsers
+--------------------
+
+Other parsers such as for PXE and SYSLINUX use a simpler mechanism provided by `parser-conf.c` In short this provides a way to load the configuration into a buffer and process each line as a key:value format. Where applicable the parser can provide it's own callbacks for these functions.
+
+This method is a lot easier to quickly construct a parser, especially for formats with relatively basic formats.
diff --git a/doc/func/plugins.rst b/doc/func/plugins.rst
new file mode 100644
index 0000000..53cf7a8
--- /dev/null
+++ b/doc/func/plugins.rst
@@ -0,0 +1,27 @@
+.. _plugins:
+
+Plugins
+=======
+
+Petitboot "plugins" provide a convenient way to package and run binaries in the Petitboot shell that would be difficult to distribute in the Linux image due to size, dependency, or licensing constraints.
+
+Plugin usage and the plugin ABI are well documented in the OpenPOWER docs repository here:
+
+`Plugin Usage & Construction <https://github.com/open-power/docs/blob/master/opal/petitboot-plugins.txt>`_
+
+`Plugin Specification & ABI <https://github.com/open-power/docs/blob/master/opal/petitboot-plugin-spec.txt>`_
+
+Petitboot will scan local devices for pb-plugin files, and will also recognise the "plugin" label in PXE network files, eg:
+
+.. code-block:: none
+
+   label Install Ubuntu 18.04
+	kernel tftp://server/ubuntu-18.04-ppc64el/vmlinux
+	initrd tftp://server/ubuntu-18.04-ppc64el/initrd.gz
+	append tasks=standard pkgsel/language-pack-patterns= pkgsel/install-language-support=false
+
+   plugin RAID Setup
+        tarball http://server/path/to/plugin-raid-1.0.pb-plugin
+
+Discovered plugins will be listed in the Plugin screen and can be installed and run from there, or run manually from the shell.
+
diff --git a/doc/func/snapshots.rst b/doc/func/snapshots.rst
new file mode 100644
index 0000000..c4932f3
--- /dev/null
+++ b/doc/func/snapshots.rst
@@ -0,0 +1,34 @@
+.. _snapshots:
+
+Snapshots
+=========
+
+By default Petitboot does not directly mount any block devices. Instead it uses the device-mapper snapshot_ device to mount an in-memory representation of the device. Any writes Petitboot or another part of the system may make to the device are written to memory rather than the physical device, providing a "real" read-only guarantee beyond just that provided by the filesystem.
+
+In normal operation this is completely transparent but there are two scenarios where actual writes are desired:
+
+.. _snapshot: https://www.kernel.org/doc/Documentation/device-mapper/snapshot.txt
+
+Saving bootloader data
+----------------------
+
+Some configuration formats include directives to save some data before boot - like GRUB's ability to record the last option booted. Snapshots will prevent this but Petitboot can be configured to merge these writes back to the source device by enabling the ""Allow bootloader scripts to modify disks" option in the System Configuration screen.
+
+Manual interaction
+------------------
+
+Any writes to a block device first mounted by Petitboot will by default be thrown away. If a user makes changes to a disk or USB device for example that they want to preserve they can tell Petitboot to merge these writes to the source device with the "sync" event. For example if the user had written something to the sda2 partition, in the shell they can run:
+
+.. code-block:: none
+
+   pb-event sync@sda2
+
+Petitboot will handle the merging itself and remount the device read-only.
+
+If desired snapshots can also be disabled via the "petitboot,snapshots?" parameter. For example:
+
+.. code-block:: none
+
+   nvram --update-config petitboot,snapshots?=false
+
+As of the next boot Petitboot will mount block devices directly.
diff --git a/doc/func/user_interface.rst b/doc/func/user_interface.rst
new file mode 100644
index 0000000..f528e8a
--- /dev/null
+++ b/doc/func/user_interface.rst
@@ -0,0 +1,51 @@
+User Interface
+==============
+
+There are two UI implementations but in practice the ncurses client `petitboot-nc` is the primary interface.
+
+The default view includes a list of discovered boot options and links to other sub screens.
+Common shortcuts include:
+
+======== =====================================
+Shortcut
+======== =====================================
+i        Open the System Information screen
+e        View/Edit a boot option details
+g        View the status update log
+l        Open the Language screen
+c        Open the System Configuration screen
+n        Create/Edit a boot option
+h        Show help text for the current screen
+x        Exit to the shell
+Ctrl-L   Refresh/Redraw the display
+======== =====================================
+
+System Information
+------------------
+
+Provides an overview of the system, in particular discovered partitions and network interfaces. Depending on the platform can also include information on firmware versions, BMC information, etc.
+
+System Configuration
+--------------------
+
+The primary method to configure Petitboot. From here the user can configure the :ref:`auto-boot` order, network interface behaviour, :ref:`snapshots` settings, and handle platform-specific options like :ref:`ipmi` overrides and default consoles.
+
+Boot Option Editor
+------------------
+
+The boot option editor displays the source device and boot resources for a given option. All fields are editable; paths are relative to the source device or full URLs for remote resources.
+
+Status Log
+----------
+
+The status log keeps a running log of all status updates that normally appear in the bottom line of the interface.
+
+Plugin Menu
+-----------
+
+The plugin menu displays a list of all known :ref:`plugins` and whether they are installed or not. "Enter" installs a plugin, and "e" on an installed interface enters a detailed view of the plugin from which a user can run the plugin.
+
+Shell
+-----
+
+At any time the user may drop to a shell by exiting the UI, depending on how Petitboot has been built. This is usually a relatively feature-ful ``sh`` shell with Busybox utilities but Petitboot doesn't make any particular guarantees about available tools aside from those it uses itself.