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>
 
#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 CONFIG_FLASH_MAP_LABELS
        const char *fa_label;
#endif
};

struct flash_sector {
        off_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);

void flash_area_close(const struct flash_area *fa);

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);

const struct device *flash_area_get_device(const struct flash_area *fa);
 
#if CONFIG_FLASH_MAP_LABELS
const char *flash_area_label(const struct flash_area *fa);
#endif

uint8_t flash_area_erased_val(const struct flash_area *fa);

#define FIXED_PARTITION_EXISTS(label) \
        UTIL_OR(DT_FIXED_PARTITION_EXISTS(DT_NODELABEL(label)), \
                DT_FIXED_SUBPARTITION_EXISTS(DT_NODELABEL(label)))

#define FIXED_PARTITION_ID(label) DT_FIXED_PARTITION_ID(DT_NODELABEL(label))

#define FIXED_PARTITION_OFFSET(label) DT_REG_ADDR(DT_NODELABEL(label))

#define FIXED_PARTITION_ADDRESS(label) \
        (COND_CODE_1(DT_FIXED_SUBPARTITION_EXISTS(DT_NODELABEL(label)), \
                (DT_FIXED_SUBPARTITION_ADDR(DT_NODELABEL(label))), \
                (DT_FIXED_PARTITION_ADDR(DT_NODELABEL(label)))))

#define FIXED_PARTITION_NODE_ADDRESS(node) \
        (COND_CODE_1(DT_FIXED_SUBPARTITION_EXISTS(node), \
                (DT_FIXED_SUBPARTITION_ADDR(node)), \
                (DT_FIXED_PARTITION_ADDR(node))))

#define FIXED_PARTITION_NODE_OFFSET(node) DT_REG_ADDR(node)

#define FIXED_PARTITION_SIZE(label) DT_REG_SIZE(DT_NODELABEL(label))

#define FIXED_PARTITION_NODE_SIZE(node) DT_REG_SIZE(node)

#define FLASH_AREA_DEVICE(label) \
        DEVICE_DT_GET(DT_MTD_FROM_FIXED_PARTITION(DT_NODE_BY_FIXED_PARTITION_LABEL(label)))

#define FIXED_PARTITION_DEVICE(label) \
        DEVICE_DT_GET(COND_CODE_1( \
                DT_FIXED_SUBPARTITION_EXISTS(DT_NODELABEL(label)), \
                        (DT_MTD_FROM_FIXED_SUBPARTITION(DT_NODELABEL(label))), \
                        (DT_MTD_FROM_FIXED_PARTITION(DT_NODELABEL(label)))))

#define FIXED_PARTITION_NODE_DEVICE(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(label)  FIXED_PARTITION_1(DT_NODELABEL(label))

#define FIXED_PARTITION_BY_NODE(node)   FIXED_PARTITION_1(node)

#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 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_ */