public interface MMIODevice extends Peripheral
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. 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.PeripheralNotAvailableException
BIG_ENDIAN, LITTLE_ENDIAN, MIXED_ENDIAN, UNDEFINED_ID
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. |
close, getID, getName, getProperties, isOpen
RawBlock getAsRawBlock() throws java.io.IOException, PeripheralNotAvailableException
RawBlock
instance.RawBlock
object encapsulating whole memory area this device is mapped to.java.io.IOException
- if an IO error occurred.PeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).RawBlock getBlock(java.lang.String name) throws java.io.IOException, PeripheralNotAvailableException
name
- name of the memory block.RawBlock
object encapsulating the designated memory block.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).int getByteOrdering() throws java.io.IOException, PeripheralNotAvailableException
Peripheral.BIG_ENDIAN
if big-endian; Peripheral.LITTLE_ENDIAN
if little-endian; Peripheral.MIXED_ENDIAN
otherwise.java.io.IOException
- if an IO error occurred.PeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).RawByte getByteRegister(java.lang.String name) throws java.io.IOException, PeripheralNotAvailableException
byte
value.name
- name of the register.RawByte
object encapsulating the byte
value of the designated register.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).RawInt getIntRegister(java.lang.String name) throws java.io.IOException, PeripheralNotAvailableException
int
value.name
- name of the register.RawInt
object encapsulating the int
value of the designated register.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).RawShort getShortRegister(java.lang.String name) throws java.io.IOException, PeripheralNotAvailableException
short
value.name
- name of the register.RawShort
object encapsulating the short
value of the designated register.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).void setMMIOEventListener(int eventId, byte[] captureBuffer, int capturedIndex, int capturedLength, MMIOEventListener listener) throws java.io.IOException, PeripheralNotAvailableException
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.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.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
.void setMMIOEventListener(int eventId, MMIOEventListener listener) throws java.io.IOException, PeripheralNotAvailableException
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.eventId
- ID of the native event to listen to.listener
- the MMIOEventListener
instance to be notified upon occurrence of the designated event.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).void setMMIOEventListener(int eventId, java.lang.String capturedName, MMIOEventListener listener) throws java.io.IOException, PeripheralNotAvailableException
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.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.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
.Copyright (c) 1990, 2013, Oracle and/or its affiliates. All rights reserved.