javax.realtime
Class PhysicalMemoryManager

java.lang.Object
  extended by javax.realtime.PhysicalMemoryManager

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, ImmortalPhysicalMemory, RawMemoryAccess and RawMemoryFloatAccess) 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.

Examples of characteristics that might be specified are: DMA memory, hardware byte swapping, non-cached access to memory, etc. 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 if 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 or other interested parties may provide PhysicalMemoryTypeFilter classes that allow additional characteristics of memory devices to be specified.

Memory attributes that are configured may not be compatible with one another. For instance, copy-back cache enable may be incompatible with execute-only. In this case, the implementation of memory filters may detect conflicts and throw a MemoryTypeConflictException, but since filters are not part of the normative RTSJ, this exception is only advisory.

Field Summary
static java.lang.Object ALIGNED
          If aligned memory is supported by the implementation specify ALIGNED to identify aligned memory.
static java.lang.Object BYTESWAP
          If automatic byte swapping is supported by the implementation specify BYTESWAP if byte swapping should be used.
static java.lang.Object DMA
          If DMA memory is supported by the implementation, specify DMA to identify DMA memory.
static java.lang.Object IO_PAGE
          If access to the system I/O space is supported by the implementation specify IO_PAGE if I/O space should be used.
static java.lang.Object SHARED
          If shared memory is supported by the implementation specify SHARED to identify shared memory.
 
Method Summary
static boolean isRemovable(long base, long size)
          Queries the system about the removability of the specified range of memory.
static boolean isRemoved(long base, long size)
          Queries the system about the removed state of the specified range of memory.
static void onInsertion(long base, long size, AsyncEvent ae)
          Register 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. 1.0.1 Replace with onInsertion(long, long, AsyncEvent)
static void onRemoval(long base, long size, AsyncEvent ae)
          Register 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. 1.0.1
static void registerFilter(java.lang.Object name, PhysicalMemoryTypeFilter filter)
          Register a memory type filter with the physical memory manager.
static void removeFilter(java.lang.Object name)
          Remove the identified filter from the set of registered filters.
static boolean unregisterInsertionEvent(long base, long size, AsyncEvent ae)
          Unregister the specified insertion event.
static boolean unregisterRemovalEvent(long base, long size, AsyncEvent ae)
          Unregister the specified removal event.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ALIGNED

public static final java.lang.Object ALIGNED
If aligned memory is supported by the implementation specify ALIGNED to identify aligned memory.

BYTESWAP

public static final java.lang.Object BYTESWAP
If automatic byte swapping is supported by the implementation specify BYTESWAP if byte swapping should be used.

DMA

public static final java.lang.Object DMA
If DMA memory is supported by the implementation, specify DMA to identify DMA memory.

IO_PAGE

public static final java.lang.Object IO_PAGE
If access to the system I/O space is supported by the implementation specify IO_PAGE if I/O space should be used.

Since:
1.0.1

SHARED

public static final java.lang.Object SHARED
If shared memory is supported by the implementation specify SHARED to identify shared memory.

Method Detail

isRemovable

public static boolean isRemovable(long base,
                                  long size)
Queries the system about the removability of the specified range of memory.

Parameters:
base - The starting address in physical memory.
size - The size of the memory area.
Returns:
true if any part of the specified range can be removed.
Throws:
java.lang.IllegalArgumentException - Thrown if size is less than zero.
SizeOutOfBoundsException - Thrown if base plus size would be greater than the physical addressing range of the processor.
OffsetOutOfBoundsException - Thrown if base is less than zero.

isRemoved

public static boolean isRemoved(long base,
                                long size)
Queries the system about the removed state of the specified range of memory. This method is used for devices that lie in the memory address space and can be removed while the system is running. (Such as PC cards).

Parameters:
base - The starting address in physical memory.
size - The size of the memory area.
Returns:
true if any part of the specified range is currently not usable.
Throws:
java.lang.IllegalArgumentException - Thrown if size is less than zero.
OffsetOutOfBoundsException - Thrown if base is less than zero.
SizeOutOfBoundsException - Thrown if base plus size would be greater than the physical addressing range of the processor.

onInsertion

public static void onInsertion(long base,
                               long size,
                               AsyncEvent ae)
Register the specified AsyncEvent to fire when any memory in the range is added to the system. If the specified range of physical memory contains multiple different types of removable memory, the AE will be registered with each of them.

Parameters:
base - The starting address in physical memory.
size - The size of the memory area.
ae - The async event to fire.
Throws:
java.lang.IllegalArgumentException - Thrown if ae is null, or if the specified range contains no removable memory, or if size is less than zero.
OffsetOutOfBoundsException - Thrown if base is less than zero.
SizeOutOfBoundsException - Thrown if base plus size would be greater than the physical addressing range of the processor.
Since:
1.0.1

onInsertion

public static void onInsertion(long base,
                               long size,
                               AsyncEventHandler aeh)
Deprecated. 1.0.1 Replace with onInsertion(long, long, AsyncEvent)

Register the specified AsyncEventHandler to run when any memory in the range is added to the system. If the specified range of physical memory contains multiple different types of removable memory, the AEH will be registered with each of them. If the size or the base is less than 0, unregister all "onInsertion" references to the handler.

Note: 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.

Parameters:
base - The starting address in physical memory.
size - The size of the memory area.
aeh - The handler to register.
Throws:
java.lang.IllegalArgumentException - Thrown if aeh is null, or if the specified range contains no removable memory, or if aeh is null and size and base are both greater than or equal to zero.
SizeOutOfBoundsException - Thrown if base plus size would be greater than the physical addressing range of the processor.

onRemoval

public static void onRemoval(long base,
                             long size,
                             AsyncEvent ae)
Register the specified AE to fire when any memory in the range is removed from the system. If the specified range of physical memory contains multiple different types of removable memory, the AE will be registered with each of them.

Parameters:
base - The starting address in physical memory.
size - The size of the memory area.
ae - The async event to register.
Throws:
java.lang.IllegalArgumentException - Thrown if the specified range contains no removable memory, if ae is null, or if size is less than zero.
OffsetOutOfBoundsException - Thrown if base is less than zero.
SizeOutOfBoundsException - Thrown if base plus size would be greater than the physical addressing range of the processor.
Since:
1.0.1

onRemoval

public static void onRemoval(long base,
                             long size,
                             AsyncEventHandler aeh)
Deprecated. 1.0.1

Register the specified AEH to run when any memory in the range is removed from the system. If the specified range of physical memory contains multiple different types of removable memory, the AEH will be registered with each of them. If size or base is less than 0, unregister all "onRemoval" references to the handler parameter.

Note: 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.

Parameters:
base - The starting address in physical memory.
size - The size of the memory area.
aeh - The handler to register.
Throws:
java.lang.IllegalArgumentException - Thrown if the specified range contains no removable memory, or if aeh is null and size and base are both greater than or equal to zero.
SizeOutOfBoundsException - Thrown if base plus size would be greater than the physical addressing range of the processor.

registerFilter

public static final void registerFilter(java.lang.Object name,
                                        PhysicalMemoryTypeFilter filter)
                                 throws DuplicateFilterException
Register a memory type filter with the physical memory manager.

Values of name are compared using reference equality (==) not value equality (equals()).

Parameters:
name - The type of memory handled by this filter.
filter - The filter object.
Throws:
DuplicateFilterException - Thrown if a filter for this type of memory already exists.
ResourceLimitError - Thrown if the system is configured for a bounded number of filters. This filter exceeds the bound.
java.lang.IllegalArgumentException - Thrown if the name parameter is an array of objects, if the name and filter are not both in immortal memory, or if either name or filter is null.
java.lang.SecurityException - Thrown if this operation is not permitted.

removeFilter

public static final void removeFilter(java.lang.Object name)
Remove the identified filter from the set of registered filters. If the filter is not registered, silently do nothing.

Values of name are compared using reference equality (==) not value equality (equals()).

Parameters:
name - The identifying object for this memory attribute.
Throws:
java.lang.IllegalArgumentException - Thrown if name is null.
java.lang.SecurityException - Thrown if this operation is not permitted.

unregisterInsertionEvent

public static boolean unregisterInsertionEvent(long base,
                                               long size,
                                               AsyncEvent ae)
Unregister the specified insertion event. The event is only unregistered if all three arguments match the arguments used to register the event, except that ae of null matches all values of ae and will unregister every ae that matches the address range.

Note: This method has no effect on handlers registered directly as async event handlers.

Parameters:
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.
Returns:
True if at least one event matched the pattern, false if no such event was found.
Throws:
java.lang.IllegalArgumentException - Thrown if size is less than 0.
OffsetOutOfBoundsException - Thrown if base is less than zero.
SizeOutOfBoundsException - Thrown if base plus size would be greater than the physical addressing range of the processor.
Since:
1.0.1

unregisterRemovalEvent

public static boolean unregisterRemovalEvent(long base,
                                             long size,
                                             AsyncEvent ae)
Unregister the specified removal event. The async event is only unregistered if all three arguments match the arguments used to register the event, except that ae of null matches all values of ae and will unregister every ae that matches the address range.

Note: This method has no effect on handlers registered directly as async event handlers.

Parameters:
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.
Returns:
True if at least one event matched the pattern, false if no such event was found.
Throws:
java.lang.IllegalArgumentException - Thrown if size is less than 0.
OffsetOutOfBoundsException - Thrown if base is less than zero.
SizeOutOfBoundsException - Thrown if base plus size would be greater than the physical addressing range of the processor.
Since:
1.0.1