1.. _eeprom_shell:
2
3EEPROM Shell
4############
5
6.. contents::
7    :local:
8    :depth: 1
9
10Overview
11********
12
13The EEPROM shell provides an ``eeprom`` command with a set of subcommands for the :ref:`shell
14<shell_api>` module. It allows testing and exploring the :ref:`EEPROM <eeprom_api>` driver API
15through an interactive interface without having to write a dedicated application. The EEPROM shell
16can also be enabled in existing applications to aid in interactive debugging of EEPROM issues.
17
18In order to enable the EEPROM shell, the following :ref:`Kconfig <kconfig>` options must be enabled:
19
20* :kconfig:option:`CONFIG_SHELL`
21* :kconfig:option:`CONFIG_EEPROM`
22* :kconfig:option:`CONFIG_EEPROM_SHELL`
23
24For example, building the :ref:`hello_world` sample for the :ref:`native_sim` with the EEPROM shell:
25
26.. zephyr-app-commands::
27   :zephyr-app: samples/hello_world
28   :board: native_sim
29   :gen-args: -DCONFIG_SHELL=y -DCONFIG_EEPROM=y -DCONFIG_EEPROM_SHELL=y
30   :goals: build
31
32See the :ref:`shell <shell_api>` documentation for general instructions on how to connect and
33interact with the shell. The EEPROM shell comes with built-in help (unless
34:kconfig:option:`CONFIG_SHELL_HELP` is disabled). The built-in help messages can be printed by
35passing ``-h`` or ``--help`` to the ``eeprom`` command or any of its subcommands. All subcommands
36also support tab-completion of their arguments.
37
38.. tip::
39   All of the EEPROM shell subcommands take the name of an EEPROM peripheral as their first argument,
40   which also supports tab-completion. A list of all devices available can be obtained using the
41   ``device list`` shell command when :kconfig:option:`CONFIG_DEVICE_SHELL` is enabled. The examples
42   below all use the device name ``eeprom@0``.
43
44EEPROM Size
45***********
46
47The size of an EEPROM can be inspected using the ``eeprom size`` subcommand as shown below:
48
49.. code-block:: console
50
51   uart:~$ eeprom size eeprom@0
52   32768 bytes
53
54Writing Data
55************
56
57Data can be written to an EEPROM using the ``eeprom write`` subcommand. This subcommand takes at
58least three arguments; the EEPROM device name, the offset to start writing to, and at least one data
59byte. In the following example, the hexadecimal sequence of bytes ``0x0d 0x0e 0x0a 0x0d 0x0b 0x0e
600x0e 0x0f`` is written to offset ``0x0``:
61
62.. code-block:: console
63
64   uart:~$ eeprom write eeprom@0 0x0 0x0d 0x0e 0x0a 0x0d 0x0b 0x0e 0x0e 0x0f
65   Writing 8 bytes to EEPROM...
66   Verifying...
67   Verify OK
68
69It is also possible to fill a portion of the EEPROM with the same pattern using the ``eeprom fill``
70subcommand. In the following example, the pattern ``0xaa`` is written to 16 bytes starting at offset
71``0x8``:
72
73.. code-block:: console
74
75   uart:~$ eeprom fill eeprom@0 0x8 16 0xaa
76   Writing 16 bytes of 0xaa to EEPROM...
77   Verifying...
78   Verify OK
79
80Reading Data
81************
82
83Data can be read from an EEPROM using the ``eeprom read`` subcommand. This subcommand takes three
84arguments; the EEPROM device name, the offset to start reading from, and the number of bytes to
85read:
86
87.. code-block:: console
88
89   uart:~$ eeprom read eeprom@0 0x0 8
90   Reading 8 bytes from EEPROM, offset 0...
91   00000000: 0d 0e 0a 0d 0b 0e 0e 0f                          |........         |
92