1.. _flash_map_api:
2
3Flash map
4#########
5
6The ``<zephyr/storage/flash_map.h>`` API allows accessing information about device
7flash partitions via :c:struct:`flash_area` structures.
8
9Each :c:struct:`flash_area` describes a flash partition. The API provides access
10to a "flash map", which contains predefined flash areas accessible via globally
11unique ID numbers. The map is created from "fixed-partition" compatible entries
12in DTS file. Users may also create :c:struct:`flash_area` objects at runtime
13for application-specific purposes.
14
15This documentation uses "flash area" when referencing single "fixed-partition"
16entities.
17
18The :c:struct:`flash_area` contains a pointer to a :c:struct:`device`,
19which can be used to access the flash device an area is placed on directly
20with the :ref:`flash API <flash_api>`.
21Each flash area is characterized by a device it is placed on, offset
22from the beginning of the device and size on the device.
23An additional identifier parameter is used by the :c:func:`flash_area_open`
24function to find flash area in flash map.
25
26The flash_map.h API provides functions for operating on a :c:struct:`flash_area`.
27The main examples are :c:func:`flash_area_read` and :c:func:`flash_area_write`.
28These functions are basically wrappers around the flash API with additional
29offset and size checks, to limit flash operations to a predefined area.
30
31Most ``<zephyr/storage/flash_map.h>`` API functions require a :c:struct:`flash_area` object pointer
32characterizing the flash area they will be working on. There are two possible
33methods to obtain such a pointer:
34
35 * obtain it using `flash_area_open`;
36
37 * defining a :c:struct:`flash_area` type object, which requires providing
38   a valid :c:struct:`device` object pointer with offset and size of the area
39   within the flash device.
40
41:c:func:`flash_area_open` uses numeric identifiers to search flash map for
42:c:struct:`flash_area` objects and returns, if found, a pointer to an object
43representing area with given ID.
44The ID number for a flash area can be obtained from a fixed-partition
45DTS node label using :c:macro:`FIXED_PARTITION_ID()`; these labels are obtained
46from the devicetree as described below.
47
48Relationship with Devicetree
49****************************
50
51The flash_map.h API uses data generated from the :ref:`devicetree_api`, in
52particular its :ref:`devicetree-flash-api`. Zephyr additionally has some
53partitioning conventions used for :ref:`dfu` via the MCUboot bootloader, as
54well as defining partitions usable by :ref:`file systems <file_system_api>` or
55other nonvolatile :ref:`storage <storage_reference>`.
56
57Here is an example devicetree fragment which uses fixed flash partitions for
58both MCUboot and a storage partition. Some details were left out for clarity.
59
60.. literalinclude:: example_fragment.dts
61   :language: DTS
62   :start-after: start-after-here
63
64Partition offset shall be expressed in relation to the flash memory beginning
65address, to which the partition belongs to.
66
67The ``boot_partition``, ``slot0_partition``, ``slot1_partition``, and
68``scratch_partition`` node labels are defined for MCUboot, though not all MCUboot
69configurations require all of them to be defined. See the `MCUboot
70documentation`_ for more details.
71
72The ``storage_partition`` node is defined for use by a file system or other
73nonvolatile storage API.
74
75.. _MCUboot documentation: https://docs.mcuboot.com
76
77Numeric flash area ID is obtained by passing DTS node label to
78:c:macro:`FIXED_PARTITION_ID()`; for example to obtain ID number
79for ``slot0_partition``, user would invoke ``FIXED_PARTITION_ID(slot0_partition)``.
80
81All :c:macro:`FIXED_PARTITION_` macros take DTS node labels as partition
82identifiers.
83
84Users do not have to obtain a :c:struct:`flash_area` object pointer
85using :c:func:`flash_map_open` to get information on flash area size, offset
86or device, if such area is defined in DTS file. Knowing the DTS node label
87of an area, users may use :c:macro:`FIXED_PARTITION_OFFSET()`,
88:c:macro:`FIXED_PARTITION_SIZE()` or :c:macro:`FIXED_PARTITION_DEVICE()`
89respectively to obtain such information directly from DTS node definition.
90For example to obtain offset of ``storage_partition`` it is enough to
91invoke ``FIXED_PARTITION_OFFSET(storage_partition)``.
92
93Below example shows how to obtain a :c:struct:`flash_area` object pointer
94using :c:func:`flash_area_open` and DTS node label:
95
96.. code-block:: c
97
98   const struct flash_area *my_area;
99   int err = flash_area_open(FIXED_PARTITION_ID(slot0_partition), &my_area);
100
101   if (err != 0) {
102   	handle_the_error(err);
103   } else {
104   	flash_area_read(my_area, ...);
105   }
106
107API Reference
108*************
109
110.. doxygengroup:: flash_area_api
111