@Deprecated
public final class PhysicalMemoryManager
extends java.lang.Object
The PhysicalMemoryManager
is not ordinarily used by
applications, except that the implementation may require the
application to use the registerFilter(java.lang.Object, javax.realtime.PhysicalMemoryTypeFilter)
method to make the
physical memory manager aware of the memory types on their platform.
The PhysicalMemoryManager
class is primarily intended
for use by the various physical memory accessor objects
(VTPhysicalMemory
, LTPhysicalMemory
, and
ImmortalPhysicalMemory
) to create objects of the types
requested by the application. The physical memory manager is
responsible for finding areas of physical memory with the appropriate
characteristics and access rights, and moderating any required
combination of physical and virtual memory characteristics.
The Physical Memory Manager assumes that the physical adresss
space is linear but not necessarily contiguous. That is, addresses
range from 0 .. MAX_LONG
, but there may be gaps in the
memory space. Some intervals in the range may be filled with removable
memory as well.
The physical memory is partitioned into chunks (pages, segments, etc.). Each chunk of memory has a base address and a length.
Each chunk of memory has certain properties. Some of these
properties may require actions to be performed by the Physical Memory
Manager when the memory is accessed. For example, access to
IO_PAGE
may require the use of special instructions to
even reach the devices, or it may require special code sequences to
ensure proper handling of processor write queues and caches.
Filters tell the Physical Memory Manager about the properties of the memory that are available on the machine by registering with the Physical Memory Manager.
When the program requests a physical memory area with particular properties, the constructor communicates with the Physical Memory Manager through a private interface. The Physical Memory Manager asks the filter whether or not the address specified has the required properties and whether it is free, or asks for a chunk of memory with the requested size.
The Physical Memory Manager then maps the physical memory chunk into virtual memory and locks the virtual memory to the memory chunk, on systems that support virtual memory.
Examples of characteristics that might be specified are DMA
memory, hardware byte swapping, and non-cached access to memory.
Standard "names" for some memory characteristics are included in this
class: DMA, SHARED, ALIGNED, BYTESWAP, and IO_PAGE. Support for
these characteristics is optional, but when they are
supported they must use these names. Additional characteristics may
be supported, but only names defined in this specification may be
visible in the PhysicalMemoryManager
API.
The base implementation will provide a
PhysicalMemoryManager
.
Original Equipment Manufacturers (OEMs) or other interested parties may
provide PhysicalMemoryTypeFilter
classes that allow
additional characteristics of memory devices to be specified.
Modifier and Type | Field and Description |
---|---|
static java.lang.Object |
ALIGNED
Deprecated.
When aligned memory is supported by the implementation,
specify
ALIGNED to identify aligned memory. |
static java.lang.Object |
BYTESWAP
Deprecated.
When automatic byte swapping is supported by the implementation,
specify
BYTESWAP when byte swapping should be used. |
static java.lang.Object |
DMA
Deprecated.
When DMA (Direct Memory Access) memory is supported by the
implementation, specify
DMA to identify DMA memory. |
static java.lang.Object |
IO_PAGE
Deprecated.
When access to the system I/O space is supported by the
implementation, specify
IO_PAGE when I/O space should be
used. |
static java.lang.Object |
SHARED
Deprecated.
When shared memory is supported by the implementation, specify
SHARED to identify shared memory. |
Modifier and Type | Method and Description |
---|---|
static boolean |
isRemovable(long base,
long size)
Deprecated.
Queries the system about the removability of the specified range of memory.
|
static boolean |
isRemoved(long base,
long size)
Deprecated.
Queries the system about the removed state of the specified range
of memory.
|
static void |
onInsertion(long base,
long size,
AsyncEvent ae)
Deprecated.
Registers the specified
AsyncEvent to fire when any memory
in the range is added to the system. |
static void |
onInsertion(long base,
long size,
AsyncEventHandler aeh)
Deprecated.
as of RTSJ 1.0.1 Replace with onInsertion(long, long, AsyncEvent)
|
static void |
onRemoval(long base,
long size,
AsyncEvent ae)
Deprecated.
Registers the specified AE to fire when any memory in the range is
removed from the system.
|
static void |
onRemoval(long base,
long size,
AsyncEventHandler aeh)
Deprecated.
as of RTSJ 1.0.1 Replace with onInsertion(long, long, AsyncEvent)
|
static void |
registerFilter(java.lang.Object name,
PhysicalMemoryTypeFilter filter)
Deprecated.
Registers a memory type filter with the physical memory manager.
|
static void |
removeFilter(java.lang.Object name)
Deprecated.
Removes the identified filter from the set of registered filters.
|
static boolean |
unregisterInsertionEvent(long base,
long size,
AsyncEvent ae)
Deprecated.
Unregisters the specified insertion event.
|
static boolean |
unregisterRemovalEvent(long base,
long size,
AsyncEvent ae)
Deprecated.
Unregisters the specified removal event.
|
public static final java.lang.Object ALIGNED
ALIGNED
to identify aligned memory.
This type of memory ignores low-order bits in load and store
accesses to force accesses to fall on natural boundaries for the
access type even when the processor uses a poorly aligned address.RawMemory
public static final java.lang.Object BYTESWAP
BYTESWAP
when byte swapping should be used.
Byte-swapping memory re-orders the bytes in accesses for 16 bits or
more such that little-endian data in memory is accessed as
big-endian, and vice-versa. Such memory would typically be
available in swapped mode in one physical address range and in
un-swapped mode in another address range.RawMemory
public static final java.lang.Object DMA
DMA
to identify DMA memory.
This memory is visible to devices that use DMA. In some systems,
only a portion of the physical address space is available to DMA
devices. On such systems, memory that will be used for DMA must be
allocated from the range of addresses that DMA can reach.RawMemory
public static final java.lang.Object IO_PAGE
IO_PAGE
when I/O space should be
used. Addresses tagged with the name IO_PAGE
are used
for memory mapped I/O devices. Such addresses are almost certainly
not suitable for physical memory, but only for raw memory access.public static final java.lang.Object SHARED
SHARED
to identify shared memory. In a NUMA
(Non-Uniform Memory Access) architecture, processors may make some
part of their local memory available to other processors. This
memory would be tagged with SHARED
, as would memory
that is shared and non-local.
A fully built-out NUMA system might well need
sub-classifications of SHARED
to reflect different
paths to memory. Note that, as with other physical memory names, a
single byte of memory may be visible at several physical addresses
with different access properties at each address. For instance, a
byte of shared memory accesses at address x might be
shared with high-performance access, but without the support of
coherent caches. The same byte accessed at address y
might be shared with coherent cache support, but substantially
longer access times.
public static boolean isRemovable(long base, long size)
base
- The starting address in physical memory.size
- The size of the memory area.true
, when any part of the specified range can be removed.java.lang.IllegalArgumentException
- when size
is
less than zero.SizeOutOfBoundsException
- when base
plus
size
would be greater than the physical addressing
range of the processor.OffsetOutOfBoundsException
- when base
is
less than zero.public static boolean isRemoved(long base, long size)
base
- The starting address in physical memory.size
- The size of the memory area.true
, when any part of the specified range is
currently not usable.java.lang.IllegalArgumentException
- when size
is
less than zero.OffsetOutOfBoundsException
- when base
is
less than zero.SizeOutOfBoundsException
- when base
plus
size
would be greater than the physical addressing
range of the processor.public static void onInsertion(long base, long size, AsyncEvent ae)
AsyncEvent
to fire when any memory
in the range is added to the system. When the specified range of
physical memory contains multiple different types of removable
memory, the AE will be registered with each of them.base
- The starting address in physical memory.size
- The size of the memory area.ae
- The async event to fire.java.lang.IllegalArgumentException
- when ae
is
null
, or when the specified range contains no removable
memory, or when size
is less than zero.OffsetOutOfBoundsException
- when base
is
less than zero.SizeOutOfBoundsException
- when base
plus
size
would be greater than the physical addressing
range of the processor.@Deprecated public static void onInsertion(long base, long size, AsyncEventHandler aeh)
AsyncEventHandler
to run when any
memory in the range is added to the system.
When the specified range of physical memory contains multiple different
types of removable memory, the AEH will be registered with each of them.
When the size or the base is less than 0, unregisters all
"onInsertion" references to the handler.
Note that this method only removes handlers that were registered with the same method. It has no effect on handlers that were registered using an associated async event.
base
- The starting address in physical memory.size
- The size of the memory area.aeh
- The handler to register.java.lang.IllegalArgumentException
- when aeh
is
null
, or when the specified range contains no removable
memory, or when aeh
is null
and
size
and base
are both greater
than or equal to zero.SizeOutOfBoundsException
- when base
plus
size
would be greater than the physical addressing
range of the processor.public static void onRemoval(long base, long size, AsyncEvent ae)
base
- The starting address in physical memory.size
- The size of the memory area.ae
- The async event to register.java.lang.IllegalArgumentException
- when the specified
range contains no removable memory, when ae
is
null
, or when size
is less than zero.OffsetOutOfBoundsException
- when base
is
less than zero.SizeOutOfBoundsException
- when base
plus
size
would be greater than the physical addressing
range of the processor.@Deprecated public static void onRemoval(long base, long size, AsyncEventHandler aeh)
size
or
base
is less than 0, unregisters all "onRemoval"
references to the handler parameter.
Note that this method only removes handlers that were registered with the same method. It has no effect on handlers that were registered using an associated async event.
base
- The starting address in physical memory.size
- The size of the memory area.aeh
- The handler to register.java.lang.IllegalArgumentException
- when the specified range
contains no removable memory, or when aeh
is
null
and size
and base
are both
greater than or equal to zero.SizeOutOfBoundsException
- when base
plus
size
would be greater than the physical addressing
range of the processor.public static final void registerFilter(java.lang.Object name, PhysicalMemoryTypeFilter filter) throws DuplicateFilterException
Values of name
are compared using reference equality
(==) not value equality (equals()
).
name
- The type of memory handled by this filter.filter
- The filter object.DuplicateFilterException
- when a filter for this type
of memory already exists.ResourceLimitError
- when the system is configured for
a bounded number of filters. This filter exceeds the bound.java.lang.IllegalArgumentException
- when the name parameter is
an array of objects, when the name and filter are not both in
immortal memory, or when either name
or
filter
is null
.StaticSecurityException
- when this operation is not permitted.public static final void removeFilter(java.lang.Object name)
Values of name
are compared using reference equality
(==) not value equality (equals()
).
name
- The identifying object for this memory attribute.java.lang.IllegalArgumentException
- when name
is null
.StaticSecurityException
- when this operation is not permitted.public static boolean unregisterInsertionEvent(long base, long size, AsyncEvent ae)
ae
of null
matches all
values of ae
and will unregister every ae
that matches the address range.
Note that this method has no effect on handlers registered directly as async event handlers.
base
- The starting address in physical memory associated with
ae
.size
- The size of the memory area associated with ae
.ae
- The event to unregister.true
, when at least one event matched the pattern,
false
, when no such event was found.java.lang.IllegalArgumentException
- when
size
is less than 0.OffsetOutOfBoundsException
- when base
is
less than zero.SizeOutOfBoundsException
- when base
plus
size
would be greater than the physical addressing
range of the processor.public static boolean unregisterRemovalEvent(long base, long size, AsyncEvent ae)
ae
of null
matches all
values of ae
and will unregister every ae
that matches the address range.
Note that this method has no effect on handlers registered directly as async event handlers.
base
- The starting address in physical memory associated with
ae
.size
- The size of the memory area associated with ae
.ae
- The async event to unregister.true
, when at least one event matched the pattern,
false
, when no such event was found.java.lang.IllegalArgumentException
- when size
is less than 0.OffsetOutOfBoundsException
- when base
is less than zero.SizeOutOfBoundsException
- when base
plus
size
would be greater than the physical addressing
range of the processor.