[DistroKit] [PATCH 1/3] doc: restructure the quick start steps in the intro

[DistroKit] [PATCH 1/3] doc: restructure the quick start steps in the intro

[Roland Hieber]

Give a brief documentation on how to install the correct PTXdist and
toolchain versions, and update outdated links to the PTXdist homepage.

Signed-off-by: Roland Hieber <rhi@pengutronix.de>
---

Robert, this relies on updated documentation on the PTX homepage. Please
merge www.pengutronix.de, branch rhi/topic/toolchain-install first :-)



 doc/hardware.rst |  2 ++
 doc/intro.rst    | 43 ++++++++++++++++++++++++++++++-------------
 2 files changed, 32 insertions(+), 13 deletions(-)

diff --git a/doc/hardware.rst b/doc/hardware.rst
index 2143b6c0120d..8ac2b0216f95 100644
--- a/doc/hardware.rst
+++ b/doc/hardware.rst
@@ -1,3 +1,5 @@
+.. _hardware-platforms:
+
 Hardware Platforms
 ==================
 
diff --git a/doc/intro.rst b/doc/intro.rst
index b8278344f1ca..86db13707726 100644
--- a/doc/intro.rst
+++ b/doc/intro.rst
@@ -12,10 +12,27 @@ minimalistic) Embedded Linux system with modern components:
 
 It can be used as a base for further BSP development.
 
-Installing the BSP
-------------------
+DistroKit supports multiple hardware platforms, see chapter
+:ref:`hardware-platforms` for more information about them.
 
-DistroKit is built with ptxdist. In order to install ptxdist,
+
+Quick Start
+-----------
+
+The next sections below describe briefly how to build the BSP from scratch,
+but for more in-depth documentation, refer to the `PTXdist manual
+<https://www.ptxdist.org/doc/>`_ (or the later chapters if you're reading this
+documentation in the HTML or the PDF version).
+
+If you already have a working environment, you can skip to the section about the
+individual :ref:`hardware-platforms` for more information on how to build
+images, how to flash an image to a board, or how to get a serial console.
+
+Installing PTXdist
+~~~~~~~~~~~~~~~~~~
+
+DistroKit is built with PTXdist version |ptxdistVendorVersion|.  In order to
+install PTXdist,
 `download the tarball <http://www.pengutronix.de/software/ptxdist/download/ptxdist-|ptxdistVendorVersion|.tar.bz2>`_
 from the PTXdist Download Area.
 
@@ -32,19 +49,19 @@ Go to the extracted directory and run
         $ ./configure && make && sudo make install
 
 Installing the Toolchain
-------------------------
-
-In order to build a BSP, you need a toolchain. The easiest way to get a
-toolchain is to install the debian packages for OSELAS.Toolchain:
-
-        `<http://www.pengutronix.de/oselas/toolchain/>`_
+~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you want to build the toolchain yourself, you can download the
-toolchain sources from
+In order to build a BSP for a different architecture than your host system,
+you need a toolchain.
+DistroKit is configured for the OSELAS.Toolchain |oselasTCNVendorVersion|.
+Depending on the platform you want to build, different toolchains are necessary –
+see the sections about the :ref:`hardware-platforms`.
 
-        `<http://www.pengutronix.de/oselas/toolchain/download/>`_
+Pre-built Debian packages of the toolchains are available from Pengutronix,
+but you can also build the toolchain from source.
+See the `OSELAS.Toolchain homepage <https://www.pengutronix.de/de/software/toolchain.html>`_
+for more information.
 
-and build them manually.
 
 Contributing
 ------------
-- 
2.28.0


_______________________________________________
DistroKit mailing list
DistroKit@pengutronix.de

[DistroKit] [PATCH 2/3] doc: hardware: strip down boilerplate documentation

[Roland Hieber]

It is enough to describe only once how to select the platform and
build the images, as the steps are the same for every platform. Only the
platformconfig and the toolchain architecture changes, so summarise them
in a table at the beginning of the section.

Signed-off-by: Roland Hieber <rhi@pengutronix.de>
---
 doc/hardware.rst | 94 ++++++++++++++++++++----------------------------
 1 file changed, 39 insertions(+), 55 deletions(-)

diff --git a/doc/hardware.rst b/doc/hardware.rst
index 8ac2b0216f95..52756f9391ad 100644
--- a/doc/hardware.rst
+++ b/doc/hardware.rst
@@ -7,40 +7,36 @@ DistroKit supports a range of hardware, supported by the ptxdist
 platforms listed below. A platform can be built with one ``ptxdist
 images`` and shares the same cross compiler and binary format.
 
+To build a platform, choose the respective platformconfig, e.g.::
 
-v7a Platform
-------------
-
-The v7a platform is made for machines based on the ARMv7a architecture.
-Select the platform with
+   $ ptxdist platform configs/platform-v7a/platformconfig
+   info: selected platformconfig:
+        'configs/platform-v7a/platformconfig'
 
-::
+If the respective toolchain for the platform is installed from the Debian packages
+or tarballs, PTXdist is able to find and select the right toolchain automatically.
+Otherwise, select your toolchain by giving its path manually, e.g. with::
 
-	$ ptxdist platform configs/platform-v7a/platformconfig
-	info: selected platformconfig:
-	      'configs/platform-v7a/platformconfig'
+   $ ptxdist toolchain /opt/OSELAS.Toolchain-2020.08.0/x86_64-unknown-linux-gnu/gcc-10.2.1-clang-10.0.1-glibc-2.32-binutils-2.35-kernel-5.8-sanitized/bin
+   found and using toolchain:
+   '/opt/OSELAS.Toolchain-2020.08.0/x86_64-unknown-linux-gnu/gcc-10.2.1-clang-10.0.1-glibc-2.32-binutils-2.35-kernel-5.8-sanitized/bin/'
 
-To use the platform, the arm-v7a-linux-gnueabihf toolchain needs to be
-installed; if installed from the debian packages or tarballs, ptxdist
-is able to find and select the right toolchain with
+Then you can build all images with::
 
-::
+   $ ptxdist images
 
-	$ ptxdist toolchain
-	found and using toolchain:
-	'/opt/OSELAS.Toolchain-2016.06.1/arm-v7a-linux-gnueabihf/gcc-5.4.0-glibc-2.23-binutils-2.26-kernel-4.6-sanitized/bin'
 
-Now everything is prepared to build the platform with
-
-::
-
-	$ ptxdist images
+v7a Platform
+------------
 
-Hardware for the v7a Platform
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
++-------------------------+-----------------------------------------+
+| platformconfig:         | ``configs/platform-v7a/platformconfig`` |
++-------------------------+-----------------------------------------+
+| Toolchain architecture: | ``arm-v7a-linux-gnueabihf``             |
++-------------------------+-----------------------------------------+
 
-DistroKit supports various boards based on the ARMv7-A architecture.
-For the following boards there is separate documentation:
+The v7a platform is made for machines based on the ARMv7-A architecture.
+It supports the following hardware:
 
 .. toctree::
    :maxdepth: 1
@@ -94,24 +90,37 @@ listed above, here is a short overview of the generic way:
 
 Refer to the :ref:`ptx_dev_manual` for a more thorough documentation.
 
+
 v8a Platform
 ------------
 
-The stuff from the v7a section above applies here accordingly.
++-------------------------+-----------------------------------------+
+| platformconfig:         | ``configs/platform-v8a/platformconfig`` |
++-------------------------+-----------------------------------------+
+| Toolchain architecture: | ``aarch64-v8a-linux-gnu``               |
++-------------------------+-----------------------------------------+
 
-Hardware for the v8a Platform
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The v8a platform targets the ARMv8-A architecture.
+
+The stuff from the v7a section above applies here accordingly.
 
-Currently DistroKit only supports a single board; the Marvell espressobin.
+Currently DistroKit only supports a single board; the Marvell espressobin:
 
 .. toctree::
    :maxdepth: 1
 
    hardware_v8a_espressobin
 
+
 rpi Platform
 ------------
 
++-------------------------+-----------------------------------------+
+| platformconfig:         | ``configs/platform-rpi/platformconfig`` |
++-------------------------+-----------------------------------------+
+| Toolchain architecture: | ``arm-1136jfs-linux-gnueabihf``         |
++-------------------------+-----------------------------------------+
+
 .. note::
 
   The rpi platform is currently not actively maintained,
@@ -121,32 +130,7 @@ rpi Platform
   we will be happy to merge your patches anyways.
 
 The rpi platform has support for the Raspberry Pi 1, which is based on
-the Broadcom BCM2835 SoC (ARMv6). Select the platform with
-
-::
-
-	$ ptxdist platform configs/platform-rpi/platformconfig
-	info: selected platformconfig:
-	      'configs/platform-rpi/platformconfig'
-
-You'll need the arm-1136jfs-linux-gnueabihf toolchain installed on your
-system. If installed through the Pengutronix Debian or tarball
-packages, ptxdist will pick it up automatically in this step.
-
-::
-
-	$ ptxdist toolchain
-	found and using toolchain:
-	'/opt/OSELAS.Toolchain-2014.12.2/arm-1136jfs-linux-gnueabihf/gcc-4.9.2-glibc-2.20-binutils-2.24-kernel-3.16-sanitized/bin/'
-
-Now everything is prepared to build the platform with
-
-::
-
-	$ ptxdist images
-
-Hardware for the rpi Platform
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+the Broadcom BCM2835 SoC (ARMv6):
 
 .. toctree::
    :maxdepth: 1
-- 
2.28.0


_______________________________________________
DistroKit mailing list
DistroKit@pengutronix.de

[DistroKit] [PATCH 3/3] doc: hardware: add toctrees for mips and x86_64

[Roland Hieber]

sphinx complained about them:

    checking consistency...
    .../distrokit/platform-x86_64/state/docs/hardware_mips_qemu.rst: WARNING: document isn't included in any toctree
    .../distrokit/platform-x86_64/state/docs/hardware_x86_64_qemu.rst: WARNING: document isn't included in any toctree
    done

Signed-off-by: Roland Hieber <rhi@pengutronix.de>
---
 doc/hardware.rst | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/doc/hardware.rst b/doc/hardware.rst
index 52756f9391ad..f09f3af5a14c 100644
--- a/doc/hardware.rst
+++ b/doc/hardware.rst
@@ -136,3 +136,33 @@ the Broadcom BCM2835 SoC (ARMv6):
    :maxdepth: 1
 
    hardware_rpi_raspi1
+
+
+mips Platform
+-------------
+
++-------------------------+------------------------------------------+
+| platformconfig:         | ``configs/platform-mips/platformconfig`` |
++-------------------------+------------------------------------------+
+| Toolchain architecture: | ``mips-softfloat-linux-gnu``             |
++-------------------------+------------------------------------------+
+
+.. toctree::
+   :maxdepth: 1
+
+   hardware_x86_64_qemu
+
+
+x86_64 Platform
+---------------
+
++-------------------------+--------------------------------------------+
+| platformconfig:         | ``configs/platform-x86_64/platformconfig`` |
++-------------------------+--------------------------------------------+
+| Toolchain architecture: | ``x86_64-unknown-linux-gnu``               |
++-------------------------+--------------------------------------------+
+
+.. toctree::
+   :maxdepth: 1
+
+   hardware_mips_qemu
-- 
2.28.0


_______________________________________________
DistroKit mailing list
DistroKit@pengutronix.de