# MMIO

## Code Example

    from periphery import MMIO

    # Open am335x real-time clock subsystem page
    rtc_mmio = MMIO(0x44E3E000, 0x1000)

    # Read current time
    rtc_secs = rtc_mmio.read32(0x00)
    rtc_mins = rtc_mmio.read32(0x04)
    rtc_hrs = rtc_mmio.read32(0x08)

    print("hours: {:02x} minutes: {:02x} seconds: {:02x}".format(rtc_hrs, rtc_mins, rtc_secs))

    rtc_mmio.close()

    # Open am335x control module page
    ctrl_mmio = MMIO(0x44E10000, 0x1000)

    # Read MAC address
    mac_id0_lo = ctrl_mmio.read32(0x630)
    mac_id0_hi = ctrl_mmio.read32(0x634)

    print("MAC address: {:04x}{:08x}".format(mac_id0_lo, mac_id0_hi))

    ctrl_mmio.close()

## API

class `periphery.``MMIO`(physaddr, size)

  Bases: `object`

  Instantiate an MMIO object and map the region of physical memory specified by the address base physaddr and size size in bytes.

  Parameters:

  - physaddr (int, long) – base physical address of memory region.
  - size (int, long) – size of memory region.

  Returns: | MMIO object.
  Return type: | MMIO

  Raises:

  - `MMIOError` – if an I/O or OS error occurs.
  - `TypeError` – if physaddr or size types are invalid.

  `read32`(offset)

    Read 32-bits from the specified offset in bytes, relative to the base physical address of the MMIO region.

    Parameters: | offset (int, long) – offset from base physical address, in bytes.
    Returns: | 32-bit value read.
    Return type: | int

    Raises:

    - `TypeError` – if offset type is invalid.
    - `ValueError` – if offset is out of bounds.

  `read16`(offset)

    Read 16-bits from the specified offset in bytes, relative to the base physical address of the MMIO region.

    Parameters: | offset (int, long) – offset from base physical address, in bytes.
    Returns: | 16-bit value read.
    Return type: | int

    Raises:

    - `TypeError` – if offset type is invalid.
    - `ValueError` – if offset is out of bounds.

  `read8`(offset)

    Read 8-bits from the specified offset in bytes, relative to the base physical address of the MMIO region.

    Parameters: | offset (int, long) – offset from base physical address, in bytes.
    Returns: | 8-bit value read.
    Return type: | int

    Raises:

    - `TypeError` – if offset type is invalid.
    - `ValueError` – if offset is out of bounds.

  `read`(offset, length)

    Read a string of bytes from the specified offset in bytes, relative to the base physical address of the MMIO region.

    Parameters:

    - offset (int, long) – offset from base physical address, in bytes.
    - length (int) – number of bytes to read.

    Returns: | bytes read.
    Return type: | bytes

    Raises:

    - `TypeError` – if offset type is invalid.
    - `ValueError` – if offset is out of bounds.

  `write32`(offset, value)

    Write 32-bits to the specified offset in bytes, relative to the base physical address of the MMIO region.

    Parameters:

    - offset (int, long) – offset from base physical address, in bytes.
    - value (int, long) – 32-bit value to write.

    Raises:

    - `TypeError` – if offset or value type are invalid.
    - `ValueError` – if offset or value are out of bounds.

  `write16`(offset, value)

    Write 16-bits to the specified offset in bytes, relative to the base physical address of the MMIO region.

    Parameters:

    - offset (int, long) – offset from base physical address, in bytes.
    - value (int, long) – 16-bit value to write.

    Raises:

    - `TypeError` – if offset or value type are invalid.
    - `ValueError` – if offset or value are out of bounds.

  `write8`(offset, value)

    Write 8-bits to the specified offset in bytes, relative to the base physical address of the MMIO region.

    Parameters:

    - offset (int, long) – offset from base physical address, in bytes.
    - value (int, long) – 8-bit value to write.

    Raises:

    - `TypeError` – if offset or value type are invalid.
    - `ValueError` – if offset or value are out of bounds.

  `write`(offset, data)

    Write a string of bytes to the specified offset in bytes, relative to the base physical address of the MMIO region.

    Parameters:

    - offset (int, long) – offset from base physical address, in bytes.
    - data (bytes, bytearray, list) – a byte array or list of 8-bit integers to write.

    Raises:

    - `TypeError` – if offset or data type are invalid.
    - `ValueError` – if offset is out of bounds, or if data is not valid bytes.

  `close`()

    Unmap the MMIO object’s mapped physical memory.

  `base`

    Get the base physical address of the MMIO region.

    Type: | int

  `size`

    Get the mapping size of the MMIO region.

    Type: | int

  `pointer`

    Get a ctypes void pointer to the memory mapped region.

    Type: | ctypes.c_void_p

class `periphery.``MMIOError`

  Bases: `OSError`

  Base class for MMIO errors.