Merge pull request #2513 from stewart-ibm/random-docs-improvements
Random docs improvements
diff --git a/doc/introduction.rst b/doc/introduction.rst
index 5ae846b..9fde475 100644
--- a/doc/introduction.rst
+++ b/doc/introduction.rst
@@ -7,30 +7,40 @@
Firmware Components
-------------------
-Buildroot
+Buildroot_
We use http://buildroot.net/ as the build system for assembling a firmware
image. `op-build` is a "Buildroot overlay". We build a kernel and initramfs
- using buildroot to run the Petitboot boot loader in.
-SBE
+ using buildroot to run the Petitboot boot loader in. We maintain a branch
+ with a minimum number of patches on top of upstream buildroot.
+SBE_
the Self Boot Engine is the first unit inside the POWER processor to start
executing. It's job is to set up a core and load Hostboot.
-Hostboot
+Hostboot_
Low level system boot firmware. It brings up CPU cores, the OCC, Memory
and hands control over to OPAL (skiboot)
-OCC
+OCC_
The On Chip Controller is responsible for thermal limits and frequency
management.
OPAL
The OpenPOWER Abstraction Layer, provided by skiboot
-skiboot
+skiboot_
skiboot implements OPAL (the OpenPOWER Abstraction Layer). Skiboot is
boot and runtime firmware and is responsible for bringing up PCI and
providing runtime abstractions to the running OS.
-Linux
+Linux_
Once skiboot has finished setting up the machine, it hands control over
to a Linux kernel. This kernel provides device drivers and userspace to
- run the bootloader, Petitboot
-Petitboot
+ run the bootloader, Petitboot. We maintain our own branch with a minimal
+ number of patches on top of the latest upstream stable release.
+Petitboot_
The bootloader. It is a normal user-space process running on Linux that
searches the system for disks and network devices that it can boot the
OS from.
+
+.. _Buildroot: https://github.com/open-power/buildroot
+.. _SBE: https://github.com/open-power/sbe
+.. _OCC: https://github.com/open-power/occ
+.. _Hostboot: https://github.com/open-power/hostboot
+.. _skiboot: https://open-power.github.io/skiboot/
+.. _Linux: https://github.com/open-power/linux
+.. _Petitboot: https://github.com/open-power/petitboot/
diff --git a/doc/process/KernelTree.rst b/doc/process/KernelTree.rst
new file mode 100644
index 0000000..4a793ff
--- /dev/null
+++ b/doc/process/KernelTree.rst
@@ -0,0 +1,64 @@
+op-build Linux Kernel
+=====================
+
+The skiroot/Petitboot kernel is currently based on the 4.19 series.
+
+Submitting a patch
+------------------
+
+If you require a patch added to the firmware, follow these steps:
+
+1. Submit your patch upstream. It doesn’t need to be upstream, but it
+ should be on it’s way
+2. Send a pull request or a ``git format-patch`` formatted patch series
+ to openpower-firmware@lists.ozlabs.org, and cc joel@jms.id.au. Be
+ sure to use ``--suppress-cc=sob`` when generating the patches so we
+ don’t spam the community. The current tree is based on 4.15-stable.
+
+Bug fixes
+---------
+
+Whenever a stable release is tagged in
+https://git.kernel.org/cgit/linux/kernel/git/stable/linux-stable.git/,
+we will rebase our patches on top of that and create a new release.
+
+If you are submitting patches upstream that you want to be included,
+then ensure you cc stable as per the
+`rules <https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/plain/Documentation/stable_kernel_rules.txt>`__.
+
+Versioning
+----------
+
+Versions are the upstream version number, followed by ``-openpowerN``,
+where N is the revision that counts up from 1 for the given upstream
+version number. These versions will be present as tags in the git
+repository hosted at https://github.com/open-power/linux.
+
+We aim to follow "the latest upstream release".
+
+For op-build stable trees, we follow the latest stable release of the
+kernel that particular op-build release was made with. Since op-build
+stable releases may outlast how long an upstream kernel is maintain for,
+we will move up the kernel version we use until the next LTS kernel.
+Once on an LTS kernel, an op-build stable release will stick with that
+version.
+
+Tree and patches
+----------------
+
+The kernel tree hosted at https://github.com/open-power/linux contains
+the current release plus a set of patches that we carry. Ideally there
+would be no patches carried, as everything should be upstream.
+
+We take the commits in this tree between the upstream tag and the
+openpower tag and generate a series of patches that are imported into
+the op-build Buildroot overlay, and placed in
+`op-build/openpower/linux <https://github.com/open-power/op-build/tree/master/openpower/linux>`_.
+op-build then fetches the upstream tarball and applies these patches.
+This way we don’t have to clone an entire tree when doing an op-build
+build.
+
+Patches in the tree
+-------------------
+
+- xhci: Reset controller on xhci shutdown
diff --git a/doc/process/building-with-ci.rst b/doc/process/building-with-ci.rst
new file mode 100644
index 0000000..471681d
--- /dev/null
+++ b/doc/process/building-with-ci.rst
@@ -0,0 +1,11 @@
+Building with ci scripts
+========================
+
+op-build has several build scripts in the ci/ directory aimed at being used to
+help continuous integration environments, as well as specifying build
+dependencies as code.
+
+These use Docker containers for the build environment.
+
+It is recommended you use (or send patches so that you can use them) these over
+rolling your own scripts.
diff --git a/doc/process/index.rst b/doc/process/index.rst
index 024518b..4efe358 100644
--- a/doc/process/index.rst
+++ b/doc/process/index.rst
@@ -4,3 +4,5 @@
.. toctree::
CONTRIBUTING.md
+ KernelTree.rst
+ building-with-ci
diff --git a/doc/release-notes/index.rst b/doc/release-notes/index.rst
index 3f8345b..dd4bfb9 100644
--- a/doc/release-notes/index.rst
+++ b/doc/release-notes/index.rst
@@ -3,6 +3,9 @@
op-build Release Notes
======================
+v1.21
+-----
+
.. toctree::
:maxdepth: 1
@@ -11,8 +14,22 @@
v1.21
v1.21.1
v1.21.2
+
+v1.22
+-----
+
+.. toctree::
+ :maxdepth: 1
+
v1.22-rc1
v1.22
+
+v2.0
+----
+
+.. toctree::
+ :maxdepth: 1
+
v2.0-rc1
v2.0
v2.0.1
@@ -26,6 +43,21 @@
v2.0.9
v2.0.10
v2.0.11
+
+v2.1
+----
+
+.. toctree::
+ :maxdepth: 1
+
v2.1-rc1
v2.1
+
+v2.2
+----
+
+ .. toctree::
+ :maxdepth: 1
+
v2.2-rc1
+
diff --git a/doc/release-notes/v2.0.10.rst b/doc/release-notes/v2.0.10.rst
index a07b94d..b3ed7f7 100644
--- a/doc/release-notes/v2.0.10.rst
+++ b/doc/release-notes/v2.0.10.rst
@@ -93,12 +93,12 @@
`Repository <https://github.com/open-power/hostboot>`__
-.. _patches-1:
+.. _op-build-v2.0.10-patches-1:
Patches
~~~~~~~
-.. _commits-1:
+.. _op-build-v2.0.10-commits-1:
Commits
~~~~~~~
@@ -151,12 +151,12 @@
`Repository <https://github.com/open-power/occ>`__
-.. _patches-2:
+.. _op-build-v2.0.10-patches-2:
Patches
~~~~~~~
-.. _commits-2:
+.. _op-build-v2.0.10-commits-2:
Commits
~~~~~~~
@@ -170,14 +170,14 @@
`Repository <https://github.com/open-power/petitboot>`__
-.. _patches-3:
+.. _op-build-v2.0.10-patches-3:
Patches
~~~~~~~
- `petitboot-01-autotools-Add-autopoint-generated-files.patch <https://github.com/open-power/op-build/tree/HEAD/openpower/package/petitboot/petitboot-01-autotools-Add-autopoint-generated-files.patch>`__
-.. _commits-3:
+.. _op-build-v2.0.10-commits-3:
Commits
~~~~~~~
@@ -191,12 +191,12 @@
`Repository <https://github.com/open-power/sbe>`__
-.. _patches-4:
+.. _op-build-v2.0.10-patches-4:
Patches
~~~~~~~
-.. _commits-4:
+.. _op-build-v2.0.10-commits-4:
Commits
~~~~~~~
@@ -234,12 +234,12 @@
`Repository <https://github.com/open-power/skiboot>`__
-.. _patches-5:
+.. _op-build-v2.0.10-patches-5:
Patches
~~~~~~~
-.. _commits-5:
+.. _op-build-v2.0.10-commits-5:
Commits
~~~~~~~
diff --git a/doc/release-notes/v2.0.3.rst b/doc/release-notes/v2.0.3.rst
index fff4683..ed752c1 100644
--- a/doc/release-notes/v2.0.3.rst
+++ b/doc/release-notes/v2.0.3.rst
@@ -65,12 +65,12 @@
`Repository <https://github.com/open-power/hostboot>`__
-.. _patches-1:
+.. _op-build-v2.0.3-patches-1:
Patches
~~~~~~~
-.. _commits-1:
+.. _op-build-v2.0.3-commits-1:
Commits
~~~~~~~
@@ -153,12 +153,12 @@
`Repository <https://github.com/open-power/occ>`__
-.. _patches-2:
+.. _op-build-v2.0.3-patches-2:
Patches
~~~~~~~
-.. _commits-2:
+.. _op-build-v2.0.3-commits-2:
Commits
~~~~~~~
@@ -173,12 +173,12 @@
`Repository <https://github.com/open-power/sbe>`__
-.. _patches-3:
+.. _op-build-v2.0.3-patches-3:
Patches
~~~~~~~
-.. _commits-3:
+.. _op-build-v2.0.3-commits-3:
Commits
~~~~~~~
@@ -193,12 +193,12 @@
`Repository <https://github.com/open-power/skiboot>`__
-.. _patches-4:
+.. _op-build-v2.0.3-patches-4:
Patches
~~~~~~~
-.. _commits-4:
+.. _op-build-v2.0.3-commits-4:
Commits
~~~~~~~
diff --git a/doc/release-notes/v2.0.9.rst b/doc/release-notes/v2.0.9.rst
index 6660f3f..ade429b 100644
--- a/doc/release-notes/v2.0.9.rst
+++ b/doc/release-notes/v2.0.9.rst
@@ -7,6 +7,7 @@
It is recommended that v2.0.9 be used over any previous v2.0.x version on POWER9 systems due to the bug fixes contained within.
The only update in this release is to skiboot. Skiboot v6.0.8 includes the following bug fixes:
+
- i2c: Ensure ordering between i2c_request_send() and completion
i2c_request_send loops waiting for a flag "uc.done" set by
diff --git a/doc/release-notes/v2.2-rc1.rst b/doc/release-notes/v2.2-rc1.rst
index 0ceb1f5..6212dae 100644
--- a/doc/release-notes/v2.2-rc1.rst
+++ b/doc/release-notes/v2.2-rc1.rst
@@ -153,12 +153,12 @@
`Repository <https://github.com/open-power/hcode>`__
-.. _patches-1:
+.. _op-build-v2.2-rc1-patches-1:
Patches
~~~~~~~
-.. _commits-1:
+.. _op-build-v2.2-rc1-commits-1:
Commits
~~~~~~~
@@ -790,7 +790,7 @@
`Repository <https://github.com/open-power/hostboot>`__
-.. _patches-2:
+.. _op-build-v2.2-rc1-patches-2:
Patches
~~~~~~~
@@ -799,7 +799,7 @@
- `hostboot-0002-Revert-Mark-Read-Only-Partitions-as-Such.patch <https://github.com/open-power/op-build/tree/HEAD/openpower/package/hostboot/hostboot-0002-Revert-Mark-Read-Only-Partitions-as-Such.patch>`__
- `hostboot-1020-Revert-jgr17071200-Removed-pdwn-settings.patch <https://github.com/open-power/op-build/tree/HEAD/openpower/package/hostboot/hostboot-1020-Revert-jgr17071200-Removed-pdwn-settings.patch>`__
-.. _commits-2:
+.. _op-build-v2.2-rc1-commits-2:
Commits
~~~~~~~
@@ -2916,12 +2916,12 @@
`Repository <https://github.com/open-power/occ>`__
-.. _patches-3:
+.. _op-build-v2.2-rc1-patches-3:
Patches
~~~~~~~
-.. _commits-3:
+.. _op-build-v2.2-rc1-commits-3:
Commits
~~~~~~~
@@ -3001,12 +3001,12 @@
`Repository <https://github.com/open-power/op-build>`__
-.. _patches-4:
+.. _op-build-v2.2-rc1-patches-4:
Patches
~~~~~~~
-.. _commits-4:
+.. _op-build-v2.2-rc1-commits-4:
Commits
~~~~~~~
@@ -3018,12 +3018,12 @@
`Repository <https://github.com/open-power/p9dsu-xml>`__
-.. _patches-5:
+.. _op-build-v2.2-rc1-patches-5:
Patches
~~~~~~~
-.. _commits-5:
+.. _op-build-v2.2-rc1-commits-5:
Commits
~~~~~~~
@@ -3035,12 +3035,12 @@
`Repository <https://github.com/open-power/palmetto-xml>`__
-.. _patches-6:
+.. _op-build-v2.2-rc1-patches-6:
Patches
~~~~~~~
-.. _commits-6:
+.. _op-build-v2.2-rc1-commits-6:
Commits
~~~~~~~
@@ -3055,14 +3055,14 @@
`Repository <https://github.com/open-power/petitboot>`__
-.. _patches-7:
+.. _op-build-v2.2-rc1-patches-7:
Patches
~~~~~~~
- `petitboot-01-autotools-Add-autopoint-generated-files.patch <https://github.com/open-power/op-build/tree/HEAD/openpower/package/petitboot/petitboot-01-autotools-Add-autopoint-generated-files.patch>`__
-.. _commits-7:
+.. _op-build-v2.2-rc1-commits-7:
Commits
~~~~~~~
@@ -3072,12 +3072,12 @@
`Repository <https://github.com/open-power/pnor>`__
-.. _patches-8:
+.. _op-build-v2.2-rc1-patches-8:
Patches
~~~~~~~
-.. _commits-8:
+.. _op-build-v2.2-rc1-commits-8:
Commits
~~~~~~~
@@ -3089,12 +3089,12 @@
`Repository <https://github.com/open-power/romulus-xml>`__
-.. _patches-9:
+.. _op-build-v2.2-rc1-patches-9:
Patches
~~~~~~~
-.. _commits-9:
+.. _op-build-v2.2-rc1-commits-9:
Commits
~~~~~~~
@@ -3131,12 +3131,12 @@
`Repository <https://github.com/open-power/sbe>`__
-.. _patches-10:
+.. _op-build-v2.2-rc1-patches-10:
Patches
~~~~~~~
-.. _commits-10:
+.. _op-build-v2.2-rc1-commits-10:
Commits
~~~~~~~
@@ -3478,12 +3478,12 @@
`Repository <https://github.com/open-power/skiboot>`__
-.. _patches-11:
+.. _op-build-v2.2-rc1-patches-11:
Patches
~~~~~~~
-.. _commits-11:
+.. _op-build-v2.2-rc1-commits-11:
Commits
~~~~~~~
@@ -3991,12 +3991,12 @@
`Repository <https://github.com/open-power/vesnin-xml>`__
-.. _patches-12:
+.. _op-build-v2.2-rc1-patches-12:
Patches
~~~~~~~
-.. _commits-12:
+.. _op-build-v2.2-rc1-commits-12:
Commits
~~~~~~~
@@ -4013,12 +4013,12 @@
`Repository <https://github.com/open-power/witherspoon-xml>`__
-.. _patches-13:
+.. _op-build-v2.2-rc1-patches-13:
Patches
~~~~~~~
-.. _commits-13:
+.. _op-build-v2.2-rc1-commits-13:
Commits
~~~~~~~
@@ -4033,12 +4033,12 @@
`Repository <https://github.com/open-power/zaius-xml>`__
-.. _patches-14:
+.. _op-build-v2.2-rc1-patches-14:
Patches
~~~~~~~
-.. _commits-14:
+.. _op-build-v2.2-rc1-commits-14:
Commits
~~~~~~~