[PATCH v3 2/2] doc: api: bootcount: Convert to rST documentation

[Vasileios Amoiridis]

On Fri, Jun 14, 2024 at 10:43:09AM +0200, Quentin Schulz wrote:
> Hi Vasileios,
> 
> On 6/14/24 12:02 AM, Vasileios Amoiridis wrote:
> > Move to the new documentation style with rST formatting.
> > 
> > Signed-off-by: Vasileios Amoiridis <vassilisamir at gmail.com>
> > ---
> >   doc/README.bootcount  | 53 ---------------------------------------
> >   doc/api/bootcount.rst | 58 +++++++++++++++++++++++++++++++++++++++++++
> >   2 files changed, 58 insertions(+), 53 deletions(-)
> >   delete mode 100644 doc/README.bootcount
> >   create mode 100644 doc/api/bootcount.rst
> > 
> > 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``
> 
> I think what was meant here is likely "unintended" (not deliberate) rather
> than "unattended" (unsupervised)?
> 
> I understand you didn't introduce this and just migrated it to rST, so free
> patch to whoever feels like sending one :)
> 
> Reviewed-by: Quentin Schulz <quentin.schulz at cherry.de>
> 
> Thanks!
> Quentin

Well if Tom agrees also with the previous patch then maybe I can send a v4
correcting those 2 issues it's fine for me!

Cheers,
Vasilis