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

[Tom Rini]

On Sun, Jun 16, 2024 at 08:20:53PM +0200, Vasileios Amoiridis wrote:
> 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!

Yes, please do a v4 with that and adding this to the index in
doc/api/index.rst so that CI will not fail.

-- 
Tom
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 659 bytes
Desc: not available
URL: <https://lists.denx.de/pipermail/u-boot/attachments/20240617/a1d1d176/attachment.sig>