doc: hardware: peripherals: eeprom: reorganize and add EEPROM shell page

Reorganize the EEPROM periheral documentation to make room for subpages
with additional details. Add a page describing the EEPROM shell module.

Signed-off-by: Henrik Brix Andersen <[email protected]>

MAINTAINERS.yml

@@ -1206,7 +1206,7 @@ Release Notes:
     - samples/drivers/eeprom/
     - tests/drivers/eeprom/
     - tests/drivers/*/eeprom/
-    - doc/hardware/peripherals/eeprom.rst
+    - doc/hardware/peripherals/eeprom/
   labels:
     - "area: EEPROM"
   tests:

doc/_scripts/redirects.py

@@ -143,6 +143,7 @@
     ('guides/west/workspaces', 'develop/west/workspaces'),
     ('guides/west/zephyr-cmds', 'develop/west/zephyr-cmds'),
     ('guides/zephyr_cmake_package', 'build/zephyr_cmake_package'),
+    ('hardware/peripherals/eeprom', 'hardware/peripherals/eeprom/index')
     ('hardware/peripherals/sensor', 'hardware/peripherals/sensor/index'),
     ('reference/api/api_lifecycle', 'develop/api/api_lifecycle'),
     ('reference/api/index', 'develop/api/index'),

doc/hardware/peripherals/eeprom.rst → doc/hardware/peripherals/eeprom/api.rst

@@ -1,17 +1,14 @@
 .. _eeprom_api:
 
-Electrically Erasable Programmable Read-Only Memory (EEPROM)
-############################################################
+EEPROM API
+##########
 
 Overview
 ********
 
 The EEPROM API provides read and write access to Electrically Erasable
 Programmable Read-Only Memory (EEPROM) devices.
 
-EEPROMs have an erase block size of 1 byte, a long lifetime, and allow
-overwriting data on byte-by-byte access.
-
 Configuration Options
 *********************
 

doc/hardware/peripherals/eeprom/index.rst

@@ -0,0 +1,16 @@
+.. _eeprom:
+
+Electrically Erasable Programmable Read-Only Memory (EEPROM)
+############################################################
+
+Overview
+********
+
+EEPROMs have an erase block size of 1 byte, a long lifetime, and allow
+overwriting data on byte-by-byte access.
+
+.. toctree::
+   :maxdepth: 2
+
+   api.rst
+   shell.rst

doc/hardware/peripherals/eeprom/shell.rst

@@ -0,0 +1,91 @@
+.. _eeprom_shell:
+
+EEPROM Shell
+############
+
+.. contents::
+    :local:
+    :depth: 1
+
+Overview
+********
+
+The EEPROM shell provides an ``eeprom`` command with a set of subcommands for the :ref:`shell
+<shell_api>` module. It allows testing and exploring the :ref:`EEPROM <eeprom_api>` driver API
+through an interactive interface without having to write a dedicated application. The EEPROM shell
+can also be enabled in existing applications to aid in interactive debugging of EEPROM issues.
+
+In order to enable the EEPROM shell, the following :ref:`Kconfig <kconfig>` options must be enabled:
+
+* :kconfig:option:`CONFIG_SHELL`
+* :kconfig:option:`CONFIG_EEPROM`
+* :kconfig:option:`CONFIG_EEPROM_SHELL`
+
+For example, building the :ref:`hello_world` sample for the :ref:`native_sim` with the EEPROM shell:
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/hello_world
+   :board: native_sim
+   :gen-args: -DCONFIG_SHELL=y -DCONFIG_EEPROM=y -DCONFIG_EEPROM_SHELL=y
+   :goals: build
+
+See the :ref:`shell <shell_api>` documentation for general instructions on how to connect and
+interact with the shell. The EEPROM shell comes with built-in help (unless
+:kconfig:option:`CONFIG_SHELL_HELP` is disabled). The built-in help messages can be printed by
+passing ``-h`` or ``--help`` to the ``eeprom`` command or any of its subcommands. All subcommands
+also support tab-completion of their arguments.
+
+.. tip::
+   All of the EEPROM shell subcommands take the name of an EEPROM peripheral as their first argument,
+   which also supports tab-completion. A list of all devices available can be obtained using the
+   ``device list`` shell command when :kconfig:option:`CONFIG_DEVICE_SHELL` is enabled. The examples
+   below all use the device name ``eeprom@0``.
+
+EEPROM Size
+***********
+
+The size of an EEPROM can be inspected using the ``eeprom size`` subcommand as shown below:
+
+.. code-block:: console
+
+   uart:~$ eeprom size eeprom@0
+   32768 bytes
+
+Writing Data
+************
+
+Data can be written to an EEPROM using the ``eeprom write`` subcommand. This subcommand takes at
+least three arguments; the EEPROM device name, the offset to start writing to, and at least one data
+byte. In the following example, the hexadecimal sequence of bytes ``0x0d 0x0e 0x0a 0x0d 0x0b 0x0e
+0x0e 0x0f`` is written to offset ``0x0``:
+
+.. code-block:: console
+
+   uart:~$ eeprom write eeprom@0 0x0 0x0d 0x0e 0x0a 0x0d 0x0b 0x0e 0x0e 0x0f
+   Writing 8 bytes to EEPROM...
+   Verifying...
+   Verify OK
+
+It is also possible to fill a portion of the EEPROM with the same pattern using the ``eeprom fill``
+subcommand. In the following example, the pattern ``0xaa`` is written to 16 bytes starting at offset
+``0x8``:
+
+.. code-block:: console
+
+   uart:~$ eeprom fill eeprom@0 0x8 16 0xaa
+   Writing 16 bytes of 0xaa to EEPROM...
+   Verifying...
+   Verify OK
+
+Reading Data
+************
+
+Data can be read from an EEPROM using the ``eeprom read`` subcommand. This subcommand takes three
+arguments; the EEPROM device name, the offset to start reading from, and the number of bytes to
+read:
+
+.. code-block:: console
+
+   uart:~$ eeprom read eeprom@0 0x0 8
+   Reading 8 bytes from EEPROM, offset 0...
+   00000000: 0d 0e 0a 0d 0b 0e 0e 0f                          |........         |

doc/hardware/peripherals/index.rst

@@ -23,7 +23,7 @@ Peripherals
    dac.rst
    dma.rst
    display/index.rst
-   eeprom.rst
+   eeprom/index.rst
    espi.rst
    entropy.rst
    edac/index.rst