flash_map.h

Go to the documentation of this file.

/*
 * Copyright (c) 2017-2024 Nordic Semiconductor ASA
 * Copyright (c) 2015 Runtime Inc
 * Copyright (c) 2023 Sensorfy B.V.
 *
 * SPDX-License-Identifier: Apache-2.0
 */

 
#ifndef ZEPHYR_INCLUDE_STORAGE_FLASH_MAP_H_
#define ZEPHYR_INCLUDE_STORAGE_FLASH_MAP_H_

 
/*
 * This API makes it possible to operate on flash areas easily and
 * effectively.
 *
 * The system contains global data about flash areas. Every area
 * contains an ID number, offset, and length.
 */

#include <zephyr/types.h>
#include <stddef.h>
#include <sys/types.h>
#include <zephyr/device.h>
#include <zephyr/devicetree.h>
#include <zephyr/devicetree/fixed-partitions.h>
#include <zephyr/devicetree/mapped-partition.h>
#include <zephyr/devicetree/partitions.h>
 
#ifdef __cplusplus
extern "C" {
#endif

struct flash_area {
        uint8_t fa_id;
        uint16_t pad16;
        off_t fa_off;
        size_t fa_size;
        const struct device *fa_dev;
#if defined(CONFIG_FLASH_MAP_LABELS)
        const char *fa_label;
#endif
};

struct flash_sector {
        ptrdiff_t fs_off;
        size_t fs_size;
};
 
#if defined(CONFIG_FLASH_AREA_CHECK_INTEGRITY)
struct flash_area_check {
        const uint8_t *match;           
        size_t clen;                    
        size_t off;                     
        uint8_t *rbuf;                  
        size_t rblen;                   
};

int flash_area_check_int_sha256(const struct flash_area *fa,
                                const struct flash_area_check *fac);
#endif

int flash_area_open(uint8_t id, const struct flash_area **fa);

static inline void flash_area_close(__unused const struct flash_area *fa)
{
        /* nothing to do for now */
}

static ALWAYS_INLINE bool flash_area_device_is_ready(const struct flash_area *fa)
{
        return (fa != NULL && device_is_ready(fa->fa_dev));
}

int flash_area_read(const struct flash_area *fa, off_t off, void *dst,
                    size_t len);

int flash_area_write(const struct flash_area *fa, off_t off, const void *src,
                     size_t len);

int flash_area_copy(const struct flash_area *src_fa, off_t src_off,
                    const struct flash_area *dst_fa, off_t dst_off,
                    off_t len, uint8_t *buf, size_t buf_size);

int flash_area_erase(const struct flash_area *fa, off_t off, size_t len);

int flash_area_flatten(const struct flash_area *fa, off_t off, size_t len);

uint32_t flash_area_align(const struct flash_area *fa);

int flash_area_get_sectors(int fa_id, uint32_t *count,
                           struct flash_sector *sectors);

int flash_area_sectors(const struct flash_area *fa, uint32_t *count, struct flash_sector *sectors);

typedef void (*flash_area_cb_t)(const struct flash_area *fa,
                                void *user_data);

void flash_area_foreach(flash_area_cb_t user_cb, void *user_data);

int flash_area_has_driver(const struct flash_area *fa);

static inline const struct device *flash_area_get_device(const struct flash_area *fa)
{
        return fa->fa_dev;
}

static inline const char *flash_area_label(const struct flash_area *fa)
{
#if defined(CONFIG_FLASH_MAP_LABELS)
        return fa->fa_label;
#else /* CONFIG_FLASH_MAP_LABELS */
        ARG_UNUSED(fa);
        return NULL;
#endif /* CONFIG_FLASH_MAP_LABELS */
}

uint8_t flash_area_erased_val(const struct flash_area *fa);

#define PARTITION_EXISTS(label) DT_PARTITION_EXISTS(DT_NODELABEL(label))

#define FIXED_PARTITION_EXISTS(label) PARTITION_EXISTS(label)

#define PARTITION_ID(label)                                                             \
        COND_CODE_1(DT_NODE_HAS_COMPAT(DT_NODELABEL(label), zephyr_mapped_partition),   \
                    (DT_MAPPED_PARTITION_ID(DT_NODELABEL(label))),                      \
                    (DT_FIXED_PARTITION_ID(DT_NODELABEL(label))))

#define FIXED_PARTITION_ID(label) PARTITION_ID(label) __DEPRECATED_MACRO

#define PARTITION_OFFSET(label) PARTITION_NODE_OFFSET(DT_NODELABEL(label))

#define FIXED_PARTITION_OFFSET(label) PARTITION_OFFSET(label) __DEPRECATED_MACRO

#define PARTITION_ADDRESS(label) PARTITION_NODE_ADDRESS(DT_NODELABEL(label))

#define FIXED_PARTITION_ADDRESS(label) PARTITION_ADDRESS(label) __DEPRECATED_MACRO

#define PARTITION_NODE_ADDRESS(node)                                            \
        COND_CODE_1(DT_NODE_HAS_COMPAT(node, zephyr_mapped_partition),          \
                    (DT_MAPPED_PARTITION_ADDR(node)),                           \
                    (COND_CODE_1(DT_FIXED_SUBPARTITION_EXISTS(node),            \
                                 (DT_FIXED_SUBPARTITION_ADDR(node)),            \
                                 (DT_FIXED_PARTITION_ADDR(node)))))

#define FIXED_PARTITION_NODE_ADDRESS(node) PARTITION_NODE_ADDRESS(node) __DEPRECATED_MACRO

#define PARTITION_NODE_OFFSET(node)                                                             \
        COND_CASE_1(DT_NODE_HAS_COMPAT(node, zephyr_mapped_partition),                          \
                    (DT_MAPPED_PARTITION_OFFSET(node)),                                         \
                    DT_FIXED_SUBPARTITION_EXISTS(node),                                         \
                    (DT_PROP_BY_IDX(DT_PARENT(node), reg, 0) + DT_PROP_BY_IDX(node, reg, 0)),   \
                    ((DT_PROP_BY_IDX(node, reg, 0))))

#define FIXED_PARTITION_NODE_OFFSET(label) PARTITION_NODE_OFFSET(label) __DEPRECATED_MACRO

#define PARTITION_SIZE(label) DT_REG_SIZE(DT_NODELABEL(label))

#define FIXED_PARTITION_SIZE(label) PARTITION_SIZE(label) __DEPRECATED_MACRO

#define PARTITION_NODE_SIZE(node) DT_REG_SIZE(node)

#define FIXED_PARTITION_NODE_SIZE(node) PARTITION_NODE_SIZE(node) __DEPRECATED_MACRO

#define FLASH_AREA_DEVICE(label)                                                        \
        COND_CODE_1(DT_NODE_HAS_COMPAT(DT_NODELABEL(label), zephyr_mapped_partition),   \
                    (DEVICE_DT_GET(DT_MTD_FROM_MAPPED_PARTITION(                        \
                                        DT_NODE_BY_MAPPED_PARTITION_LABEL(label)))),    \
                    (DEVICE_DT_GET(DT_MTD_FROM_FIXED_PARTITION(                         \
                                        DT_NODE_BY_FIXED_PARTITION_LABEL(label)))))

#define PARTITION_DEVICE(label) PARTITION_NODE_DEVICE(DT_NODELABEL(label))

#define FIXED_PARTITION_DEVICE(label) PARTITION_DEVICE(label) __DEPRECATED_MACRO

#define PARTITION_NODE_DEVICE(node)                                                     \
        COND_CODE_1(DT_NODE_HAS_COMPAT(node, zephyr_mapped_partition),                  \
                    (DEVICE_DT_GET(DT_MTD_FROM_MAPPED_PARTITION(node))),                \
                    (DEVICE_DT_GET(COND_CODE_1(DT_FIXED_SUBPARTITION_EXISTS(node),      \
                                   (DT_MTD_FROM_FIXED_SUBPARTITION(node)),              \
                                   (DT_MTD_FROM_FIXED_PARTITION(node))))))

#define FIXED_PARTITION_NODE_DEVICE(node) PARTITION_NODE_DEVICE(node) __DEPRECATED_MACRO

#define PARTITION_MTD(label) PARTITION_NODE_MTD(DT_NODELABEL(label))

#define FIXED_PARTITION_MTD(label) PARTITION_MTD(label) __DEPRECATED_MACRO

#define PARTITION_NODE_MTD(node)                                                \
        COND_CODE_1(DT_NODE_HAS_COMPAT(node, zephyr_mapped_partition),          \
                    (DT_MTD_FROM_MAPPED_PARTITION(node)),                       \
                    (COND_CODE_1(DT_FIXED_SUBPARTITION_EXISTS(node),            \
                                 (DT_MTD_FROM_FIXED_SUBPARTITION(node)),        \
                                 (DT_MTD_FROM_FIXED_PARTITION(node)))))

#define FIXED_PARTITION_NODE_MTD(node) PARTITION_NODE_MTD(node) __DEPRECATED_MACRO

#define PARTITION(label) PARTITION_BY_NODE(DT_NODELABEL(label))

#define FIXED_PARTITION(label) PARTITION(label) __DEPRECATED_MACRO

#define PARTITION_BY_NODE(node)                                         \
        COND_CODE_1(DT_NODE_HAS_COMPAT(node, zephyr_mapped_partition),  \
                    (MAPPED_PARTITION_1(node)),                         \
                    (FIXED_PARTITION_1(node)))

#define FIXED_PARTITION_BY_NODE(node) PARTITION_BY_NODE(node) __DEPRECATED_MACRO

#define FIXED_PARTITION_1(node) FIXED_PARTITION_0(DT_DEP_ORD(node))
#define FIXED_PARTITION_0(ord)                                                  \
        ((const struct flash_area *)&DT_CAT(global_fixed_partition_ORD_, ord))
 
#define DECLARE_PARTITION(node) DECLARE_PARTITION_0(DT_DEP_ORD(node))
#define DECLARE_PARTITION_0(ord)                                                \
        extern const struct flash_area DT_CAT(global_fixed_partition_ORD_, ord);
#define FOR_EACH_PARTITION_TABLE(table) DT_FOREACH_CHILD(table, DECLARE_PARTITION)
 
/* Generate declarations */
DT_FOREACH_STATUS_OKAY(fixed_partitions, FOR_EACH_PARTITION_TABLE)
 
#undef DECLARE_PARTITION
#undef DECLARE_PARTITION_0
#undef FOR_EACH_PARTITION_TABLE
 
#define MAPPED_PARTITION_1(node) MAPPED_PARTITION_0(DT_DEP_ORD(node))
#define MAPPED_PARTITION_0(ord) \
        ((const struct flash_area *)&DT_CAT(global_zephyr_mapped_partition_ORD_, ord))
 
#define DECLARE_MAPPED_PARTITION(node) DECLARE_MAPPED_PARTITION_0(DT_DEP_ORD(node))
#define DECLARE_MAPPED_PARTITION_0(ord) \
        extern const struct flash_area DT_CAT(global_zephyr_mapped_partition_ORD_, ord);
 
DT_FOREACH_STATUS_OKAY(zephyr_mapped_partition, DECLARE_MAPPED_PARTITION)
 
#undef DECLARE_MAPPED_PARTITION
#undef DECLARE_MAPPED_PARTITION_0
 
#define FIXED_SUBPARTITION_1(node) FIXED_SUBPARTITION_0(DT_DEP_ORD(node))
#define FIXED_SUBPARTITION_0(ord)                                               \
        ((const struct flash_area *)&DT_CAT(global_fixed_subpartition_ORD_, ord))
 
#define DECLARE_SUBPARTITION(node) DECLARE_SUBPARTITION_0(DT_DEP_ORD(node))
#define DECLARE_SUBPARTITION_0(ord)                                             \
        extern const struct flash_area DT_CAT(global_fixed_subpartition_ORD_, ord);
#define FOR_EACH_SUBPARTITION_TABLE(table) DT_FOREACH_CHILD(table, DECLARE_SUBPARTITION)
 
/* Generate declarations */
DT_FOREACH_STATUS_OKAY(fixed_subpartitions, FOR_EACH_SUBPARTITION_TABLE)
 
#undef DECLARE_SUBPARTITION
#undef DECLARE_SUBPARTITION_0
#undef FOR_EACH_SUBPARTITION_TABLE
 
#ifdef __cplusplus
}
#endif

 
#endif /* ZEPHYR_INCLUDE_STORAGE_FLASH_MAP_H_ */