diff options
Diffstat (limited to 'doc/dev')
| -rw-r--r-- | doc/dev/design.rst | 31 | ||||
| -rw-r--r-- | doc/dev/linux-image.rst | 35 | ||||
| -rw-r--r-- | doc/dev/submitting.rst | 26 |
3 files changed, 92 insertions, 0 deletions
diff --git a/doc/dev/design.rst b/doc/dev/design.rst new file mode 100644 index 0000000..7c3fa22 --- /dev/null +++ b/doc/dev/design.rst @@ -0,0 +1,31 @@ +Design Topics +============= + +When considering new functionality or other changes to Petitboot there are a few guidelines we do our best to adhere to: + +Be Generic +---------- + +Avoid adding code that ties Petitboot to a particular platform or functionality by default. Avoid making assumptions about the system that Petitboot may be running on. Platform specific functionality should as much as possible be confined to `platform-` files. Especially when thinking about dependencies on outside utilities or tools consider using the pb-plugin interface instead. + +Don't Surprise The User +----------------------- + +Communicate clearly to the user what is happening. What the UI says is happening should be what actually happens. +A particular example of this is the kernel command line: there are a few problems that would be easier to solve if we could modify the command line of the kernel to be booted, but this would be something that interferes with the users expectations and depending on their scenario could cause them problems. + +Avoid Dependencies On The Target Operating System +------------------------------------------------- + +Supporting multiple configuration formats means that Petitboot can be dropped in as the bootloader for most existing systems without any change in the target operating system or its bootloader configuration. Avoid any changes that would require a corresponding update in the target operating system or dependencies on any particular version of Petitboot. + +Maintain Server-Client Separation +--------------------------------- + +As much as possible the server should perform any actions, and the clients should only makes requests to the server. This is particularly true with the introduction of Petitboot "users" and password restrictions. +An exception to this is the running of Petitboot plugins since these need to be run in the visible shell; however these are still subject to user permissions if enabled. + +Abstract Dependencies +--------------------- + +Avoid direct dependencies on certain utilities or versions of utilities. If there are several versions or interfaces to a utility that Petitboot might access, abstract these differences where possible. (See handling of different utilities such as tftp, udhcpc, etc). diff --git a/doc/dev/linux-image.rst b/doc/dev/linux-image.rst new file mode 100644 index 0000000..ba2b65f --- /dev/null +++ b/doc/dev/linux-image.rst @@ -0,0 +1,35 @@ +Linux Image Requirements +======================== + +Petitboot has a few requirements for the linux image it is built in to. +For an in-practice example of how to build a Petitboot image see op-build_. + +For build-time dependencies see configure.ac_. + +.. _op-build: https://github.com/open-power/op-build/tree/master/openpower/package/petitboot +.. _configure.ac: https://github.com/open-power/petitboot/blob/master/configure.ac + +Core dependencies +----------------- + +* pb-discover expects to be run as root, or at least have permission for device management, executing kexec, etc. +* udev: pb-discover discovers devices via libudev enumeration so a udev implementation must be present. + Following this any udev rules required for certain device types must also be present. Eg. op-build's inclusions_. +* network utilities: pb-discover expects to have ``udhcpc`` available for DHCP, or a call-equivalent version. Similarly it expects ``tftp`` and ``wget`` binaries in order to download boot resources. +* kexec: A kexec binary must be available. This is commonly kexec-lite_ however kexec-tools should also work. +* LVM: Petitboot depends on libdevmapper, and also requires ``vgscan`` and ``vgchange`` to be available if order to setup logical volumes. + +.. _inclusions: https://github.com/open-power/op-build/blob/master/openpower/package/petitboot/63-md-raid-arrays.rules +.. _kexec-lite: https://github.com/open-power/kexec-lite + +Optional dependencies +--------------------- + +* ``mdadm`` for software RAID handling. +* libflash: On OPAL platforms Petitboot will use libflash to load firmware version information. +* ipmi: If ``/dev/ipmi`` is available Petitboot will use it to source information from the BMC. +* console setup: unless you have other requirements you probably want to be starting the UI through ``pb-console`` in which case it is useful to have this called by udev. + For example: petitboot-console-ui.rules_, or depending on if you're using ``agetty -l`` to log in a user, shell_profile_. + +.. _petitboot-console-ui.rules: https://github.com/open-power/op-build/blob/master/openpower/package/petitboot/petitboot-console-ui.rules +.. _shell_profile: https://github.com/open-power/op-build/blob/master/openpower/package/petitboot/shell_profile diff --git a/doc/dev/submitting.rst b/doc/dev/submitting.rst new file mode 100644 index 0000000..fb968cd --- /dev/null +++ b/doc/dev/submitting.rst @@ -0,0 +1,26 @@ +Development and Submitting Patches +================================== + +Petitboot is largely written in C and follows the `Linux kernel coding style <https://github.com/torvalds/linux/blob/master/Documentation/process/coding-style.rst>`_. + +Development occurs on the `Petitboot mailing list <https://lists.ozlabs.org/listinfo/petitboot>`_. + +Petitboot also has a `Patchwork instance <http://patchwork.ozlabs.org/project/petitboot/list/>`_ that watches the list. + +Patch Guidelines +---------------- + +Patches should be sent to the mailing list generally following what you would see in `submitting-patches <https://github.com/torvalds/linux/blob/master/Documentation/process/submitting-patches.rst>`_ + +In general if you generate the patch with ``git format-patch`` or ``git send-email`` you should be fine. + +Patches should have an obvious title and where necessary a clear commit message describing the changes. +Avoid lumping unrelated changes together, instead putting them in separate patches in a logical order. +If a patch is generally contained to one area (and it should be), it should generally be prefixed with the path of what it is changing, for example "discover/grub:" or "ui/ncurses:". + +If sending a new revision of a patch update the title to mention the verson (hint: ``git format-patch -v 2``) and include a short changelog under the ``---`` describing what changed between versions. Check out the list archives for `some examples <https://lists.ozlabs.org/pipermail/petitboot/2018-November/001188.html>`_. + +Stable Patches +-------------- + +Patches or upstream commits that need to be applied to a stable branch should be restricted to small, self-contained fixes as much as possible. Avoid backporting new features or invasive changes. |
