From 389be395c69782f3faf3d27efe92133954dc9c07 Mon Sep 17 00:00:00 2001
From: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
Date: Sun, 15 Jan 2023 11:35:55 +0100
Subject: [PATCH] doc: man-page for blkcache

Provide a man-page for the blkcache command.

Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
Reviewed-by: Simon Glass <sjg@chromium.org>
---
 doc/usage/cmd/blkcache.rst | 74 ++++++++++++++++++++++++++++++++++++++
 doc/usage/index.rst        |  1 +
 2 files changed, 75 insertions(+)
 create mode 100644 doc/usage/cmd/blkcache.rst

diff --git a/doc/usage/cmd/blkcache.rst b/doc/usage/cmd/blkcache.rst
new file mode 100644
index 0000000000..d3b2254cfa
--- /dev/null
+++ b/doc/usage/cmd/blkcache.rst
@@ -0,0 +1,74 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright 2023, Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
+
+blkcache command
+================
+
+Synopsis
+--------
+
+::
+
+    blkcache show
+    blkcache configure <blocks> <entries>
+
+Description
+-----------
+
+The *blkcache* command is used to control the size of the block cache and to
+display statistics.
+
+The block cache buffers data read from block devices. This speeds up the access
+to file-systems.
+
+show
+    show and reset statistics
+
+configure
+    set the maximum number of cache entries and the maximum number of blocks per
+    entry
+
+blocks
+    maximum number of blocks per cache entry. The block size is device specific.
+    The initial value is 8.
+
+entries
+    maximum number of entries in the cche. The initial value is 32.
+
+Example
+-------
+
+.. code-block::
+
+    => blkcache show
+    hits: 296
+    misses: 149
+    entries: 7
+    max blocks/entry: 8
+    max cache entries: 32
+    => blkcache show
+    hits: 0
+    misses: 0
+    entries: 7
+    max blocks/entry: 8
+    max cache entries: 32
+    => blkcache configure 16 64
+    changed to max of 64 entries of 16 blocks each
+    => blkcache show
+    hits: 0
+    misses: 0
+    entries: 0
+    max blocks/entry: 16
+    max cache entries: 64
+    =>
+
+Configuration
+-------------
+
+The blkcache command is only available if CONFIG_CMD_BLOCK_CACHE=y.
+
+Return code
+-----------
+
+If the command succeeds, the return code $? is set 0 (true). In case of an
+error the return code is set to 1 (false).
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index 53e4aeec56..9284d159d7 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -23,6 +23,7 @@ Shell commands
    cmd/addrmap
    cmd/askenv
    cmd/base
+   cmd/blkcache
    cmd/bootd
    cmd/bootdev
    cmd/bootefi
-- 
2.39.5