com.oracle.deviceaccess.mmio

Interface MMIODevice

All Superinterfaces:

Peripheral

public interface MMIODevice
extends Peripheral

The MMIODevice class provides methods to retrieve memory-mapped registers and memory blocks of a peripheral device.

Each memory-mapped I/O device is identified by a numerical ID and by a name.
An MMIODevice instance can be opened by a call to one of the PeripheralManager.open() methods.

With memory-mapped I/O, peripheral devices can be controlled by directly reading or writing to memory areas representing the registers or memory blocks of the peripheral device. Each register or memory block is represented by a RawMemory instance. Each register or memory block is also usually assigned a name which can be used for name-based lookup. The complete memory area the peripheral device is mapped to can also be retrieved as single RawBlock instance, allowing for offset-based access to all the registers and memory blocks of the device.

An application can register an MMIOEventListener instance to monitor native events of the designated type fired by the peripheral device. To register a MMIOEventListener instance, the application must call the setMMIOEventListener(int, MMIOEventListener) method. The registered listener can later on be removed by calling the same method with a null listener parameter. Asynchronous notification may not be supported by all memory-mapped devices. An attempt to set a listener on a memory-mapped device which does not supports it will result in an InvalidOperationException being thrown.

When done, an application should call the MMIODevice.close() method to release the MMIO device. Any further attempt to access an MMIO device which has been closed will result in a PeripheralNotAvailableException been thrown.

Note that the event types (IDs) supported by a memory-mapped device are device as well as platform specific. For example, each interrupt request line of a peripheral device may be mapped to a distinct event type ID. Refer to the device data sheet and the platform configuration.

Note that the byte, short and int values passed to and returned by this API have to be interpreted as 8 bit, 16 bit and 32 bit unsigned quantities. Proper handling is needed when performing integer arithmetic on these quantities.

See Also:

PeripheralNotAvailableException

Field Summary

Fields inherited from interface com.oracle.deviceaccess.Peripheral

BIG_ENDIAN, LITTLE_ENDIAN, MIXED_ENDIAN, UNDEFINED_ID

Method Summary

Methods

Modifier and Type	Method and Description
RawBlock	getAsRawBlock() Gets the complete memory area this device is mapped to as a RawBlock instance.
RawBlock	getBlock(java.lang.String name) Gets the designated memory block.
int	getByteOrdering() Returns the byte ordering of this memory-mapped peripheral device.
RawByte	getByteRegister(java.lang.String name) Gets the designated register holding a byte value.
RawInt	getIntRegister(java.lang.String name) Gets the designated register holding a int value.
RawShort	getShortRegister(java.lang.String name) Gets the designated register holding a short value.
void	setMMIOEventListener(int eventId, byte[] captureBuffer, int capturedIndex, int capturedLength, MMIOEventListener listener) Registers a MMIOEventListener instance to monitor native events of the designated type fired by the peripheral device mapped to this MMIODevice object and capture the content of designated memory area.
void	setMMIOEventListener(int eventId, MMIOEventListener listener) Registers a MMIOEventListener instance to monitor native events of the designated type fired by the peripheral device mapped to this MMIODevice object.
void	setMMIOEventListener(int eventId, java.lang.String capturedName, MMIOEventListener listener) Registers a MMIOEventListener instance to monitor native events of the designated type fired by the peripheral device mapped to this MMIODevice object and capture the content of designated register or block.

Methods inherited from interface com.oracle.deviceaccess.Peripheral

close, getID, getName, getProperties, isOpen

Method Detail

getAsRawBlock

RawBlock getAsRawBlock()
                       throws java.io.IOException,
                              PeripheralNotAvailableException

Gets the complete memory area this device is mapped to as a RawBlock instance.

Returns:

a RawBlock object encapsulating whole memory area this device is mapped to.

Throws:

java.io.IOException - if an IO error occurred.

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

getBlock

RawBlock getBlock(java.lang.String name)
                  throws java.io.IOException,
                         PeripheralNotAvailableException

Gets the designated memory block.

Parameters:

name - name of the memory block.

Returns:

a RawBlock object encapsulating the designated memory block.

Throws:

java.io.IOException - if an IO error occurred.

java.lang.IllegalArgumentException - if the provided name does not correspond to any memory block.

java.lang.NullPointerException - if name is null.

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

getByteOrdering

int getByteOrdering()
                    throws java.io.IOException,
                           PeripheralNotAvailableException

Returns the byte ordering of this memory-mapped peripheral device.

Returns:

Peripheral.BIG_ENDIAN if big-endian; Peripheral.LITTLE_ENDIAN if little-endian; Peripheral.MIXED_ENDIAN otherwise.

Throws:

java.io.IOException - if an IO error occurred.

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

getByteRegister

RawByte getByteRegister(java.lang.String name)
                        throws java.io.IOException,
                               PeripheralNotAvailableException

Gets the designated register holding a byte value.

Parameters:

name - name of the register.

Returns:

a RawByte object encapsulating the byte value of the designated register.

Throws:

java.lang.IllegalArgumentException - if the provided name does not correspond to any register or if the type of of the value held in the register does not match.

java.lang.NullPointerException - if name is null.

java.io.IOException - if an IO error occurred.

PeripheralNotAvailableException - if the peripheral is not currently available (has been released).

getIntRegister

RawInt getIntRegister(java.lang.String name)
                      throws java.io.IOException,
                             PeripheralNotAvailableException

Gets the designated register holding a int value.

Parameters:

name - name of the register.

Returns:

a RawInt object encapsulating the int value of the designated register.

Throws:

java.lang.IllegalArgumentException - if the provided name does not correspond to any register or if the type of of the value held in the register does not match.

java.lang.NullPointerException - if name is null.

java.io.IOException - if an IO error occurred.

PeripheralNotAvailableException - if the peripheral is not currently available (has been released).

getShortRegister

RawShort getShortRegister(java.lang.String name)
                          throws java.io.IOException,
                                 PeripheralNotAvailableException

Gets the designated register holding a short value.

Parameters:

name - name of the register.

Returns:

a RawShort object encapsulating the short value of the designated register.

Throws:

java.lang.IllegalArgumentException - if the provided name does not correspond to any register or if the type of of the value held in the register does not match.

java.lang.NullPointerException - if name is null.

java.io.IOException - if an IO error occurred.

PeripheralNotAvailableException - if the peripheral is not currently available (has been released).

setMMIOEventListener

void setMMIOEventListener(int eventId,
                        byte[] captureBuffer,
                        int capturedIndex,
                        int capturedLength,
                        MMIOEventListener listener)
                          throws java.io.IOException,
                                 PeripheralNotAvailableException

Registers a MMIOEventListener instance to monitor native events of the designated type fired by the peripheral device mapped to this MMIODevice object and capture the content of designated memory area.

While the listener can be triggered by hardware interrupts, there are no real-time guarantees of when the listener will be called.

The content the designated memory area will be captured upon the occurrence of the designated event.

If listener is null then listener previously registered for the specified event type will be removed.

Only one listener can be registered at a particular time for a particular event type.

Parameters:

eventId - ID of the native event to listen to.

captureBuffer - the buffer to save the captured memory area in.

capturedIndex - the byte index in this device mapped raw memory area to capture.

capturedLength - the length (in bytes) of the content to capture; must be non-negative and no larger than captureBuffer.length.

listener - the MMIOEventListener instance to be notified upon occurrence of the designated event.

Throws:

java.io.IOException - if an IO error occurred.

AccessOutOfBoundsException - if capturedIndex and/or capturedLength would result in pointing outside this device mapped raw memory area.

java.lang.IndexOutOfBoundsException - if the preconditions on the offset and length parameters do not hold.

java.lang.IllegalArgumentException - if eventId does not correspond to any supported event.

com.oracle.deviceaccess.InvalidOperationException - if this MMIODevice object does not support asynchronous event notification.

InvalidStateException - if listener is not null and a listener is already registered for the specified event type.

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

java.lang.NullPointerException - if captureBuffer is null.

setMMIOEventListener

void setMMIOEventListener(int eventId,
                        MMIOEventListener listener)
                          throws java.io.IOException,
                                 PeripheralNotAvailableException

Registers a MMIOEventListener instance to monitor native events of the designated type fired by the peripheral device mapped to this MMIODevice object. While the listener can be triggered by hardware interrupts, there are no real-time guarantees of when the listener will be called.

If listener is null then listener previously registered for the specified event type will be removed.

Only one listener can be registered at a particular time for a particular event type.

Parameters:

eventId - ID of the native event to listen to.

listener - the MMIOEventListener instance to be notified upon occurrence of the designated event.

Throws:

java.io.IOException - if an IO error occurred.

java.lang.IllegalArgumentException - if eventId does not correspond to any supported event.

com.oracle.deviceaccess.InvalidOperationException - if this MMIODevice object does not support asynchronous event notification.

InvalidStateException - if listener is not null and a listener is already registered for the specified event type.

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

setMMIOEventListener

void setMMIOEventListener(int eventId,
                        java.lang.String capturedName,
                        MMIOEventListener listener)
                          throws java.io.IOException,
                                 PeripheralNotAvailableException

Registers a MMIOEventListener instance to monitor native events of the designated type fired by the peripheral device mapped to this MMIODevice object and capture the content of designated register or block.

While the listener can be triggered by hardware interrupts, there are no real-time guarantees of when the listener will be called.

The content of the designated register or block will be captured upon the occurrence of the designated event.

If listener is null then listener previously registered for the specified event type will be removed.

Only one listener can be registered at a particular time for a particular event type.

Parameters:

eventId - ID of the native event to listen to.

capturedName - the name of the register or memory block whose content is to be captured at the time of the underlying event occurs.

listener - the MMIOEventListener instance to be notified upon occurrence of the designated event.

Throws:

java.io.IOException - if an IO error occurred.

java.lang.IllegalArgumentException - if eventId does not correspond to any supported event; or if the provided name does not correspond to any memory block or register.

com.oracle.deviceaccess.InvalidOperationException - if this MMIODevice object does not support asynchronous event notification.

InvalidStateException - if listener is not null and a listener is already registered for the specified event type.

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

java.lang.NullPointerException - if capturedName is null.