flash.h

Go to the documentation of this file.

/*
 * Copyright (c) 2017-2024 Nordic Semiconductor ASA
 * Copyright (c) 2016 Intel Corporation
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifndef ZEPHYR_INCLUDE_DRIVERS_FLASH_H_
#define ZEPHYR_INCLUDE_DRIVERS_FLASH_H_
 
#include <errno.h>
 
#include <zephyr/types.h>
#include <stddef.h>
#include <sys/types.h>
#include <zephyr/device.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
#if defined(CONFIG_FLASH_PAGE_LAYOUT)
struct flash_pages_layout {
        size_t pages_count; /* count of pages sequence of the same size */
        size_t pages_size;
};
#endif /* CONFIG_FLASH_PAGE_LAYOUT */
 
struct flash_parameters {
        const size_t write_block_size;
 
        /* User code should call flash_params_get_ functions on flash_parameters
         * to get capabilities, rather than accessing object contents directly.
         */
        struct {
                /* Device has no explicit erase, so it either erases on
                 * write or does not require it at all.
                 * This also includes devices that support erase but
                 * do not require it.
                 */
                bool no_explicit_erase: 1;
        } caps;
        uint8_t erase_value;
};
 
#define FLASH_ERASE_C_EXPLICIT          0x01
#define FLASH_ERASE_CAPS_UNSET          (int)-1
/* The values below are now reserved but not used */
#define FLASH_ERASE_C_SUPPORTED         0x02
#define FLASH_ERASE_C_VAL_BIT           0x04
#define FLASH_ERASE_UNIFORM_PAGE        0x08
 
 
/* @brief Parser for flash_parameters for retrieving erase capabilities
 *
 * The functions parses flash_parameters type object and returns combination
 * of erase capabilities of 0 if device does not have any.
 * Not that in some cases availability of erase may be dependent on driver
 * options, so even if by hardware design a device provides some erase
 * capabilities, the function may return 0 if these been disabled or not
 * implemented by driver.
 *
 * @param p             pointer to flash_parameters type object
 *
 * @return 0 or combination of FLASH_ERASE_C_ capabilities.
 */
static inline
int flash_params_get_erase_cap(const struct flash_parameters *p)
{
#if defined(CONFIG_FLASH_HAS_EXPLICIT_ERASE)
#if defined(CONFIG_FLASH_HAS_NO_EXPLICIT_ERASE)
        return (p->caps.no_explicit_erase) ? 0 : FLASH_ERASE_C_EXPLICIT;
#else
        ARG_UNUSED(p);
        return FLASH_ERASE_C_EXPLICIT;
#endif
#endif
        return 0;
}
 
typedef int (*flash_api_read)(const struct device *dev, off_t offset,
                              void *data,
                              size_t len);
typedef int (*flash_api_write)(const struct device *dev, off_t offset,
                               const void *data, size_t len);
 
typedef int (*flash_api_erase)(const struct device *dev, off_t offset,
                               size_t size);
 
typedef const struct flash_parameters* (*flash_api_get_parameters)(const struct device *dev);
 
#if defined(CONFIG_FLASH_PAGE_LAYOUT)
typedef void (*flash_api_pages_layout)(const struct device *dev,
                                       const struct flash_pages_layout **layout,
                                       size_t *layout_size);
#endif /* CONFIG_FLASH_PAGE_LAYOUT */
 
typedef int (*flash_api_sfdp_read)(const struct device *dev, off_t offset,
                                   void *data, size_t len);
typedef int (*flash_api_read_jedec_id)(const struct device *dev, uint8_t *id);
typedef int (*flash_api_ex_op)(const struct device *dev, uint16_t code,
                               const uintptr_t in, void *out);
 
__subsystem struct flash_driver_api {
        flash_api_read read;
        flash_api_write write;
        flash_api_erase erase;
        flash_api_get_parameters get_parameters;
#if defined(CONFIG_FLASH_PAGE_LAYOUT)
        flash_api_pages_layout page_layout;
#endif /* CONFIG_FLASH_PAGE_LAYOUT */
#if defined(CONFIG_FLASH_JESD216_API)
        flash_api_sfdp_read sfdp_read;
        flash_api_read_jedec_id read_jedec_id;
#endif /* CONFIG_FLASH_JESD216_API */
#if defined(CONFIG_FLASH_EX_OP_ENABLED)
        flash_api_ex_op ex_op;
#endif /* CONFIG_FLASH_EX_OP_ENABLED */
};
 
__syscall int flash_read(const struct device *dev, off_t offset, void *data,
                         size_t len);
 
static inline int z_impl_flash_read(const struct device *dev, off_t offset,
                                    void *data,
                                    size_t len)
{
        const struct flash_driver_api *api =
                (const struct flash_driver_api *)dev->api;
 
        return api->read(dev, offset, data, len);
}
 
__syscall int flash_write(const struct device *dev, off_t offset,
                          const void *data,
                          size_t len);
 
static inline int z_impl_flash_write(const struct device *dev, off_t offset,
                                     const void *data, size_t len)
{
        const struct flash_driver_api *api =
                (const struct flash_driver_api *)dev->api;
        int rc;
 
        rc = api->write(dev, offset, data, len);
 
        return rc;
}
 
__syscall int flash_erase(const struct device *dev, off_t offset, size_t size);
 
static inline int z_impl_flash_erase(const struct device *dev, off_t offset,
                                     size_t size)
{
        int rc = -ENOSYS;
 
        const struct flash_driver_api *api =
                (const struct flash_driver_api *)dev->api;
 
        if (api->erase != NULL) {
                rc = api->erase(dev, offset, size);
        }
 
        return rc;
}
 
__syscall int flash_fill(const struct device *dev, uint8_t val, off_t offset, size_t size);
 
__syscall int flash_flatten(const struct device *dev, off_t offset, size_t size);
 
struct flash_pages_info {
        off_t start_offset; /* offset from the base of flash address */
        size_t size;
        uint32_t index;
};
 
#if defined(CONFIG_FLASH_PAGE_LAYOUT)
__syscall int flash_get_page_info_by_offs(const struct device *dev,
                                          off_t offset,
                                          struct flash_pages_info *info);
 
__syscall int flash_get_page_info_by_idx(const struct device *dev,
                                         uint32_t page_index,
                                         struct flash_pages_info *info);
 
__syscall size_t flash_get_page_count(const struct device *dev);
 
typedef bool (*flash_page_cb)(const struct flash_pages_info *info, void *data);
 
void flash_page_foreach(const struct device *dev, flash_page_cb cb,
                        void *data);
#endif /* CONFIG_FLASH_PAGE_LAYOUT */
 
#if defined(CONFIG_FLASH_JESD216_API)
__syscall int flash_sfdp_read(const struct device *dev, off_t offset,
                              void *data, size_t len);
 
static inline int z_impl_flash_sfdp_read(const struct device *dev,
                                         off_t offset,
                                         void *data, size_t len)
{
        int rv = -ENOTSUP;
        const struct flash_driver_api *api =
                (const struct flash_driver_api *)dev->api;
 
        if (api->sfdp_read != NULL) {
                rv = api->sfdp_read(dev, offset, data, len);
        }
        return rv;
}
 
__syscall int flash_read_jedec_id(const struct device *dev, uint8_t *id);
 
static inline int z_impl_flash_read_jedec_id(const struct device *dev,
                                             uint8_t *id)
{
        int rv = -ENOTSUP;
        const struct flash_driver_api *api =
                (const struct flash_driver_api *)dev->api;
 
        if (api->read_jedec_id != NULL) {
                rv = api->read_jedec_id(dev, id);
        }
        return rv;
}
#endif /* CONFIG_FLASH_JESD216_API */
 
__syscall size_t flash_get_write_block_size(const struct device *dev);
 
static inline size_t z_impl_flash_get_write_block_size(const struct device *dev)
{
        const struct flash_driver_api *api =
                (const struct flash_driver_api *)dev->api;
 
        return api->get_parameters(dev)->write_block_size;
}
 
 
__syscall const struct flash_parameters *flash_get_parameters(const struct device *dev);
 
static inline const struct flash_parameters *z_impl_flash_get_parameters(const struct device *dev)
{
        const struct flash_driver_api *api =
                (const struct flash_driver_api *)dev->api;
 
        return api->get_parameters(dev);
}
 
__syscall int flash_ex_op(const struct device *dev, uint16_t code,
                          const uintptr_t in, void *out);
 
/*
 *  Extended operation interface provides flexible way for supporting flash
 *  controller features. Code space is divided equally into Zephyr codes
 *  (MSb == 0) and vendor codes (MSb == 1). This way we can easily add extended
 *  operations to the drivers without cluttering the API or problems with API
 *  incompatibility. Extended operation can be promoted from vendor codes to
 *  Zephyr codes if the feature is available in most flash controllers and
 *  can be represented in the same way.
 *
 *  It's not forbidden to have operation in Zephyr codes and vendor codes for
 *  the same functionality. In this case, vendor operation could provide more
 *  specific access when abstraction in Zephyr counterpart is insufficient.
 */
#define FLASH_EX_OP_VENDOR_BASE 0x8000
#define FLASH_EX_OP_IS_VENDOR(c) ((c) & FLASH_EX_OP_VENDOR_BASE)
 
enum flash_ex_op_types {
        /*
         * Reset flash device.
         */
        FLASH_EX_OP_RESET = 0,
};
 
static inline int z_impl_flash_ex_op(const struct device *dev, uint16_t code,
                                     const uintptr_t in, void *out)
{
#if defined(CONFIG_FLASH_EX_OP_ENABLED)
        const struct flash_driver_api *api =
                (const struct flash_driver_api *)dev->api;
 
        if (api->ex_op == NULL) {
                return -ENOTSUP;
        }
 
        return api->ex_op(dev, code, in, out);
#else
        ARG_UNUSED(dev);
        ARG_UNUSED(code);
        ARG_UNUSED(in);
        ARG_UNUSED(out);
 
        return -ENOSYS;
#endif /* CONFIG_FLASH_EX_OP_ENABLED */
}
 
#ifdef __cplusplus
}
#endif
 
#include <zephyr/syscalls/flash.h>
 
#endif /* ZEPHYR_INCLUDE_DRIVERS_FLASH_H_ */