[RFC PATCH v2 2/5] doc: cmd: add documentation for fuse command

[Harsha Vardhan V M <h-vm@ti.com>]

Add documentation for the 'fuse' sub-system commands.

Signed-off-by: Harsha Vardhan V M <h-vm@ti.com>
---
 doc/usage/cmd/fuse.rst | 156 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 156 insertions(+)
 create mode 100644 doc/usage/cmd/fuse.rst

diff --git a/doc/usage/cmd/fuse.rst b/doc/usage/cmd/fuse.rst
new file mode 100644
index 00000000000..6e330eddfea
--- /dev/null
+++ b/doc/usage/cmd/fuse.rst
@@ -0,0 +1,156 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+.. index::
+   single: fuse (command)
+
+fuse command
+============
+
+Synopsis
+--------
+
+::
+
+    fuse read <bank> <word> [<cnt>]
+    fuse cmp <bank> <word> <hexval>
+    fuse readm <bank> <word> <addr> [<cnt>]
+    fuse sense <bank> <word> [<cnt>]
+    fuse prog [-y] <bank> <word> <hexval> [<hexval>...]
+    fuse override <bank> <word> <hexval> [<hexval>...]
+
+Description
+-----------
+
+The fuse API allows to control a fusebox and how it is used by the upper
+hardware layers.
+
+A fuse corresponds to a single non-volatile memory bit that can be programmed
+(i.e., blown, set to 1) only once. The programming operation is irreversible.
+A fuse that has not been programmed reads as 0.
+
+Fuses can be used by SoCs to store various permanent configurations and data,
+such as boot configurations, security settings, MAC addresses, etc.
+
+A fuse 'word' is the smallest group of fuses that can be read at once from
+the fusebox control IP registers. In the current API, this is limited to 32 bits.
+
+A fuse 'bank' is the smallest group of fuse words having a common ID, as
+defined by each SoC.
+
+Upon startup, the fusebox control IP reads the fuse values and stores them in a
+volatile shadow cache.
+
+Commands
+--------
+
+- **fuse read <bank> <word> [<cnt>]**
+  Reads 1 or 'cnt' fuse words, starting at 'word' from the shadow cache.
+
+- **fuse cmp <bank> <word> <hexval>**
+  Compares 'hexval' to fuse at 'word'.
+
+- **fuse readm <bank> <word> <addr> [<cnt>]**
+  Reads 1 or 'cnt' fuse words, starting at 'word' into memory at 'addr'.
+
+- **fuse sense <bank> <word> [<cnt>]**
+  Sense 1 or 'cnt' fuse words, starting at 'word'.
+  Sense - i.e. read directly from the fusebox, skipping the shadow cache -
+  fuse words. This operation does not update the shadow cache. This is
+  useful to know the true value of fuses if an override has been
+  performed (see below).
+
+- **fuse prog [-y] <bank> <word> <hexval> [<hexval>...]**
+  Permanently programs 1 or several fuse words, starting at 'word'.
+  This operation directly affects the fusebox and is irreversible. The
+  shadow cache is updated accordingly or not, depending on each IP.
+  Only the bits to be programmed should be set in the input value (i.e.
+  for fuse bits that have already been programmed and hence should be
+  left unchanged by a further programming, it is preferable to clear
+  the corresponding bits in the input value in order not to perform a
+  new hardware programming operation on these fuse bits).
+
+- **fuse override <bank> <word> <hexval> [<hexval>...]**
+  Override 1 or several fuse words, starting at 'word' in the shadow cache.
+  The fusebox is unaffected, so following this operation, the shadow cache
+  may differ from the fusebox values. Read or sense operations can then be
+  used to get the values from the shadow cache or from the fusebox.
+  This is useful to change the behaviours linked to some cached fuse values,
+  either because this is needed only temporarily, or because some of the
+  fuses have already been programmed or are locked (if the SoC allows to
+  override a locked fuse).
+
+Examples
+--------
+
+fuse read
+~~~~~~~~~
+
+::
+
+    u-boot=> fuse read 0 1
+      Reading bank 0:
+
+      Word 0x00000001: 00000001
+
+fuse cmp
+~~~~~~~~
+
+::
+
+    u-boot=> fuse cmp 0 1 0x1
+      Comparing bank 0:
+
+      Word 0x00000001:
+      Value 0x00000001:0x00000001
+      passed
+
+fuse readm
+~~~~~~~~~~
+
+::
+
+    u-boot=> fuse readm 0 1 0x83000000
+      Reading bank 0 len 1 to 0x83000000
+
+fuse sense
+~~~~~~~~~~
+
+::
+
+    u-boot=> fuse sense 0 1
+      Sensing bank 0:
+
+      Word 0x00000001: 00000001
+
+fuse prog
+~~~~~~~~~
+
+::
+
+    u-boot=> fuse prog 0 1 0x00000002
+      Programming bank 0 word 0x00000001 to 0x00000002...
+      Warning: Programming fuses is an irreversible operation!
+               This may brick your system.
+               Use this command only if you are sure of what you are doing!
+
+      Really perform this fuse programming? <y/N>
+      y
+
+fuse override
+~~~~~~~~~~~~~
+
+::
+
+    u-boot=> fuse override 0 1 0x00000003
+      Overriding bank 0 word 0x00000001 with 0x00000003...
+
+Configuration
+-------------
+
+The fuse commands are available if CONFIG_CMD_FUSE=y.
+
+Return code
+-----------
+
+The return value $? is set to 0 (true) if the command is successful,
+1 (false) otherwise.
-- 
2.34.1