(ae68723)

Memory-mapped IO functions, for volatile access. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "sw/device/lib/base/bitfield.h"
#include "sw/device/lib/base/macros.h"

Go to the source code of this file.

Data Structures
struct	mmio_region
	"Instrumented" mmio_region_t. More...

Macros
#define	MMIO_DEPRECATED
	2020-06: We're transitioning to a more efficient manner of using our MMIO APIs, where the DIFs explicitly read, then modify, then write. More...

Typedefs
typedef struct mmio_region	mmio_region_t
	"Instrumented" mmio_region_t. More...

Functions
OT_WARN_UNUSED_RESULT mmio_region_t	mmio_region_from_addr (uintptr_t address)
	Stubbed-out read/write operations for overriding by a testing library.

OT_WARN_UNUSED_RESULT uint8_t	mmio_region_read8 (mmio_region_t base, ptrdiff_t offset)

OT_WARN_UNUSED_RESULT uint32_t	mmio_region_read32 (mmio_region_t base, ptrdiff_t offset)

void	mmio_region_write8 (mmio_region_t base, ptrdiff_t offset, uint8_t value)

void	mmio_region_write32 (mmio_region_t base, ptrdiff_t offset, uint32_t value)

void	mmio_region_write8_shadowed (mmio_region_t base, ptrdiff_t offset, uint8_t value)

void	mmio_region_write32_shadowed (mmio_region_t base, ptrdiff_t offset, uint32_t value)

OT_WARN_UNUSED_RESULT MMIO_DEPRECATED uint32_t	mmio_region_read_mask32 (mmio_region_t base, ptrdiff_t offset, uint32_t mask, uint32_t mask_index)
	Reads the bits in `mask` from the MMIO region `base` at the given offset. More...

OT_WARN_UNUSED_RESULT MMIO_DEPRECATED bool	mmio_region_get_bit32 (mmio_region_t base, ptrdiff_t offset, uint32_t bit_index)
	Checks whether the `bit_index`th bit is set in the MMIO region `base` at the given offset. More...

MMIO_DEPRECATED void	mmio_region_nonatomic_clear_mask32 (mmio_region_t base, ptrdiff_t offset, uint32_t mask, uint32_t mask_index)
	Clears the bits in `mask` from the MMIO region `base` at the given offset. More...

MMIO_DEPRECATED void	mmio_region_nonatomic_set_mask32 (mmio_region_t base, ptrdiff_t offset, uint32_t mask, uint32_t mask_index)
	Sets the bits in `mask` from the MMIO region `base` at the given offset. More...

MMIO_DEPRECATED void	mmio_region_write_only_set_mask32 (mmio_region_t base, ptrdiff_t offset, uint32_t mask, uint32_t mask_index)
	Sets the bits in `mask` from the MMIO region `base` at the given offset. More...

MMIO_DEPRECATED void	mmio_region_nonatomic_set_field32 (mmio_region_t base, ptrdiff_t offset, bitfield_field32_t field, uint32_t value)
	Sets the `field` from the MMIO region `base` at the given `offset`. More...

MMIO_DEPRECATED void	mmio_region_write_only_set_field32 (mmio_region_t base, ptrdiff_t offset, bitfield_field32_t field, uint32_t value)
	Sets the `field` from the MMIO region `base` at the given `offset`. More...

MMIO_DEPRECATED void	mmio_region_nonatomic_clear_bit32 (mmio_region_t base, ptrdiff_t offset, uint32_t bit_index)
	Clears the `bit_index`th bit in the MMIO region `base` at the given offset. More...

MMIO_DEPRECATED void	mmio_region_nonatomic_set_bit32 (mmio_region_t base, ptrdiff_t offset, uint32_t bit_index)
	Sets the `bit_index`th bit in the MMIO region `base` at the given offset. More...

MMIO_DEPRECATED void	mmio_region_write_only_set_bit32 (mmio_region_t base, ptrdiff_t offset, uint32_t bit_index)
	Sets the `bit_index`th bit in the MMIO region `base` at the given offset. More...

void	mmio_region_memcpy_from_mmio32 (mmio_region_t base, uint32_t offset, void *dest, size_t len)
	Copies a block of memory from MMIO to main memory while ensuring that MMIO accesses are both word-sized and word-aligned. More...

void	mmio_region_memcpy_to_mmio32 (mmio_region_t base, uint32_t offset, const void *src, size_t len)
	Copies a block of memory from main memory to MMIO while ensuring that MMIO accesses are both word-sized and word-aligned. More...

Detailed Description

Memory-mapped IO functions, for volatile access.

Memory-mapped IO functions, which either map to volatile accesses, or can be replaced with instrumentation calls at compile time, for use with tests.

Compiling translation units that pull in this header with -DMOCK_MMIO will disable the definitions of mmio_region_read and mmio_region_write. These symbols can then be defined by a test harness to allow for instrumentation of MMIO accesses.

Definition in file mmio.h.

Data Structure Documentation

◆ mmio_region

struct mmio_region

"Instrumented" mmio_region_t.

Instead of containing a volatile pointer, mmio_region_t becomes a void * when -DMOCK_MMIO is enabled. This makes it incompatible with the non-mock version of mmio_region_t, which prevents users from being able to access the pointer inside.

Definition at line 180 of file mmio.h.

Data Fields
void *	mock

Macro Definition Documentation

◆ MMIO_DEPRECATED

#define MMIO_DEPRECATED

2020-06: We're transitioning to a more efficient manner of using our MMIO APIs, where the DIFs explicitly read, then modify, then write.

All the *_nonatomic_* functions in this DIF are deprecated and will be removed eventually, leaving only the read<N>, write<N>, and memcpy functions.

For the moment, we are not adding __attribute__((deprecated(reason))) using this macro, because most code still uses the old version, but at some point we will add that expansion. This should be seen as a note to humans, not computers (yet).

Definition at line 43 of file mmio.h.

Typedef Documentation

◆ mmio_region_t

typedef struct mmio_region mmio_region_t

"Instrumented" mmio_region_t.

Instead of containing a volatile pointer, mmio_region_t becomes a void * when -DMOCK_MMIO is enabled. This makes it incompatible with the non-mock version of mmio_region_t, which prevents users from being able to access the pointer inside.

Function Documentation

◆ mmio_region_get_bit32()

OT_WARN_UNUSED_RESULT MMIO_DEPRECATED bool mmio_region_get_bit32	(	mmio_region_t	base,
		ptrdiff_t	offset,
		uint32_t	bit_index
	)

inline

Checks whether the bit_indexth bit is set in the MMIO region base at the given offset.

This function has the same guarantees as mmio_region_read32() and mmio_region_write32().

Parameters

base	the region to mask.
offset	the offset to apply the mask at.
bit_index	the bit to check.

Returns: true if the bit is set, false otherwise

Definition at line 237 of file mmio.h.

◆ mmio_region_memcpy_from_mmio32()

void mmio_region_memcpy_from_mmio32	(	mmio_region_t	base,
		uint32_t	offset,
		void *	dest,
		size_t	len
	)

Copies a block of memory from MMIO to main memory while ensuring that MMIO accesses are both word-sized and word-aligned.

This function may perform up to len/4 + 2 volatile reads to handle unaligned accesses.

Parameters

base	the MMIO region to read from.
offset	the offset to start reading from, in bytes.
dest	the main memory location to start writing to.
len	number of bytes to copy.

Definition at line 102 of file mmio.c.

◆ mmio_region_memcpy_to_mmio32()

void mmio_region_memcpy_to_mmio32	(	mmio_region_t	base,
		uint32_t	offset,
		const void *	src,
		size_t	len
	)

Copies a block of memory from main memory to MMIO while ensuring that MMIO accesses are both word-sized and word-aligned.

Unaligned MMIO blocks are handled by performing a read-modify-write for the boundary words.

Parameters

base	the MMIO region to write to.
offset	the offset to start writing to, in bytes.
src	the main memory location to start reading from.
len	number of bytes to copy.

Definition at line 107 of file mmio.c.

◆ mmio_region_nonatomic_clear_bit32()

MMIO_DEPRECATED void mmio_region_nonatomic_clear_bit32	(	mmio_region_t	base,
		ptrdiff_t	offset,
		uint32_t	bit_index
	)

inline

Clears the bit_indexth bit in the MMIO region base at the given offset.

This function has the same guarantees as mmio_region_nonatomic_clear_mask().

Parameters

base	the region to mask.
offset	the offset to apply the mask at.
bit_index	the bit to clear.

Definition at line 364 of file mmio.h.

◆ mmio_region_nonatomic_clear_mask32()

MMIO_DEPRECATED void mmio_region_nonatomic_clear_mask32	(	mmio_region_t	base,
		ptrdiff_t	offset,
		uint32_t	mask,
		uint32_t	mask_index
	)

inline

Clears the bits in mask from the MMIO region base at the given offset.

This function performs a non-atomic read-write-modify operation on a MMIO region.

Parameters

base	the region to mask.
offset	the offset to apply the mask at, in bytes.
mask	the mask to clear from the selected register.
mask_index	mask position within the selected register.

Definition at line 254 of file mmio.h.

◆ mmio_region_nonatomic_set_bit32()

MMIO_DEPRECATED void mmio_region_nonatomic_set_bit32	(	mmio_region_t	base,
		ptrdiff_t	offset,
		uint32_t	bit_index
	)

inline

Sets the bit_indexth bit in the MMIO region base at the given offset.

This function has the same guarantees as mmio_region_nonatomic_set_mask().

Parameters

base	the region to mask.
offset	the offset to apply the mask at.
bit_index	the bit to set.

Definition at line 382 of file mmio.h.

◆ mmio_region_nonatomic_set_field32()

MMIO_DEPRECATED void mmio_region_nonatomic_set_field32	(	mmio_region_t	base,
		ptrdiff_t	offset,
		bitfield_field32_t	field,
		uint32_t	value
	)

inline

Sets the field from the MMIO region base at the given offset.

This function performs a non-atomic read-write-modify operation on a MMIO region. The information of which portion of the register to set, is stored in the field. The semantics of this operation are similar to the mmio_region_nonatomic_set_mask32, however the appropriate portion of the register is zeroed before it is written to.

Parameters

base	the region to set the field in.
offset	the offset to set the field at, in bytes.
field	field within selected register field to be set.
value	value to set the field to.

Definition at line 323 of file mmio.h.

◆ mmio_region_nonatomic_set_mask32()

MMIO_DEPRECATED void mmio_region_nonatomic_set_mask32	(	mmio_region_t	base,
		ptrdiff_t	offset,
		uint32_t	mask,
		uint32_t	mask_index
	)

inline

Sets the bits in mask from the MMIO region base at the given offset.

This function performs a non-atomic read-write-modify operation on a MMIO region.

Parameters

base	the region to mask.
offset	the offset to apply the mask at, in bytes.
mask	the mask to set on the selected register.
mask_index	mask position within the selected register.

Definition at line 276 of file mmio.h.

◆ mmio_region_read_mask32()

OT_WARN_UNUSED_RESULT MMIO_DEPRECATED uint32_t mmio_region_read_mask32	(	mmio_region_t	base,
		ptrdiff_t	offset,
		uint32_t	mask,
		uint32_t	mask_index
	)

inline

Reads the bits in mask from the MMIO region base at the given offset.

This function has the same guarantees as mmio_region_read32() and mmio_region_write32().

Parameters

base	the region to mask.
offset	the offset to apply the mask at, in bytes.
mask	the mask to read from the selected register.
mask_index	mask position within the selected register.

Returns: return the value of the read mask.

Definition at line 216 of file mmio.h.

◆ mmio_region_write_only_set_bit32()

MMIO_DEPRECATED void mmio_region_write_only_set_bit32	(	mmio_region_t	base,
		ptrdiff_t	offset,
		uint32_t	bit_index
	)

inline

Sets the bit_indexth bit in the MMIO region base at the given offset.

This function is like nonatomic_set_bit32, but does not perform a read, for use with write-only memory.

There is no write_only_clear32, since such a function would be a no-op.

Parameters

base	the region to mask.
offset	the offset to apply the mask at.
bit_index	the bit to set.

Definition at line 403 of file mmio.h.

◆ mmio_region_write_only_set_field32()

MMIO_DEPRECATED void mmio_region_write_only_set_field32	(	mmio_region_t	base,
		ptrdiff_t	offset,
		bitfield_field32_t	field,
		uint32_t	value
	)

inline

Sets the field from the MMIO region base at the given offset.

This function is like nonatomic_set_field32, but does not perform a read, for use with write-only memory.

Parameters

base	the region to set the field in.
offset	the offset to set the field at, in bytes.
field	field within selected register field to be set.
value	value to set field to.

Definition at line 344 of file mmio.h.

◆ mmio_region_write_only_set_mask32()

MMIO_DEPRECATED void mmio_region_write_only_set_mask32	(	mmio_region_t	base,
		ptrdiff_t	offset,
		uint32_t	mask,
		uint32_t	mask_index
	)

inline

Sets the bits in mask from the MMIO region base at the given offset.

This function is like nonatomic_set_mask32, but does not perform a read, for use with write-only memory.

Parameters

base	the region to mask.
offset	the offset to apply the mask at, in bytes.
mask	the mask to set on the selected register.
mask_index	mask position within the selected register.

Definition at line 298 of file mmio.h.

(ae68723)

Data Structures

Macros

Typedefs

Functions

Detailed Description

Data Structure Documentation

◆ mmio_region

Macro Definition Documentation

◆ MMIO_DEPRECATED

Typedef Documentation

◆ mmio_region_t

Function Documentation

◆ mmio_region_get_bit32()

◆ mmio_region_memcpy_from_mmio32()

◆ mmio_region_memcpy_to_mmio32()

◆ mmio_region_nonatomic_clear_bit32()

◆ mmio_region_nonatomic_clear_mask32()

◆ mmio_region_nonatomic_set_bit32()

◆ mmio_region_nonatomic_set_field32()

◆ mmio_region_nonatomic_set_mask32()

◆ mmio_region_read_mask32()

◆ mmio_region_write_only_set_bit32()

◆ mmio_region_write_only_set_field32()

◆ mmio_region_write_only_set_mask32()