Named MMIO region macros

For drivers which need to manage multiple MMIO regions, which will be referenced by name. More...

Macros
#define	DEVICE_MMIO_NAMED_RAM(name)   mm_reg_t name
	Declare storage for MMIO data within a device's dev_data struct.
#define	DEVICE_MMIO_NAMED_RAM_PTR(dev, name)    (&(DEV_DATA(dev)->name))
	Return a pointer to the RAM storage for a device's named MMIO address.
#define	DEVICE_MMIO_NAMED_ROM(name)   struct z_device_mmio_rom name
	Declare storage for MMIO data within a device's config struct.
#define	DEVICE_MMIO_NAMED_ROM_PTR(dev, name)   (&(DEV_CFG(dev)->name))
	Return a pointer to the ROM-based storage area for a device's MMIO information.
#define	DEVICE_MMIO_NAMED_ROM_INIT(name, node_id)    .name = Z_DEVICE_MMIO_ROM_INITIALIZER(node_id)
	Initialize a named DEVICE_MMIO_NAMED_ROM member.
#define	DEVICE_MMIO_NAMED_ROM_INIT_BY_NAME(name, node_id)    .name = Z_DEVICE_MMIO_NAMED_ROM_INITIALIZER(name, node_id)
	Initialize a named DEVICE_MMIO_NAMED_ROM member using a named DT reg property.
#define	DEVICE_MMIO_NAMED_MAP(dev, name, flags)
	Set up memory for a named MMIO region.
#define	DEVICE_MMIO_NAMED_GET(dev, name)    (*DEVICE_MMIO_NAMED_RAM_PTR((dev), name))
	Obtain a named MMIO address for a device.

Detailed Description

For drivers which need to manage multiple MMIO regions, which will be referenced by name.

Macro Definition Documentation

DEVICE_MMIO_NAMED_GET

#define DEVICE_MMIO_NAMED_GET	(		dev,
			name
	)		(*DEVICE_MMIO_NAMED_RAM_PTR((dev), name))

#include <zephyr/sys/device_mmio.h>

Obtain a named MMIO address for a device.

This macro returns the MMIO base address for a named region from the appropriate place within the device object's linked data structures.

This is for drivers which have multiple MMIO regions.

This macro requires that the macros DEV_DATA and DEV_CFG are locally defined and return properly typed pointers to the particular dev_data and config structs for this driver.

See also

DEVICE_MMIO_GET

Parameters

dev	Device object
name	Member name for MMIO information, as declared with DEVICE_MMIO_NAMED_RAM/DEVICE_MMIO_NAMED_ROM

Returns

mm_reg_t linear address of the MMIO region

DEVICE_MMIO_NAMED_MAP

#define DEVICE_MMIO_NAMED_MAP	(		dev,
			name,
			flags
	)

#include <zephyr/sys/device_mmio.h>

Value:

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

Set up memory for a named MMIO region.

This performs the necessary PCI probing and/or MMU virtual memory mapping such that DEVICE_MMIO_GET(name) returns a suitable linear memory address for the MMIO region.

If such operations are not required by the target hardware, this expands to nothing.

This should be called from the driver's init function, once for each MMIO region that needs to be mapped.

This macro requires that the macros DEV_DATA and DEV_CFG are locally defined and return properly typed pointers to the particular dev_data and config structs for this driver.

The flags argument is currently used for caching mode, which should be one of the DEVICE_CACHE_* macros. Unused bits are reserved for future expansion.

Parameters

dev	Device object
name	Member name for MMIO information, as declared with DEVICE_MMIO_NAMED_RAM/DEVICE_MMIO_NAMED_ROM
flags	One of the DEVICE_CACHE_* caching modes

DEVICE_MMIO_NAMED_RAM

#define DEVICE_MMIO_NAMED_RAM

(

name

)

mm_reg_t name

#include <zephyr/sys/device_mmio.h>

Declare storage for MMIO data within a device's dev_data struct.

This gets accessed by the DEVICE_MMIO_NAMED_MAP() and DEVICE_MMIO_NAMED_GET() macros.

Depending on configuration, no memory may be reserved at all. Multiple named regions may be declared.

There must be a corresponding DEVICE_MMIO_ROM in config if the physical address is known at build time, but may be omitted if not (such as with PCIe.

Example for a driver named "foo":

struct foo_driver_data {
     int blarg;
     DEVICE_MMIO_NAMED_RAM(corge);
     DEVICE_MMIO_NAMED_RAM(grault);
     int wibble;
     ...
}

No build-time initialization of this memory is necessary; it will be set up in the init function by DEVICE_MMIO_NAMED_MAP().

Parameters

name	Member name to use to store within dev_data.

DEVICE_MMIO_NAMED_RAM_PTR

#define DEVICE_MMIO_NAMED_RAM_PTR	(		dev,
			name
	)		(&(DEV_DATA(dev)->name))

#include <zephyr/sys/device_mmio.h>

Return a pointer to the RAM storage for a device's named MMIO address.

This macro requires that the macro DEV_DATA is locally defined and returns a properly typed pointer to the particular dev_data struct for this driver.

Parameters

dev	device instance object
name	Member name within dev_data

Return values

mm_reg_t

pointer to storage location

DEVICE_MMIO_NAMED_ROM

#define DEVICE_MMIO_NAMED_ROM

(

name

)

struct z_device_mmio_rom name

#include <zephyr/sys/device_mmio.h>

Declare storage for MMIO data within a device's config struct.

This gets accessed by DEVICE_MMIO_NAMED_MAP() and DEVICE_MMIO_NAMED_GET() macros.

What gets stored here varies considerably by configuration. Multiple named regions may be declared. There must be corresponding entries in the dev_data struct.

This storage is not used if the device is PCIe and may be omitted.

If used, this must be initialized at build time with information from DTS using DEVICE_MMIO_NAMED_ROM_INIT()

A pointer to this memory may be obtained with DEVICE_MMIO_NAMED_ROM_PTR().

Example for a driver named "foo":

struct foo_config {
     int bar;
     DEVICE_MMIO_NAMED_ROM(corge);
     DEVICE_MMIO_NAMED_ROM(grault);
     int baz;
     ...
}

See also

DEVICE_MMIO_NAMED_ROM_INIT()

Parameters

name	Member name to store within config

DEVICE_MMIO_NAMED_ROM_INIT

#define DEVICE_MMIO_NAMED_ROM_INIT	(		name,
			node_id
	)		.name = Z_DEVICE_MMIO_ROM_INITIALIZER(node_id)

#include <zephyr/sys/device_mmio.h>

Initialize a named DEVICE_MMIO_NAMED_ROM member.

Initialize MMIO-related information within a specific instance of a device config struct, using information from DTS.

Example for an instance of a driver belonging to the "foo" subsystem that will have two regions named 'corge' and 'grault':

struct foo_config my_config = {
     bar = 7;
     DEVICE_MMIO_NAMED_ROM_INIT(corge, DT_DRV_INST(...));
     DEVICE_MMIO_NAMED_ROM_INIT(grault, DT_DRV_INST(...));
     baz = 2;
     ...
}

See also

DEVICE_MMIO_NAMED_ROM()

Parameters

name	Member name within config for the MMIO region
node_id	DTS node identifier

DEVICE_MMIO_NAMED_ROM_INIT_BY_NAME

#define DEVICE_MMIO_NAMED_ROM_INIT_BY_NAME	(		name,
			node_id
	)		.name = Z_DEVICE_MMIO_NAMED_ROM_INITIALIZER(name, node_id)

#include <zephyr/sys/device_mmio.h>

Initialize a named DEVICE_MMIO_NAMED_ROM member using a named DT reg property.

Same as DEVICE_MMIO_NAMED_ROM_INIT but the size and address are taken from a named DT reg property.

Example for an instance of a driver belonging to the "foo" subsystem that will have two DT-defined regions named 'chip' and 'dale':

foo@E5000000 {
     reg = <0xE5000000 0x1000>, <0xE6000000 0x1000>;
     reg-names = "chip", "dale";
     ...
};

struct foo_config my_config = {
     bar = 7;
     DEVICE_MMIO_NAMED_ROM_INIT_BY_NAME(chip, DT_DRV_INST(...));
     DEVICE_MMIO_NAMED_ROM_INIT_BY_NAME(dale, DT_DRV_INST(...));
     baz = 2;
     ...
}

See also

DEVICE_MMIO_NAMED_ROM_INIT()

Parameters

name	Member name within config for the MMIO region and name of the reg property in the DT
node_id	DTS node identifier

DEVICE_MMIO_NAMED_ROM_PTR

#define DEVICE_MMIO_NAMED_ROM_PTR	(		dev,
			name
	)		(&(DEV_CFG(dev)->name))

#include <zephyr/sys/device_mmio.h>

Return a pointer to the ROM-based storage area for a device's MMIO information.

This macro requires that the macro DEV_CFG is locally defined and returns a properly typed pointer to the particular config struct for this driver.

Parameters

dev	device instance object
name	Member name within config

Return values

struct

device_mmio_rom * pointer to storage location