001 package javax.realtime;
002
003 /** The <code>PhysicalMemoryManager</code> is available for use
004 * by the various physical memory accessor objects
005 * (<code>VTPhysicalMemory, LTPhysicalMemory, ImmortalPhysicalMemory,
006 * RawMemoryAccess, RawMemoryFloatAccess</code>) to create objects
007 * of the correct type that are bound to areas of physical memory
008 * with the appropriate characteristics -- or with appropriate
009 * accessor behavior. Esxamples of characteristics that might be
010 * specified are: DMA memory, accessors with byte swapping, etc.
011 * <p>
012 * The base implementation will provide a <code>PhysicalMemoryManager</code>
013 * and a set of <code>PhysicalMemoryTypeFilter</code> classes that correctly
014 * identify memory classes that are standard for the (OS, JVM, and processor)
015 * platform.
016 * <p>
017 * OEMs may provide a <code>PhysicalMemoryTypeFilter</code> classes that allow
018 * additional characteristics of memory devices to be specified.
019 * <p>
020 * Memory attributes that are configured may not be compatible with one another.
021 * For instance, copy-back cache enable may be imcompatible with execute-only.
022 * In this case, the implementation of memory filters may detect conflicts and
023 * throw a <code>MemoryTypeConflictException</code>, but since filters are not
024 * part of the normative RTSJ, this exception is at best advisory.
025 */
026 public final class PhysicalMemoryManager {
027 /** Specify this to identify aligned memory. */
028 public static final String ALIGNED = "ALIGNED";
029
030 /** Specify this if byte swapping should be used. */
031 public static final String BYTESWAP = "BYTESWAP";
032
033 /** Specify this to identify DMA memory. */
034 public static final String DMA = "DMA";
035
036 /** Specify this to identify shared memory. */
037 public static final String SHARED = "SHARED";
038
039
040 public PhysicalMemoryManager() {}
041
042 /** Queries the system about the removability of the specified range
043 * of memory.
044 *
045 * @param base The starting address in physical memory.
046 * @param size The size of the memory area.
047 */
048 public static boolean isRemovable(long address, long size) {
049 // TODO
050
051 return false;
052 }
053
054 /** Queries the system about the removed state of the specified range
055 * of memory. This method is used for devices that lien in the
056 * memory address space and can be removed while the system is
057 * running (such as PC cards).
058 *
059 * @param base The starting address in physical memory.
060 * @param size The size of the memory area.
061 * @return True, if any part of the specified range is currently not usable.
062 */
063 public static boolean isRemoved(long address, long size) {
064 // TODO
065
066 return false;
067 }
068
069 /** Register the specified <code>AsyncEventHandler</code> to run when any
070 * memory in the range is added to the system. If the specified range of
071 * physical memory contains multiple different types of removable memory,
072 * the <code>AsyncEventHandler</code> will be registered with any one of
073 * them. If the size or the base is less than zero, unregister all "remove"
074 * references to the handler.
075 *
076 * @param base The starting address in physical memory.
077 * @param size The size of the memory area.
078 * @param aeh The handler to register.
079 */
080 public static void onInsertion(long base, long size,
081 AsyncEventHandler aeh) {
082 // TODO
083 }
084
085 /** Register the specified <code>AsyncEventHandler</code> to run when any
086 * memory in the range is removed from the system. If the specified range
087 * of physical memory contains multiple different types of removable memory,
088 * the <code>aeh</code> will be registered with any one of them. If the size
089 * or the base is less than zero, remove all "remove" references to the
090 * handler parameter.
091 *
092 * @param base The starting address in physical memory.
093 * @param size The size of the memory area.
094 * @param aeh The handler to register.
095 */
096 public static void onRemoval(long base, long size,
097 AsyncEventHandler aeh)
098 throws IllegalArgumentException {
099 // TODO
100 }
101
102 /** Register a memory type filter with the physical memory manager.
103 *
104 * @param name The type of memory handled by this filter.
105 * @param filter The filter object
106 * @throws DuplicateFilterException A filter for this type of memory already exists.
107 * @throws java.lang.RuntimeException The system is configured for a bounded number
108 * of filters. This filter exceeds the bound.
109 * @throws java.lang.IllegalArgumentException The name parameter must not be an
110 * array of objects.
111 * @throws java.lang.IllegalArgumentException The name and filter must both be in
112 * immortal memory.
113 */
114 public static final void registerFilter(Object name,
115 PhysicalMemoryTypeFilter filter)
116 throws DuplicateFilterException, IllegalArgumentException {
117 // TODO
118 }
119
120 /** Remove the identified filter from the set of registered filters. */
121 public static final void removeFilter(Object name) {
122 // TODO
123 }
124 }