device_mmio.h

Go to the documentation of this file.

/*
 * Copyright (c) 2020 Intel Corporation.
 *
 * SPDX-License-Identifier: Apache-2.0
 *
 * Definitions and helper macros for managing driver memory-mapped
 * input/output (MMIO) regions appropriately in either RAM or ROM.
 *
 * In most cases drivers will just want to include device.h, but
 * including this separately may be needed for arch-level driver code
 * which uses the DEVICE_MMIO_TOPLEVEL variants and including the
 * main device.h would introduce header dependency loops due to that
 * header's reliance on kernel.h.
 */
#ifndef ZEPHYR_INCLUDE_SYS_DEVICE_MMIO_H
#define ZEPHYR_INCLUDE_SYS_DEVICE_MMIO_H
 
#include <zephyr/toolchain.h>
#include <zephyr/linker/sections.h>
 
/* Storing MMIO addresses in RAM is a system-wide decision based on
 * configuration. This is just used to simplify some other definitions.
 *
 * If we have an MMU enabled, all physical MMIO regions must be mapped into
 * the kernel's virtual address space at runtime, this is a hard requirement.
 *
 * If we have PCIE enabled, this does mean that non-PCIE drivers may waste
 * a bit of RAM, but systems with PCI express are not RAM constrained.
 */
#if defined(CONFIG_MMU) || defined(CONFIG_PCIE) || defined(CONFIG_EXTERNAL_ADDRESS_TRANSLATION)
#define DEVICE_MMIO_IS_IN_RAM
#endif
 
#if defined(CONFIG_EXTERNAL_ADDRESS_TRANSLATION)
#include <zephyr/drivers/mm/system_mm.h>
#endif
 
#ifndef _ASMLANGUAGE
#include <stdint.h>
#include <stddef.h>
#include <zephyr/sys/mem_manage.h>
#include <zephyr/sys/sys_io.h>
 
#ifdef DEVICE_MMIO_IS_IN_RAM
/* Store the physical address and size from DTS, we'll memory
 * map into the virtual address space at runtime. This is not applicable
 * to PCIe devices, which must query the bus for BAR information.
 */
struct z_device_mmio_rom {
        uintptr_t phys_addr;
 
        size_t size;
};
 
#define Z_DEVICE_MMIO_ROM_INITIALIZER(node_id) \
        { \
                .phys_addr = DT_REG_ADDR(node_id), \
                .size = DT_REG_SIZE(node_id) \
        }
 
#define Z_DEVICE_MMIO_NAMED_ROM_INITIALIZER(name, node_id) \
        { \
                .phys_addr = DT_REG_ADDR_BY_NAME(node_id, name), \
                .size = DT_REG_SIZE_BY_NAME(node_id, name) \
        }
 
__boot_func
static inline void device_map(mm_reg_t *virt_addr, uintptr_t phys_addr,
                              size_t size, uint32_t flags)
{
#ifdef CONFIG_MMU
        /* Pass along flags and add that we want supervisor mode
         * read-write access.
         */
        z_phys_map((uint8_t **)virt_addr, phys_addr, size,
                   flags | K_MEM_PERM_RW);
#else
        ARG_UNUSED(size);
        ARG_UNUSED(flags);
#ifdef CONFIG_EXTERNAL_ADDRESS_TRANSLATION
        sys_mm_drv_page_phys_get((void *) phys_addr, virt_addr);
#else
        *virt_addr = phys_addr;
#endif /* CONFIG_EXTERNAL_ADDRESS_TRANSLATION */
#endif /* CONFIG_MMU */
}
#else
/* No MMU or PCIe. Just store the address from DTS and treat as a linear
 * address
 */
struct z_device_mmio_rom {
        mm_reg_t addr;
};
 
#define Z_DEVICE_MMIO_ROM_INITIALIZER(node_id) \
        { \
                .addr = (mm_reg_t)DT_REG_ADDR_U64(node_id) \
        }
 
#define Z_DEVICE_MMIO_NAMED_ROM_INITIALIZER(name, node_id) \
        { \
                .addr = (mm_reg_t)DT_REG_ADDR_BY_NAME_U64(node_id, name) \
        }
 
#endif /* DEVICE_MMIO_IS_IN_RAM */
#endif /* !_ASMLANGUAGE */
#ifdef DEVICE_MMIO_IS_IN_RAM
#define DEVICE_MMIO_RAM                 mm_reg_t _mmio
#else
#define DEVICE_MMIO_RAM
#endif
 
#ifdef DEVICE_MMIO_IS_IN_RAM
#define DEVICE_MMIO_RAM_PTR(device)     (mm_reg_t *)((device)->data)
#endif /* DEVICE_MMIO_IS_IN_RAM */
 
#define DEVICE_MMIO_ROM         struct z_device_mmio_rom _mmio
 
#define DEVICE_MMIO_ROM_PTR(dev) \
        ((struct z_device_mmio_rom *)((dev)->config))
 
#define DEVICE_MMIO_ROM_INIT(node_id) \
        ._mmio = Z_DEVICE_MMIO_ROM_INITIALIZER(node_id)
 
#ifdef DEVICE_MMIO_IS_IN_RAM
#define DEVICE_MMIO_MAP(dev, flags) \
        device_map(DEVICE_MMIO_RAM_PTR(dev), \
                   DEVICE_MMIO_ROM_PTR(dev)->phys_addr, \
                   DEVICE_MMIO_ROM_PTR(dev)->size, \
                   (flags))
#else
#define DEVICE_MMIO_MAP(dev, flags) do { } while (false)
#endif
 
#ifdef DEVICE_MMIO_IS_IN_RAM
#define DEVICE_MMIO_GET(dev)    (*DEVICE_MMIO_RAM_PTR(dev))
#else
#define DEVICE_MMIO_GET(dev)    (DEVICE_MMIO_ROM_PTR(dev)->addr)
#endif
#ifdef DEVICE_MMIO_IS_IN_RAM
#define DEVICE_MMIO_NAMED_RAM(name)     mm_reg_t name
#else
#define DEVICE_MMIO_NAMED_RAM(name)
#endif /* DEVICE_MMIO_IS_IN_RAM */
 
#ifdef DEVICE_MMIO_IS_IN_RAM
#define DEVICE_MMIO_NAMED_RAM_PTR(dev, name) \
                (&(DEV_DATA(dev)->name))
#endif /* DEVICE_MMIO_IS_IN_RAM */
 
#define DEVICE_MMIO_NAMED_ROM(name) struct z_device_mmio_rom name
 
#define DEVICE_MMIO_NAMED_ROM_PTR(dev, name) (&(DEV_CFG(dev)->name))
 
#define DEVICE_MMIO_NAMED_ROM_INIT(name, node_id) \
        .name = Z_DEVICE_MMIO_ROM_INITIALIZER(node_id)
 
#define DEVICE_MMIO_NAMED_ROM_INIT_BY_NAME(name, node_id) \
        .name = Z_DEVICE_MMIO_NAMED_ROM_INITIALIZER(name, node_id)
 
#ifdef DEVICE_MMIO_IS_IN_RAM
#define DEVICE_MMIO_NAMED_MAP(dev, name, flags) \
        device_map(DEVICE_MMIO_NAMED_RAM_PTR((dev), name), \
                   (DEVICE_MMIO_NAMED_ROM_PTR((dev), name)->phys_addr), \
                   (DEVICE_MMIO_NAMED_ROM_PTR((dev), name)->size), \
                   (flags))
#else
#define DEVICE_MMIO_NAMED_MAP(dev, name, flags) do { } while (false)
#endif
 
#ifdef DEVICE_MMIO_IS_IN_RAM
#define DEVICE_MMIO_NAMED_GET(dev, name) \
                (*DEVICE_MMIO_NAMED_RAM_PTR((dev), name))
#else
#define DEVICE_MMIO_NAMED_GET(dev, name) \
                ((DEVICE_MMIO_NAMED_ROM_PTR((dev), name))->addr)
#endif /* DEVICE_MMIO_IS_IN_RAM */
 
 #define Z_TOPLEVEL_ROM_NAME(name) _CONCAT(z_mmio_rom__, name)
 #define Z_TOPLEVEL_RAM_NAME(name) _CONCAT(z_mmio_ram__, name)
 
#ifdef DEVICE_MMIO_IS_IN_RAM
#define DEVICE_MMIO_TOPLEVEL(name, node_id) \
        __pinned_bss \
        mm_reg_t Z_TOPLEVEL_RAM_NAME(name); \
        __pinned_rodata \
        const struct z_device_mmio_rom Z_TOPLEVEL_ROM_NAME(name) = \
                Z_DEVICE_MMIO_ROM_INITIALIZER(node_id)
#else
#define DEVICE_MMIO_TOPLEVEL(name, node_id) \
        __pinned_rodata \
        const struct z_device_mmio_rom Z_TOPLEVEL_ROM_NAME(name) = \
                Z_DEVICE_MMIO_ROM_INITIALIZER(node_id)
#endif /* DEVICE_MMIO_IS_IN_RAM */
 
#ifdef DEVICE_MMIO_IS_IN_RAM
#define DEVICE_MMIO_TOPLEVEL_DECLARE(name) \
        extern mm_reg_t Z_TOPLEVEL_RAM_NAME(name); \
        extern const struct z_device_mmio_rom Z_TOPLEVEL_ROM_NAME(name)
#else
#define DEVICE_MMIO_TOPLEVEL_DECLARE(name) \
        extern const struct z_device_mmio_rom Z_TOPLEVEL_ROM_NAME(name)
#endif /* DEVICE_MMIO_IS_IN_RAM */
 
#ifdef DEVICE_MMIO_IS_IN_RAM
#define DEVICE_MMIO_TOPLEVEL_STATIC(name, node_id) \
        __pinned_bss \
        static mm_reg_t Z_TOPLEVEL_RAM_NAME(name); \
        __pinned_rodata \
        static const struct z_device_mmio_rom Z_TOPLEVEL_ROM_NAME(name) = \
                Z_DEVICE_MMIO_ROM_INITIALIZER(node_id)
#else
#define DEVICE_MMIO_TOPLEVEL_STATIC(name, node_id) \
        __pinned_rodata \
        static const struct z_device_mmio_rom Z_TOPLEVEL_ROM_NAME(name) = \
                Z_DEVICE_MMIO_ROM_INITIALIZER(node_id)
#endif /* DEVICE_MMIO_IS_IN_RAM */
 
#ifdef DEVICE_MMIO_IS_IN_RAM
#define DEVICE_MMIO_TOPLEVEL_RAM_PTR(name) &Z_TOPLEVEL_RAM_NAME(name)
#endif /* DEVICE_MMIO_IS_IN_RAM */
 
#define DEVICE_MMIO_TOPLEVEL_ROM_PTR(name) &Z_TOPLEVEL_ROM_NAME(name)
 
#ifdef DEVICE_MMIO_IS_IN_RAM
#define DEVICE_MMIO_TOPLEVEL_MAP(name, flags) \
        device_map(&Z_TOPLEVEL_RAM_NAME(name), \
                   Z_TOPLEVEL_ROM_NAME(name).phys_addr, \
                   Z_TOPLEVEL_ROM_NAME(name).size, flags)
#else
#define DEVICE_MMIO_TOPLEVEL_MAP(name, flags) do { } while (false)
#endif
 
#ifdef DEVICE_MMIO_IS_IN_RAM
#define DEVICE_MMIO_TOPLEVEL_GET(name)  \
                ((mm_reg_t)Z_TOPLEVEL_RAM_NAME(name))
#else
#define DEVICE_MMIO_TOPLEVEL_GET(name)  \
                ((mm_reg_t)Z_TOPLEVEL_ROM_NAME(name).addr)
#endif
#endif /* ZEPHYR_INCLUDE_SYS_DEVICE_MMIO_H */