From 370787a227ba9db863024b1dca2fbac16307c566 Mon Sep 17 00:00:00 2001 From: Henrik Brix Andersen Date: Thu, 4 Jul 2024 12:41:11 +0200 Subject: [PATCH] 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 --- MAINTAINERS.yml | 2 +- doc/_scripts/redirects.py | 1 + .../{eeprom.rst => eeprom/api.rst} | 7 +- doc/hardware/peripherals/eeprom/index.rst | 16 ++++ doc/hardware/peripherals/eeprom/shell.rst | 91 +++++++++++++++++++ doc/hardware/peripherals/index.rst | 2 +- 6 files changed, 112 insertions(+), 7 deletions(-) rename doc/hardware/peripherals/{eeprom.rst => eeprom/api.rst} (58%) create mode 100644 doc/hardware/peripherals/eeprom/index.rst create mode 100644 doc/hardware/peripherals/eeprom/shell.rst diff --git a/MAINTAINERS.yml b/MAINTAINERS.yml index d18919a3625..6537e18d21d 100644 --- a/MAINTAINERS.yml +++ b/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: diff --git a/doc/_scripts/redirects.py b/doc/_scripts/redirects.py index 1f96c762c86..e734d81ef55 100644 --- a/doc/_scripts/redirects.py +++ b/doc/_scripts/redirects.py @@ -143,6 +143,7 @@ REDIRECTS = [ ('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'), diff --git a/doc/hardware/peripherals/eeprom.rst b/doc/hardware/peripherals/eeprom/api.rst similarity index 58% rename from doc/hardware/peripherals/eeprom.rst rename to doc/hardware/peripherals/eeprom/api.rst index e4dfb518553..7d8d637a497 100644 --- a/doc/hardware/peripherals/eeprom.rst +++ b/doc/hardware/peripherals/eeprom/api.rst @@ -1,7 +1,7 @@ .. _eeprom_api: -Electrically Erasable Programmable Read-Only Memory (EEPROM) -############################################################ +EEPROM API +########## Overview ******** @@ -9,9 +9,6 @@ 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 ********************* diff --git a/doc/hardware/peripherals/eeprom/index.rst b/doc/hardware/peripherals/eeprom/index.rst new file mode 100644 index 00000000000..cfbe39fc556 --- /dev/null +++ b/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 diff --git a/doc/hardware/peripherals/eeprom/shell.rst b/doc/hardware/peripherals/eeprom/shell.rst new file mode 100644 index 00000000000..b1b1535e8e4 --- /dev/null +++ b/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 +` module. It allows testing and exploring the :ref:`EEPROM ` 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 ` 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 ` 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 |........ | diff --git a/doc/hardware/peripherals/index.rst b/doc/hardware/peripherals/index.rst index 0af23d02fca..e3e85254e6c 100644 --- a/doc/hardware/peripherals/index.rst +++ b/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