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

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

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

Go to the source code of this file.

Data Structures

struct  mmio_region
 An mmio_region_t is an opaque handle to an MMIO region; it should only be modified using the functions provided in this header. 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...
 
#define MMIO_WARN_UNUSED_RESULT   __attribute__((warn_unused_result))
 All MMIO functions return their results using return values, rather than out- parameters. More...
 

Typedefs

typedef struct mmio_region mmio_region_t
 An mmio_region_t is an opaque handle to an MMIO region; it should only be modified using the functions provided in this header.
 

Functions

MMIO_WARN_UNUSED_RESULT mmio_region_t mmio_region_from_addr (uintptr_t address)
 Create a new mmio_region_t from the given address. More...
 
MMIO_WARN_UNUSED_RESULT uint8_t mmio_region_read8 (mmio_region_t base, ptrdiff_t offset)
 Reads an aligned uint8_t from the MMIO region base at the given byte offset. More...
 
MMIO_WARN_UNUSED_RESULT uint32_t mmio_region_read32 (mmio_region_t base, ptrdiff_t offset)
 Reads an aligned uint32_t from the MMIO region base at the given byte offset. More...
 
void mmio_region_write8 (mmio_region_t base, ptrdiff_t offset, uint8_t value)
 Writes an aligned uint8_t to the MMIO region base at the given byte offset. More...
 
void mmio_region_write32 (mmio_region_t base, ptrdiff_t offset, uint32_t value)
 Writes an aligned uint32_t to the MMIO region base at the given byte offset. More...
 
MMIO_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...
 
MMIO_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

struct mmio_region

An mmio_region_t is an opaque handle to an MMIO region; it should only be modified using the functions provided in this header.

Definition at line 58 of file mmio.h.

Data Fields
volatile void * base

Macro Definition Documentation

#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.

#define MMIO_WARN_UNUSED_RESULT   __attribute__((warn_unused_result))

All MMIO functions return their results using return values, rather than out- parameters.

Where the return types are non-void, it is prudent to ensure these results are used, or explicitly discarded (in the case of a volatile read that is needed for side effects only).

Definition at line 51 of file mmio.h.

Function Documentation

MMIO_WARN_UNUSED_RESULT mmio_region_t mmio_region_from_addr ( uintptr_t  address)
inline

Create a new mmio_region_t from the given address.

Parameters
addressan address to an MMIO region.
Returns
a mmio_region_t value representing that region.

Definition at line 67 of file mmio.h.

MMIO_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 194 of file mmio.h.

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 110 of file mmio.c.

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 115 of file mmio.c.

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 321 of file mmio.h.

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 211 of file mmio.h.

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 339 of file mmio.h.

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 280 of file mmio.h.

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 233 of file mmio.h.

MMIO_WARN_UNUSED_RESULT uint32_t mmio_region_read32 ( mmio_region_t  base,
ptrdiff_t  offset 
)
inline

Reads an aligned uint32_t from the MMIO region base at the given byte offset.

This function is guaranteed to commit a read to memory, and will not be reordered with respect to other MMIO manipulations.

Parameters
basethe region to read from.
offsetthe offset to read at, in bytes.
Returns
the read value.

Definition at line 101 of file mmio.h.

MMIO_WARN_UNUSED_RESULT uint8_t mmio_region_read8 ( mmio_region_t  base,
ptrdiff_t  offset 
)
inline

Reads an aligned uint8_t from the MMIO region base at the given byte offset.

This function is guaranteed to commit a read to memory, and will not be reordered with respect to other MMIO manipulations.

Parameters
basethe region to read from.
offsetthe offset to read at, in bytes.
Returns
the read value.

Definition at line 85 of file mmio.h.

MMIO_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. return the value of the read mask.

Definition at line 173 of file mmio.h.

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

Writes an aligned uint32_t to the MMIO region base at the given byte offset.

This function is guaranteed to commit a write to memory, and will not be reordered with respect to other region manipulations.

Parameters
basethe region to write to.
offsetthe offset to write at, in bytes.
valuethe value to write.

Definition at line 132 of file mmio.h.

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

Writes an aligned uint8_t to the MMIO region base at the given byte offset.

This function is guaranteed to commit a write to memory, and will not be reordered with respect to other region manipulations.

Parameters
basethe region to write to.
offsetthe offset to write at, in bytes.
valuethe value to write.

Definition at line 116 of file mmio.h.

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 360 of file mmio.h.

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 301 of file mmio.h.

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 255 of file mmio.h.