[PATCH 3/3] README: bring it up to date

[Ahmad Fatoum <a.fatoum@pengutronix.de>]

Most of the file was written when barebox used to be called U-Boot v2.
It thus focused on comparisons and highlighted some aspects that
U-Boot has since adopted.

Give the file an overhaul by converting it to ReST and highlight
my subjective take on what makes barebox cool in 2024.

Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
---
 README     | 271 -------------------------------------------
 README.rst | 328 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 328 insertions(+), 271 deletions(-)
 delete mode 100644 README
 create mode 100644 README.rst

diff --git a/README b/README
deleted file mode 100644
index 37fd80c10280..000000000000
--- a/README
+++ /dev/null
@@ -1,271 +0,0 @@
-# SPDX-License-Identifier: GPL-2.0-only
-
-barebox
--------
-
-barebox is a bootloader that follows the tradition of Das U-Boot, while
-adopting modern design ideas from the Linux kernel.
-
-
-Features
---------
-
-- A POSIX-based file API
-  Inside barebox the usual open/close/read/write/lseek functions are used.
-  This makes it familiar to everyone who has programmed under UNIX systems.
-
-- Usual shell commands like ls/cd/mkdir/echo/cat,...
-
-- The environment is not a variable store anymore, but a file store. It has
-  currently some limitations, of course. The environment is not a real
-  read/write filesystem, but more like a tar archive.
-  The saveenv command saves the files under a certain directory (by default
-  /env) in persistent storage (by default /dev/env0). There is a counterpart
-  called loadenv, too.
-
-- filesystem support
-  The loader starts up with mounting a ramdisk on /. Then a devfs is mounted
-  on /dev allowing the user (or shell commands) to access devices. Apart from
-  these two filesystems there are a number of different filesystems ported:
-  ext4, efi, efivarfs, ext4, fat, jffs2, NFS, pstore, squashfs, ubifs,
-  u-boot variable FS among others.
-
-- device/driver model
-  Devices are no longer described by defines in the config file. Instead
-  devices are registered as they are discovered (e.g. through OpenFirmware
-  device tree traversal or EFI handles) or by board code.
-  Drivers will match upon the devices automatically.
-
-- clocksource support
-  Timekeeping has been simplified by the use of the Linux clocksource API.
-  no [gs]et_timer[masked]() or reset_timer[masked]() functions.
-
-- Kconfig and Kernel build system
-  Only targets which are really needed get recompiled. Parallel builds are
-  no problem anymore. This also removes the need for many many ifdefs in
-  the code.
-
-- ARCH=sandbox simulation target
-  barebox can be compiled to run under Linux. While this is rather useless
-  in real world this is a great debugging and development aid. New features
-  can be easily developed and tested on long train journeys and started
-  under gdb. There is a console driver for Linux which emulates a serial
-  device and a TAP-based Ethernet driver. Linux files can be mapped to
-  devices under barebox to emulate storage devices.
-
-- device parameter support
-  Each device can have an unlimited number of parameters. They can be accessed
-  on the command line with <devid>.<param>="...", for example
-  'eth0.ip=192.168.0.7' or 'echo $eth0.ip'
-
-- initcalls
-  hooks in the startup process can be achieved with *_initcall() directives
-  in each file.
-
-- getopt
-  There is a small getopt implementation. Some commands got really
-  complicated (both in code and in usage) due to the fact that U-Boot
-  allowed only positional parameters.
-
-- editor
-  Scripts can be edited with a small editor. This editor has no features
-  except the ones really needed: moving the cursor and typing characters.
-
-
-Building barebox
-----------------
-
-barebox uses the Linux kernel's build system. It consists of two parts:
-the Makefile infrastructure (kbuild), plus a configuration system
-(kconfig). So building barebox is very similar to building the Linux
-kernel.
-
-For the examples below, we use the User Mode barebox implementation, which
-is a port of barebox to the Linux userspace. This makes it possible to
-test drive the code without having real hardware. So for this test
-scenario, ARCH=sandbox is the valid architecture selection. This currently
-works on at least IA32 hosts and x86-64 hosts.
-
-Selection of the architecture and the cross compiler can be done by using
-the environment variables ARCH and CROSS_COMPILE.
-
-In order to configure the various aspects of barebox, start the barebox
-configuration system:
-
-  # make menuconfig
-
-This command starts a menu box and lets you select all the different
-options available for your architecture. Once the configuration was
-finished (you can simulate this by using the standard demo config file
-with 'make sandbox_defconfig'), there is a .config file in the toplevel
-directory of the source code.
-
-Once barebox is configured, we can start the compilation
-
-  # make
-
-If everything goes well, the result is a file called barebox:
-
-  # ls -l barebox
-    -rwxr-xr-x 1 rsc ptx 114073 Jun 26 22:34 barebox
-
-barebox usually needs an environment for storing the configuration data.
-You can generate an environment using the example environment contained
-in board/sandbox/env:
-
-  # ./scripts/bareboxenv -s -p 0x10000 arch/sandbox/board/env env.bin
-
-To get some files to play with, you can generate a cramfs image:
-  # mkcramfs somedir/ cramfs.bin
-
-The barebox image is a normal Linux executable, so it can be started
-just like every other program:
-
-  # ./barebox -e env.bin -i cramfs.bin
-
-  barebox 2.0.0-trunk (Jun 26 2007 - 22:34:38)
-
-  loading environment from /dev/env0
-  barebox> /
-
-Specifying -[ie] <file> tells barebox to map the file as a device
-under /dev. Files given with '-e' will appear as /dev/env[n]. Files
-given with '-i' will appear as /dev/fd[n].
-
-If barebox finds a valid configuration sector on /dev/env0 it will
-load it to /env. It then executes /env/init if it exists. If you have
-loaded the example environment, barebox will show you a menu asking for
-your settings.
-
-If you have started barebox as root, you will find a new tap device on your
-host which you can configure using ifconfig. Once you configured barebox'
-network settings accordingly you can do a ping or tftpboot.
-
-If you have mapped a cramfs image, try mounting it with
-
-  # mkdir /cram
-  # mount /dev/fd0 cramfs /cram
-
-Memory can be examined as usual using md/mw commands. They both understand
-the -f <file> option to tell the commands that they should work on the
-specified files instead of /dev/mem which holds the complete address space.
-Note that if you call 'md /dev/fd0' (without -f) barebox will segfault on
-the host, because it will interpret /dev/fd0 as a number.
-
-
-Directory Layout
-----------------
-
-Most of the directory layout is based upon the Linux Kernel:
-
-arch/*                -> contains architecture specific parts
-arch/*/include        -> architecture specific includes
-arch/*/mach-*         -> SoC specific code
-arch/*/mach-*/include -> SoC specific includes
-
-drivers/serial        -> drivers
-drivers/net
-drivers/...
-
-fs/                   -> filesystem support and filesystem drivers
-
-lib/                  -> generic library functions (getopt, readline and the
-                         like)
-
-common/               -> common stuff
-
-commands/             -> many things previously in common/cmd_*, one command
-			 per file
-
-net/                  -> Networking stuff
-
-scripts/              -> Kconfig system
-
-Documentation/        -> Sphinx generated documentation. Call "make docs" to
-                         generate a HTML version in Documentation/html.
-
-
-Release Strategy
-----------------
-
-barebox is developed with git. On a monthly schedule, tarball releases are
-branched from the repository and released on the project web site. Here
-are the release rules:
-
-- Releases follow a time based scheme:
-
-  barebox-xxxx.yy.z.tar.bz2
-          ^^^^ ^^ ^----------- Bugfix Number, starting at 0
-            \   \------------- Month
-             \---------------- Year
-
-  Example: barebox-2009.12.0.tar.bz2
-
-- Releases are made around the beginning of the month. As we are aiming
-  for monthly releases, development is considered to be a continuous
-  process. If you find bugs in one release, you have the chance to get
-  patches in on a very short time scale.
-
-- Usually, there are no bugfix releases, so z=0. If there is a need
-  to make a bugfix release, z is the right place to increment.
-
-- If there may be a reason for pre releases, they are called
-
-  barebox-xxxx.yy.z-pren.tar.bz
-                       ^------ Number of prerelease, starting with 1
-
-  Example: barebox-2009.12.0-pre1.tar.bz2
-
-  We think that there is no need for pre releases, but if it's ever
-  necessary, this is the scheme we follow.
-
-- Only the monthly releases are archived on the web site. The tarballs
-  are located in https://www.barebox.org/download/ and this location
-  does never change, in order to make life easier for distribution
-  people.
-
-
-Contributing
-------------
-
-For any questions regarding barebox, send a mail to the mailing list at
-<barebox@lists.infradead.org>. The archives for this list are available
-publicly at <http://lists.infradead.org/pipermail/barebox/> and
-<https://lore.barebox.org/barebox/>.
-
-The same list should also be used to send patches. barebox uses a similar
-process as the Linux kernel, so most of the Linux guide for submitting patches
-<https://www.kernel.org/doc/html/latest/process/submitting-patches.html> also
-applies to barebox (except the step for selecting your recipient - we don't
-have a MAINTAINERS file, instead all patches go to the list).
-
-
-License
--------
-
-Copyright (C) 2000 - 2005 Wolfgang Denk, DENX Software Engineering, wd@denx.de.
-Copyright (C) 2018 Sascha Hauer, Pengutronix, and individual contributors
-
-barebox is free software: you can redistribute it and/or modify it under the
-terms of the GNU General Public License, version 2, as published by the Free
-Software Foundation.
-
-This program is distributed in the hope that it will be useful, but WITHOUT ANY
-WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-PARTICULAR PURPOSE. See the GNU General Public License for more details.
-
-You should have received a copy of the GNU General Public License in the file
-COPYING along with this program. If not, see <https://www.gnu.org/licenses/>.
-
-Individual files may contain the following SPDX license tags as a shorthand for
-the above copyright and warranty notices:
-
-    SPDX-License-Identifier: GPL-2.0-only
-    SPDX-License-Identifier: GPL-2.0-or-later
-
-This eases machine processing of licensing information based on the SPDX
-License Identifiers that are available at http://spdx.org/licenses/.
-
-Also note that some files in the barebox source tree are available under
-several different GPLv2-compatible open-source licenses. This fact is noted
-clearly in the file headers of the respective files.
diff --git a/README.rst b/README.rst
new file mode 100644
index 000000000000..17bf288c4c60
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,328 @@
+..
+  SPDX-License-Identifier: GPL-2.0-only
+
+=======
+barebox
+=======
+
+A bootloader that follows the tradition of Das U-Boot, while
+adopting modern design ideas from the Linux kernel.
+
+.. class:: center
+
+`Try it out in your browser ✨ <https://www.barebox.org/jsbarebox/?graphic=0>`_
+·
+`Check out the documentation 📖 <https://www.barebox.org/doc/latest/index.html>`_
+·
+`Get involved 🫶 <https://www.barebox.org/doc/latest/user/introduction.html#feedback>`_
+
+Features
+--------
+
+* A POSIX-based file API:
+  Inside barebox the usual ``open/close/read/write/lseek`` functions are used.
+  This makes it familiar to everyone who has programmed under UNIX systems.
+
+* Usual shell commands like ``ls/cd/mkdir/echo/cat/cp/mount``,...
+  which work uniformly across file systems
+
+* Filesystem support:
+  The loader starts up with mounting a ramdisk on ``/``. Then a devfs is mounted
+  on ``/dev`` allowing the user (or shell commands) to access devices. Apart from
+  these two filesystems there are a number of different filesystems ported:
+  ext4, efi, efivarfs, ext4, fat, jffs2, NFS, tftp, pstore, squashfs, ubifs,
+  ratp (RFC916), u-boot variable FS among others.
+
+* Multiplatform support:
+  Configurations like ``multi_v7_defconfig`` and ``multi_v8_defconfig`` build
+  barebox for many dozens of boards all at once. All resulting images share the
+  same barebox proper binary, each time with a different prebootloader that does
+  low-level initialization and passes in the device tree. Prebootloaders may
+  detect board/SoC type and pass in different device trees to support various
+  boards with the same image.
+
+* Focus on developer experience:
+  barebox provides many features that should be familiar to kernel developers
+
+  * barebox images are designed to be bootable from within barebox itself,
+    so developers can trivially network boot. For chainloading from existing
+    bootloaders, there's also an extra ``barebox-dt-2nd.img`` that is bootable
+    exactly like a Linux kernel.
+  * KASAN (KernelAddressSanitizer) and kallsyms (symbolized stack traces)
+    help in hunting down memory issues
+  * ramoops allows barebox to share its own ``dmesg`` log with Linux
+  * Linux kernel drivers are easier to port, because the driver frameworks are
+    closely based on the upstream Linux counterpart
+
+* Device parameter support:
+  Each device can have an unlimited number of parameters. They can be accessed
+  on the command line with ``<devid>.<param>="..."``, for example
+  ``eth0.ip=192.168.0.7`` or echo ``$eth0.ip``.
+
+* Editor:
+  Scripts can be edited with a small editor. This editor has no features
+  except the ones really needed: moving the cursor and typing characters
+  on multiple lines.
+
+* The environment is not a variable store anymore, but a file store.
+  The ``saveenv`` command archives the files under a certain directory (by default
+  ``/env``) in persistent storage (by default ``/dev/env0``). There is a counterpart
+  called ``loadenv``, too. Additionally, barebox-state provides power-fail-safe
+  variable-only storage with optional authentication, so the mutable environment
+  can be disabled for security reasons.
+
+* Uniformity: Finding out where barebox booted from, determining what caused
+  the last reset, booting in a redundant fail-safe manner, updating barebox on disk
+  are examples of functionality handled generically by frameworks, so boards can look
+  and feel the same and custom scripts or board code are only needed for the
+  exceptional stuff.
+
+* device/driver model:
+  Devices are no longer described by defines in the config file. Instead
+  devices are registered as they are discovered (e.g. through OpenFirmware
+  device tree traversal or EFI handles) or by board code.
+  Drivers will match upon the devices automatically.
+
+* Device Tree Manipulation:
+  barebox has extensive support for fixing up both its own device tree at
+  runtime and the kernel's, whether from board code, shell scripts or within
+  device tree overlays
+
+* Initcalls:
+  hooks in the startup process can be achieved with ``*_initcall()`` directives
+  in each file.
+
+* ``ARCH=sandbox`` simulation target:
+  barebox can be compiled to run under Linux. While this is rather useless
+  in real world this is a great debugging and development aid. New features
+  can be easily developed and tested on long train journeys and started
+  under gdb. There is a console driver for Linux which emulates a serial
+  device and a TAP-based Ethernet driver. Linux files can be mapped to
+  devices under barebox to emulate storage devices.
+
+* and `yes, of course it runs DOOM <https://doomwiki.org/wiki/BareDOOM>`_.
+
+Building barebox
+----------------
+
+barebox uses the Linux kernel's build system. It consists of two parts:
+the Makefile infrastructure (kbuild), plus a configuration system
+(kconfig). So building barebox is very similar to building the Linux
+kernel.
+
+For the examples below, we use the User Mode barebox implementation, which
+is a port of barebox to the Linux userspace. This makes it possible to
+test drive the code without having real hardware. So for this test
+scenario, ``ARCH=sandbox`` is the valid architecture selection. This currently
+works on at least IA32 hosts and x86-64 hosts.
+
+Selection of the architecture and the cross compiler can be done by using
+the environment variables ``ARCH`` and ``CROSS_COMPILE``.
+
+In order to configure the various aspects of barebox, start the barebox
+configuration system::
+
+  # make menuconfig
+
+This command starts a menu box and lets you select all the different
+options available for your architecture. Once the configuration was
+finished (you can simulate this by using the standard demo config file
+with ``make sandbox_defconfig``), there is a ``.config`` file in the
+toplevel directory of the source code.
+
+Once barebox is configured, we can start the compilation::
+
+  # make
+
+If everything goes well, the result is a file called barebox::
+
+  # ls -l barebox
+    -rwxr-xr-x 1 rsc ptx 114073 Jun 26 22:34 barebox
+
+To get some files to play with, you can generate a squashfs image::
+
+  # mksquashfs somedir/ squashfs.bin
+
+The barebox image is a normal Linux executable, so it can be started
+just like every other program::
+
+  # ./barebox -i squashfs.bin
+
+  add fd0 backed by file squashfs.bin
+  add stickypage backed by file /run/user/1000/barebox/stickypage.1661112
+
+  barebox 2024.07.0 #0 Wed Jul 18 11:36:31 CEST 2024
+  [...]
+
+  barebox@Sandbox:/
+
+Specifying ``-[ie] <file>`` tells barebox to map the file as a device
+under /dev. Files given with ``-e`` will appear as ``/dev/env[n]``. Files
+given with ``-i`` will appear as ``/dev/fd[n]``.
+
+If barebox finds a valid configuration sector on ``/dev/env0`` it will
+load it to ``/env``. It then source ``/env/init/*`` if it exists. If you have
+loaded the example environment, barebox will show you a menu asking for
+your settings. The sandbox configuration embeds a "sticky page", which is
+inherited across barebox resets. This way, there's a usable environment
+out-of-the-box.
+
+If you have started barebox as root, you will find a new tap device on your
+host which you can configure using ifconfig. Once you configured barebox'
+network settings accordingly you can do a ping or tftpboot.
+
+If you have mapped a squashfs image, try mounting it with::
+
+  barebox@Sandbox:/ mount fd0
+  mounted /dev/fd0 on /mnt/fd0
+
+When called with a single argument, the barebox ``mount`` command will inspect
+the source device file's magic bytes and mount it with the appropriate file system
+under ``/mnt``.
+
+Memory can be examined as usual using md/mw commands. They understand
+the ``-s <file>`` and ``-d <file>`` options respectively to tell the commands
+that they should work on the specified files instead of ``/dev/mem`` which holds
+the complete address space.
+
+Directory Layout
+----------------
+
+Most of the directory layout is based upon the Linux Kernel
+
+.. list-table::
+
+  * - | ``arch/*``
+      | ``arch/*/include``
+      | ``arch/*/mach-*``
+      | ``include/mach/*``
+    - | contains architecture specific parts
+      | architecture specific includes
+      | SoC specific code
+      | SoC specific includes
+
+  * - | ``drivers/serial``
+      | ``drivers/net/dsa/``
+      | ``drivers/...``
+    - | drivers
+
+  * - | ``fs/``
+    - | filesystem support and filesystem drivers
+
+  * - | ``lib/``
+    - | generic library functions (getopt, readline and the like)
+
+  * - | ``common/``
+      | ``common/boards``
+    - | common stuff
+      | board code shared between multiple boards (possibly of different architectures)
+
+  * - | ``commands/``
+    - | Commands that can be executed by the barebox shell
+
+  * - | ``net/``
+    - | Networking stuff
+
+  * - | ``scripts/``
+    - | Kconfig system and tools used during barebox build or for deploying it
+
+  * - | ``Documentation/``
+    - | Sphinx generated documentation. Call "make docs" to generate a HTML version in Documentation/html.
+
+  * - | ``defaultenv/``
+    - | default environment assembled into images. Board environment is overlaid on top
+
+  * - | ``dts/``
+    - | An import of the upstream device tree repository maintained as part of the Linux kernel
+
+Release Strategy
+----------------
+
+barebox is developed with git. On a monthly schedule, tarball releases are
+branched from the repository and released on the project web site. Here
+are the release rules:
+
+- Releases follow a time based scheme::
+
+    barebox-xxxx.yy.z.tar.bz2
+            ^^^^ ^^ ^----------- Bugfix Number, starting at 0
+              \   \------------- Month
+               \---------------- Year
+
+  Example: barebox-2024.08.0.tar.bz2
+
+- As we are aiming for monthly releases, development is considered to be
+  a continuous process. If you find bugs in one release, you have the chance
+  to get patches in on a very short time scale (usually a month at most).
+
+- New features are applied to the ``next`` branch. Fixes directly to the
+  ``master`` branch. Releases are always branched from ``master`` and then
+  ``next`` is merged into ``master``. Thus new features take 1-2 months
+  until they hit a release.
+
+- Usually, there are no bugfix releases, so z=0. If there is a need
+  to make a bugfix release, z is the right place to increment.
+
+- If there may be a reason for pre releases, they are called ::
+
+    barebox-xxxx.yy.z-pren.tar.bz
+                         ^------ Number of prerelease, starting with 1
+
+  Example: barebox-2009.12.0-pre1.tar.bz2
+
+  We think that there is no need for pre releases, but if it's ever
+  necessary, this is the scheme we follow.
+
+- Only the monthly releases are archived on the web site. The tarballs
+  are located in https://www.barebox.org/download/ and this location
+  does never change, in order to make life easier for distribution
+  people.
+
+.. _contributing:
+
+Contributing
+------------
+
+barebox collaboration happens chiefly on the
+<barebox@lists.infradead.org> mailing list.
+
+The repository can be forked on `Github <https://github.com/barebox/barebox>`
+to run the CI test suite against the virtualized targets before submitting
+patches.
+
+Refer to the
+`introduction section <https://www.barebox.org/doc/latest/user/introduction.html#feedback>`_
+in the documentation for more information.
+
+License
+-------
+
+| Copyright (C) 2000 - 2005 Wolfgang Denk, DENX Software Engineering, wd@denx.de.
+| Copyright (C) 2018 Sascha Hauer, Pengutronix, and individual contributors
+|
+
+
+barebox is free software: you can redistribute it and/or modify it under the
+terms of the GNU General Public License, version 2, as published by the Free
+Software Foundation.
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License in the file
+COPYING along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+Individual files may contain the following SPDX license tags as a shorthand for
+the above copyright and warranty notices::
+
+    SPDX-License-Identifier: GPL-2.0-only
+    SPDX-License-Identifier: GPL-2.0-or-later
+
+This eases machine processing of licensing information based on the SPDX
+License Identifiers that are available at http://spdx.org/licenses/.
+
+Also note that some files in the barebox source tree are available under
+several different GPLv2-compatible open-source licenses. This fact is noted
+clearly in the file headers of the respective files and the full license
+text is reproduced in the ``LICENSES/`` directory.
-- 
2.39.2