Software APIs
Data Structures | Macros | Typedefs | Functions
mmio.h File Reference

(b233d14)

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_indexth 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_indexth 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_indexth 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_indexth 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 173 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
basethe region to mask.
offsetthe offset to apply the mask at.
bit_indexthe bit to check.
Returns
true if the bit is set, false otherwise

Definition at line 230 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
basethe MMIO region to read from.
offsetthe offset to start reading from, in bytes.
destthe main memory location to start writing to.
lennumber 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
basethe MMIO region to write to.
offsetthe offset to start writing to, in bytes.
srcthe main memory location to start reading from.
lennumber 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
basethe region to mask.
offsetthe offset to apply the mask at.
bit_indexthe bit to clear.

Definition at line 357 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
basethe region to mask.
offsetthe offset to apply the mask at, in bytes.
maskthe mask to clear from the selected register.
mask_indexmask position within the selected register.

Definition at line 247 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
basethe region to mask.
offsetthe offset to apply the mask at.
bit_indexthe bit to set.

Definition at line 375 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
basethe region to set the field in.
offsetthe offset to set the field at, in bytes.
fieldfield within selected register field to be set.
valuevalue to set the field to.

Definition at line 316 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
basethe region to mask.
offsetthe offset to apply the mask at, in bytes.
maskthe mask to set on the selected register.
mask_indexmask position within the selected register.

Definition at line 269 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
basethe region to mask.
offsetthe offset to apply the mask at, in bytes.
maskthe mask to read from the selected register.
mask_indexmask position within the selected register.
Returns
return the value of the read mask.

Definition at line 209 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
basethe region to mask.
offsetthe offset to apply the mask at.
bit_indexthe bit to set.

Definition at line 396 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
basethe region to set the field in.
offsetthe offset to set the field at, in bytes.
fieldfield within selected register field to be set.
valuevalue to set field to.

Definition at line 337 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
basethe region to mask.
offsetthe offset to apply the mask at, in bytes.
maskthe mask to set on the selected register.
mask_indexmask position within the selected register.

Definition at line 291 of file mmio.h.