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

Move to the new documentation style with rST formatting.

Signed-off-by: Vasileios Amoiridis <vassilisamir@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

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@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@cherry.de>

Thanks!
Quentin

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@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@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

Hi Vasileios,

On Thu, 13 Jun 2024 at 16:04, Vasileios Amoiridis
<vassilisamir@gmail.com> wrote:
>
> Move to the new documentation style with rST formatting.
>
> Signed-off-by: Vasileios Amoiridis <vassilisamir@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

Thanks for doing this. Can you please add it to an index file so it
can be navigated to? You can check it with 'make htmldocs'.

Regards,
Simon

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@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@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.