public interface MMIODevice extends Peripheral<MMIODevice>
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.MMIOPermission
,
ClosedPeripheralException
BIG_ENDIAN, LITTLE_ENDIAN, MIXED_ENDIAN
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> |
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,
int capturedIndex,
java.nio.ByteBuffer captureBuffer,
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, getDescriptor, isOpen, tryLock, unlock
RawBlock getAsRawBlock() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
RawBlock
instance.RawBlock
object encapsulating whole memory area this device is mapped to.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.RawBlock getBlock(java.lang.String name) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
name
- name of the memory block.RawBlock
object encapsulating the designated memory block.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.int getByteOrdering() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
Peripheral.BIG_ENDIAN
if big-endian; Peripheral.LITTLE_ENDIAN
if little-endian; Peripheral.MIXED_ENDIAN
otherwise.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.<T extends java.lang.Number> RawRegister<T> getRegister(java.lang.String name, java.lang.Class<T> type) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
name
- the name of the register.type
- the type of the value held in the register.RawRegister
object encapsulating the 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
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.void setMMIOEventListener(int eventId, int capturedIndex, java.nio.ByteBuffer captureBuffer, MMIOEventListener listener) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
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 of the designated memory area will be captured upon the occurrence of the designated event.
Upon notification of the corresponding MMIOEvent
, the captured content of a designated memory area
may be retrieved using MMIOEvent.getCapturedMemoryContent
.
If this MMIODevice
is open in PeripheralManager.SHARED
access mode
the listeners registered by all the applications sharing the underlying device will get
notified of the events they registered for.
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.capturedIndex
- the byte index in this device mapped raw memory area to capture.captureBuffer
- the direct ByteBuffer
to save the captured memory area in; up to captureBuffer.remaining()
bytes will
be copied from this device mapped raw memory area starting at capturedIndex
into this buffer starting at the buffer's position at the moment this method is called.listener
- the MMIOEventListener
instance to be notified upon occurrence of the designated event.java.io.IOException
- if some other I/O error occurs.AccessOutOfBoundsException
- if capturedIndex
and/or captureBuffer.remaining()
would result in pointing outside this device
mapped raw memory area.java.lang.IllegalArgumentException
- if eventId
does not correspond to any supported event or if captureBuffer
is not a direct ByteBuffer
.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.ClosedPeripheralException
- if the peripheral has been closed.java.lang.NullPointerException
- if captureBuffer
is null
.UnavailablePeripheralException
void setMMIOEventListener(int eventId, MMIOEventListener listener) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
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 this MMIODevice
is open in PeripheralManager.SHARED
access mode
the listeners registered by all the applications sharing the underlying device will get
notified of the events they registered for.
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 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.ClosedPeripheralException
- if the peripheral has been closed.UnavailablePeripheralException
void setMMIOEventListener(int eventId, java.lang.String capturedName, MMIOEventListener listener) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
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.
Upon notification of the corresponding MMIOEvent
, the captured value of a designated register may
be retrieved using MMIOEvent.getCapturedRegisterValue
while the captured content of a designated block
may be retrieved using MMIOEvent.getCapturedMemoryContent
.
If this MMIODevice
is open in PeripheralManager.SHARED
access mode
the listeners registered by all the applications sharing the underlying device will get
notified of the events they registered for.
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 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.ClosedPeripheralException
- if the peripheral has been closed.java.lang.NullPointerException
- if capturedName
is null
.UnavailablePeripheralException
Copyright © 2012, 2014, Oracle and/or its affiliates. All rights reserved.
Legal Notices