com.oracle.deviceaccess.mmio

Interface MMIODevice

All Superinterfaces:

java.lang.AutoCloseable, java.nio.channels.Channel, java.io.Closeable, Peripheral<MMIODevice>

public interface MMIODevice
extends Peripheral<MMIODevice>

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

An MMIO device may be identified by the numerical ID and by the name (if any defined) that correspond to its registered configuration. An MMIODevice instance can be opened by a call to one of the PeripheralManager.open(id,...) methods using its ID or by a call to one of the PeripheralManager.open(name,...) methods using its name. When an MMIODevice instance is opened with an ad-hoc MMIODeviceConfig configuration (which includes its hardware addressing information) using one of the PeripheralManager.open(config,...) it is not assigned any ID nor name.

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 UnsupportedOperationException being thrown.

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

Opening a MMIODevice instance is subject to permission checks (see MMIOPermission).

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:

MMIOPermission, ClosedPeripheralException

Field Summary

Fields inherited from interface com.oracle.deviceaccess.Peripheral

BIG_ENDIAN, LITTLE_ENDIAN, MIXED_ENDIAN

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.
<T extends java.lang.Number> RawRegister<T>	getRegister(java.lang.String name, java.lang.Class<T> type) Gets the designated register holding a value of the designated type.
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, getDescriptor, isOpen, tryLock, unlock

Method Detail

getAsRawBlock

RawBlock getAsRawBlock()
                       throws java.io.IOException,
                              UnavailablePeripheralException,
                              ClosedPeripheralException

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 some other I/O error occurs.

UnavailablePeripheralException - if this peripheral is not currently available - such as it is locked by another application.

ClosedPeripheralException - if the peripheral has been closed.

getBlock

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

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 some other I/O error occurs.

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

java.lang.NullPointerException - if name is null.

UnavailablePeripheralException - if this peripheral is not currently available - such as it is locked by another application.

ClosedPeripheralException - if the peripheral has been closed.

getByteOrdering

int getByteOrdering()
                    throws java.io.IOException,
                           UnavailablePeripheralException,
                           ClosedPeripheralException

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 some other I/O error occurs.

UnavailablePeripheralException - if this peripheral is not currently available - such as it is locked by another application.

ClosedPeripheralException - if the peripheral has been closed.

getRegister

<T extends java.lang.Number> RawRegister<T> getRegister(java.lang.String name,
                                                      java.lang.Class<T> type)
                                                    throws java.io.IOException,
                                                           UnavailablePeripheralException,
                                                           ClosedPeripheralException

Gets the designated register holding a value of the designated type.

Parameters:

name - the name of the register.

type - the type of the value held in the register.

Returns:

a RawRegister object encapsulating the 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 or type is null.

java.io.IOException - if some other I/O error occurs.

UnavailablePeripheralException - if this peripheral is not currently available - such as it is locked by another application.

ClosedPeripheralException - if the peripheral has been closed.

setMMIOEventListener

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

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; captured bytes are copied into this buffer starting at index 0.

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 some other I/O error occurs.

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.

java.lang.UnsupportedOperationException - if this MMIODevice object does not support asynchronous event notification.

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

UnavailablePeripheralException - if this peripheral is not currently available - such as it is locked by another application.

ClosedPeripheralException - if the peripheral has been closed.

java.lang.NullPointerException - if captureBuffer is null.

setMMIOEventListener

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

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 some other I/O error occurs.

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

java.lang.UnsupportedOperationException - if this MMIODevice object does not support asynchronous event notification.

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

UnavailablePeripheralException - if this peripheral is not currently available - such as it is locked by another application.

ClosedPeripheralException - if the peripheral has been closed.

setMMIOEventListener

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

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 some other I/O error occurs.

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.

java.lang.UnsupportedOperationException - if this MMIODevice object does not support asynchronous event notification.

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

UnavailablePeripheralException - if this peripheral is not currently available - such as it is locked by another application.

ClosedPeripheralException - if the peripheral has been closed.

java.lang.NullPointerException - if capturedName is null.