[thirdparty/u-boot.git] / doc / README.bootcount

.. SPDX-License-Identifier: GPL-2.0+

Boot Count Limit
================

This allows to detect multiple failed attempts to boot Linux.

After a power-on reset, "bootcount" variable will be initialized with 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", thus allowing for more boot
cycles.

BOOTCOUNT_EXT
-------------

This adds support for maintaining boot count in a file on an EXT filesystem.
The file to use is define by:

SYS_BOOTCOUNT_EXT_INTERFACE
SYS_BOOTCOUNT_EXT_DEVPART
SYS_BOOTCOUNT_EXT_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 save.
So the Userspace Application must set the "upgrade_available" and "bootcount"
variables to 0, if a boot was successfully.
This also prevents writes on all reboots.
Commit	Line	Data
df928f85 FD	1	.. SPDX-License-Identifier: GPL-2.0+
	2
	3	Boot Count Limit
	4	================
	5
	6	This allows to detect multiple failed attempts to boot Linux.
	7
	8	After a power-on reset, "bootcount" variable will be initialized with 1, and
	9	each reboot will increment the value by 1.
	10
	11	If, after a reboot, the new value of "bootcount" exceeds the value of
	12	"bootlimit", then instead of the standard boot action (executing the contents of
	13	"bootcmd") an alternate boot action will be performed, and the contents of
	14	"altbootcmd" will be executed.
	15
	16	If the variable "bootlimit" is not defined in the environment, the Boot Count
	17	Limit feature is disabled. If it is enabled, but "altbootcmd" is not defined,
	18	then U-Boot will drop into interactive mode and remain there.
	19
	20	It is the responsibility of some application code (typically a Linux
	21	application) to reset the variable "bootcount", thus allowing for more boot
	22	cycles.
	23
	24	BOOTCOUNT_EXT
	25	-------------
	26
	27	This adds support for maintaining boot count in a file on an EXT filesystem.
	28	The file to use is define by:
	29
	30	SYS_BOOTCOUNT_EXT_INTERFACE
	31	SYS_BOOTCOUNT_EXT_DEVPART
	32	SYS_BOOTCOUNT_EXT_NAME
	33
	34	The format of the file is:
	35
	36	==== =================
	37	type entry
	38	==== =================
	39	u8 magic
	40	u8 version
	41	u8 bootcount
	42	u8 upgrade_available
	43	==== =================
	44
	45	To prevent unattended usage of "altbootcmd" the "upgrade_available" variable is
	46	used.
	47	If "upgrade_available" is 0, "bootcount" is not saved, if "upgrade_available" is
	48	1 "bootcount" is save.
	49	So the Userspace Application must set the "upgrade_available" and "bootcount"
	50	variables to 0, if a boot was successfully.
	51	This also prevents writes on all reboots.