Package com.oracle.deviceaccess.mmio

Interfaces and classes for performing memory-mapped I/O.

See: Description

Interface Summary

Interface	Description
MMIODevice	The MMIODevice class provides methods to retrieve memory-mapped registers and memory blocks of a peripheral device.
MMIOEventListener	The MMIOEventListener interface defines methods for getting notified of events fired by peripherals mapped to memory.
RawBlock	The RawBlock interface provides methods to access a continuous range of physical memory (raw memory).
RawByte	The RawByte interface provides methods for setting and getting the value of a register or memory area holding a byte value.
RawInt	The RawInt interface provides methods for setting and getting the value of a register or memory area holding a int value.
RawMemory	The RawMemory interface provides generic methods for the different types of raw memory area a peripheral device's registers may be mapped to.
RawShort	The RawShort interface provides methods for setting and getting the value of a register or memory area holding a short value.

Class Summary

Class	Description
MMIODeviceConfig	The MMIODeviceConfig class encapsulates the hardware addressing information, and static and dynamic configuration parameters of an MMIO device.
MMIODeviceConfig.RawBlockConfig	The RawBlockConfig class encapsulates the configuration parameters of a memory block.
MMIODeviceConfig.RawMemoryConfig	The RawMemoryConfig class encapsulates the configuration parameters of a generic raw memory area.
MMIODeviceConfig.RawRegisterConfig	The RawRegisterConfig class encapsulates the configuration parameters of a register.
MMIOEvent	The MMIOEvent class encapsulates events fired by peripherals mapped to memory.

Exception Summary

Exception	Description
AccessOutOfBoundsException	Thrown by an instance of RawBlock if the offset used is out of valid boundary of the specified memory block.

Package com.oracle.deviceaccess.mmio Description

Interfaces and classes for performing memory-mapped I/O.

Memory mapped I/O is typically used for controlling hardware peripherals by reading from and writing to registers or memory blocks of the hardware mapped to the system memory. The MMIO APIs allows for low level control over the peripheral.

In order to access a specific memory block a device has been mapped to, an application should first open and obtain an MMIODevice instance for the memory-mapped I/O device the application wants to control and access, using its numerical ID, name, type (interface) and/or properties:

Using its ID

 MMIODevice device = (MMIODevice) PeripheralManager.open(7);
 

Using its name and interface

 MMIODevice device = (MMIODevice) PeripheralManager.open("RTC", MMIODevice.class, null);
 

Once the peripheral opened, the application can retrieve registers using methods of the MMIODevice interface such as the MMIODevice.getByteRegister(String) methods.

 RawByte seconds = (RawByte) device.getByteRegister("Seconds");
 

When done, the application should call the Peripheral.close() method to release MMIO device.

 device.close();
 

The following sample codes give examples of using the MMIO API to communicate Real Time Clock device:

 static final int INTERRUPT = 0;
 
 MMIODevice rtc = null;
 try {
     rtc = (MMIODevice) PeripheralManager.open("RTC", MMIODevice.class, (String[]) null);
     //The RTC device has 14 bytes of clock and control registers and 50 bytes
     // of general purpose RAM (see the data sheet of the HITACHI HD146818 Real Time Clock).
     RawByte seconds = rtc.getByteRegister("Seconds");
     RawByte secAlarm = rtc.getByteRegister("SecAlarm");
     RawByte minutes = rtc.getByteRegister("Minutes");
     RawByte minAlarm = rtc.getByteRegister("MinAlarm");
     RawByte hours = rtc.getByteRegister("Hours");
     RawByte hrAlarm = rtc.getByteRegister("HrAlarm");
     ... // More registers
     RawByte registerA = rtc.getByteRegister("RegisterA");
     RawByte registerB = rtc.getByteRegister("RegisterB");
     RawByte registerC = rtc.getByteRegister("RegisterC");
     RawByte registerD = rtc.getByteRegister("RegisterD");
     RawBlock userRAM = rtc.getBlock("UserRam");
     ...
 } catch (PeripheralException pe) {
 } catch (IOException ioe) {
 } finally {
     if (rtc != null) {
         try {
             rtc.close();
         } catch (IOException ex) {
         }
     }
 }
 

 // Sets the daily alarm for after some delay
 public void setAlarm(byte delaySeconds, byte delayMinutes, byte delayHours) throws IOException, PeripheralException {
     MMIODevice rtc = (MMIODevice) PeripheralManager.open("RTC", MMIODevice.class, (String[]) null);
     RawByte seconds = rtc.getByteRegister("Seconds");
     RawByte secAlarm = rtc.getByteRegister("SecAlarm");
     RawByte minutes = rtc.getByteRegister("Minutes");
     RawByte minAlarm = rtc.getByteRegister("MinAlarm");
     RawByte hours = rtc.getByteRegister("Hours");
     RawByte hrAlarm = rtc.getByteRegister("HrAlarm");
     RawByte registerB = rtc.getByteRegister("RegisterB");
 
     // Directly read from/write to the registers using RawByte instances.
     byte currentSeconds = seconds.get();
     byte currentMinutes = minutes.get();
     byte currentHours = hours.get();
     int i = (currentSeconds + delaySeconds) % 60;
     int j = (currentSeconds + delaySeconds) / 60;
     secAlarm.set((byte) i);
     i = (currentMinutes + delayMinutes + j) % 60;
     j = (currentMinutes + delayMinutes + j) / 60;
     minAlarm.set((byte) i);
     i = (currentHours + delayHours + j) % 24;
     hrAlarm.set((byte) i);
     rtc.setMMIOEventListener(INTERRUPT, new MMIOEventListener() {
         public void eventDispatched(MMIOEvent event) {
             try {
                 MMIODevice rtc = (MMIODevice) event.getPeripheral();
                 RawByte registerC = rtc.getByteRegister("RegisterC");
                 // Check the Alarm Interrupt Flag (AF)
                 if ((registerC.get() & 0X20) != 0) {
                     // Notify application of alarm
                 }
             } catch (IOException ex) {
             } catch (PeripheralNotAvailableException ex) {
             }
         }
     });
     // Set the Alarm Interrupt Enabled (AIE) flag
     registerB.set((byte) (registerB.get() | 0X20));
 }
 

Alternatively, in this example, the value of RegisterC could be automatically captured upon occurrence of an interrupt request from the Real Time Clock device as follows:

 rtc.setMMIOEventListener(INTERRUPT, "RegisterC", new MMIOEventListener() {
 
     public void eventDispatched(MMIOEvent event) {
         byte v = (byte) event.getCapturedRegisterValue();
         // Check the Alarm Interrupt Flag (AF)
         if ((v & 0X20) != 0) {
             // Notify application of alarm
         }
     }
 });
 

Security

MMIO devices are opened by invoking one of the com.oracle.deviceaccess.PeripheralManager.open methods. The "com.oracle.deviceaccess.mmio" permission allows access to be granted to MMIO devices as a whole.