# 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, path='/dev/mem')

  Bases: `object`

  Instantiate an MMIO object and map the region of physical memory specified by the physaddr base physical address and size size in bytes. The default memory character device “/dev/mem” can be overridden with the keyword argument path, for use with sandboxed memory character devices, e.g. “/dev/gpiomem”.

  Parameters

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

    - size (int, long) – size of memory region.

    - path (str) – memory character device path.

  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.

  property base

    Get the base physical address of the MMIO region.

    Type

      int

  property size

    Get the mapping size of the MMIO region.

    Type

      int

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