From: Vasileios Amoiridis <vassilisamir@gmail.com>
Date: Fri, 28 Jun 2024 17:35:42 +0000 (+0200)
Subject: doc: api: bootcount: Convert to rST documentation
X-Git-Tag: v2025.01-rc5-pxa1908~400^2~1
X-Git-Url: http://git.dujemihanovic.xyz/%22http:/www.sics.se/static/%7B%7B%20%24.Site.BaseURL%20%7D%7Dposts/%7B%7B%20%24style.Permalink%20%7D%7D?a=commitdiff_plain;h=1c1e484ba856fa03122a01cd9e7b8e038fa5d1bc;p=u-boot.git

doc: api: bootcount: Convert to rST documentation

Move to the new documentation style with rST formatting.

Signed-off-by: Vasileios Amoiridis <vasileios.amoiridis@cern.ch>
---

diff --git a/doc/README.bootcount b/doc/README.bootcount
deleted file mode 100644
index 0f4ffb6828..0000000000
--- a/doc/README.bootcount
+++ /dev/null
@@ -1,53 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0+
-
-Boot Count Limit
-================
-
-This is enabled by CONFIG_BOOTCOUNT_LIMIT.
-
-This allows to detect multiple failed attempts to boot Linux.
-
-After a power-on reset, the "bootcount" variable will be initialized to 1, and
-each reboot will increment the value by 1.
-
-If, after a reboot, the new value of "bootcount" exceeds the value of
-"bootlimit", then instead of the standard boot action (executing the contents of
-"bootcmd"), an alternate boot action will be performed, and the contents of
-"altbootcmd" will be executed.
-
-If the variable "bootlimit" is not defined in the environment, the Boot Count
-Limit feature is disabled. If it is enabled, but "altbootcmd" is not defined,
-then U-Boot will drop into interactive mode and remain there.
-
-It is the responsibility of some application code (typically a Linux
-application) to reset the variable "bootcount" to 0 when the system booted
-successfully, thus allowing for more boot cycles.
-
-CONFIG_BOOTCOUNT_FS
---------------------
-
-This adds support for maintaining boot count in a file on a filesystem.
-Supported filesystems are FAT and EXT. The file to use is defined by:
-
-CONFIG_SYS_BOOTCOUNT_FS_INTERFACE
-CONFIG_SYS_BOOTCOUNT_FS_DEVPART
-CONFIG_SYS_BOOTCOUNT_FS_NAME
-
-The format of the file is:
-
-==== =================
-type entry
-==== =================
-u8   magic
-u8   version
-u8   bootcount
-u8   upgrade_available
-==== =================
-
-To prevent unattended usage of "altbootcmd", the "upgrade_available" variable is
-used.
-If "upgrade_available" is 0, "bootcount" is not saved.
-If "upgrade_available" is 1, "bootcount" is saved.
-So a userspace application should take care of setting the "upgrade_available"
-and "bootcount" variables to 0, if the system boots successfully.
-This also avoids writing the "bootcount" information on all reboots.
diff --git a/doc/api/bootcount.rst b/doc/api/bootcount.rst
new file mode 100644
index 0000000000..9435a7ef15
--- /dev/null
+++ b/doc/api/bootcount.rst
@@ -0,0 +1,58 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Boot Count Limit
+================
+
+This is enabled by CONFIG_BOOTCOUNT_LIMIT.
+
+This allows to detect multiple failed attempts to boot Linux.
+
+After a power-on reset, the ``bootcount`` variable will be initialized to 1, and
+each reboot will increment the value by 1.
+
+If, after a reboot, the new value of ``bootcount`` exceeds the value of
+``bootlimit``, then instead of the standard boot action (executing the contents
+of ``bootcmd``), an alternate boot action will be performed, and the contents of
+``altbootcmd`` will be executed.
+
+If the variable ``bootlimit`` is not defined in the environment, the Boot Count
+Limit feature is disabled. If it is enabled, but ``altbootcmd`` is not defined,
+then U-Boot will drop into interactive mode and remain there.
+
+It is the responsibility of some application code (typically a Linux
+application) to reset the variable ``bootcount`` to 0 when the system booted
+successfully, thus allowing for more boot cycles.
+
+CONFIG_BOOTCOUNT_FS
+--------------------
+
+This adds support for maintaining boot count in a file on a filesystem.
+Tested filesystems are FAT and EXT. The file to use is defined by:
+
+CONFIG_SYS_BOOTCOUNT_FS_INTERFACE
+CONFIG_SYS_BOOTCOUNT_FS_DEVPART
+CONFIG_SYS_BOOTCOUNT_FS_NAME
+
+The format of the file is:
+
+.. list-table::
+   :header-rows: 1
+
+   * - type
+     - entry
+   * - u8
+     - magic
+   * - u8
+     - version
+   * - u8
+     - bootcount
+   * - u8
+     - upgrade_available
+
+To prevent unattended usage of ``altbootcmd``, the ``upgrade_available``
+variable is used.
+If ``upgrade_available`` is 0, ``bootcount`` is not saved.
+If ``upgrade_available`` is 1, ``bootcount`` is saved.
+So a userspace application should take care of setting the ``upgrade_available``
+and ``bootcount`` variables to 0, if the system boots successfully.
+This also avoids writing the ``bootcount`` information on all reboots.
diff --git a/doc/api/index.rst b/doc/api/index.rst
index 51b2013af3..ec0b8adb2c 100644
--- a/doc/api/index.rst
+++ b/doc/api/index.rst
@@ -6,6 +6,7 @@ U-Boot API documentation
 .. toctree::
    :maxdepth: 2
 
+   bootcount
    clk
    dfu
    dm