001 // RawMemoryAccess.java, created by wbeebee
002 // Copyright (C) 2001 Wes Beebee <wbeebee@mit.edu>
003 // Licensed under the terms of the GNU GPL; see COPYING for details.
004 package javax.realtime;
005
006 /** An instance of <code>RawMemoryAccess</code> models a range of
007 * physical memory as a fixed sequence of bytes. A full complement
008 * of accessor methods allow the contents of the physical area to
009 * be accessed through offsets from the base, interpreted as byte,
010 * short, int, or long data values or as arrays of these types.
011 * <p>
012 * Whether the offset addresses the high-order of low-order byte
013 * is based on the value of the <code>BYTE_ORDER</code> static
014 * boolean variable in class <code>RealtimeSystem</code>.
015 * The <code>RawMemoryAccess</code> class allows a real-time
016 * program to implement device drivers, memory-mapped I/O, flash
017 * memory, battery-backed RAM, and similar low-level software.
018 * <p>
019 * A raw memory area cannot contain references to Java objects.
020 * Such a capability would be unsafe (since it could be used to
021 * defeat Java's type checking) and error-prone (since it is
022 * sensitive to the specific representational choices made by
023 * the Java compiler).
024 * <p>
025 * Many of the constructors and methods in this class throw
026 * <code>OffsetOutOfBoundsException</code>. This exception means
027 * that the value given in the offset parameter is either negative
028 * or outside the memory area.
029 * <p>
030 * Many of the constructors and methods in this class throw
031 * <code>SizeOutOfBoundsException</code>. This exception means
032 * that the value given in the size parameter is either negative,
033 * larger than an allowable range, or would cause an accessor
034 * method to access an address outside of the memory area.
035 * <p>
036 * Unlike other integral parameters in this chapter, negative
037 * values are valid for <code>byte, short, int</code> and
038 * <code>long</code> values that are copied in and out of memory
039 * by the <code>set</code> and <code>get</code> methods of this class.
040 */
041 public class RawMemoryAccess {
042
043 private long base, size;
044 private Runnable logic;
045
046 /** Construct an instance of <code>RawMemoryAccess</code> with the given parameters.
047 *
048 * @param type An <code>Object</code> representing the type of memory required.
049 * Used to define the base address and control the mapping.
050 * @param size The size of the area in bytes.
051 * @throws java.lang.SecurityException The application doesn't have permissions
052 * to access physical memory or the given
053 * type of memory.
054 * @throws OffsetOutOfBoundsException The address is invalid.
055 * @throws UnsupportedPhysicalMemoryException Thrown if the underlying hardwre does
056 * not support the given type.
057 * @throws MemoryTypeConflictException The specified base does not point to memory
058 * that matches the request type, or if
059 * <code>type</code> specifies attributes with
060 * a conflict.
061 * @throws MemoryInUseException The specified memory is already in use.
062 */
063 public RawMemoryAccess(Object type, long size)
064 throws SecurityException, OffsetOutOfBoundsException,
065 SizeOutOfBoundsException,
066 UnsupportedPhysicalMemoryException,
067 MemoryTypeConflictException {
068 // TODO
069 }
070
071 /** Construct an instance of <code>RawMemoryAccess</code> with the given parameters.
072 *
073 * @param type An <code>Object</code> representing the type of memory required.
074 * Used to define the base address and control the mapping.
075 * @param base The physical memory address of the region.
076 * @param size The size of the area in bytes.
077 * @throws java.lang.SecurityException The application doesn't have permissions
078 * to access physical memory or the given
079 * type of memory.
080 * @throws OffsetOutOfBoundsException The address is invalid.
081 * @throws UnsupportedPhysicalMemoryException Thrown if the underlying hardwre does
082 * not support the given type.
083 * @throws MemoryTypeConflictException The specified base does not point to memory
084 * that matches the request type, or if
085 * <code>type</code> specifies attributes with
086 * a conflict.
087 * @throws MemoryInUseException The specified memory is already in use.
088 */
089 public RawMemoryAccess(Object type, long base, long size)
090 throws SecurityException, OffsetOutOfBoundsException,
091 SizeOutOfBoundsException,
092 UnsupportedPhysicalMemoryException,
093 MemoryTypeConflictException {
094 this(type, size);
095 this.base = base;
096 }
097
098
099 // CONSTRUCTORS(?) NOT IN SPECS
100
101 protected RawMemoryAccess(long base, long size) {
102
103 }
104
105 /** Constructor reserved for use by the memory object factory. */
106 protected RawMemoryAccess(RawMemoryAccess memory, long base, long size) {
107
108 }
109
110 public static RawMemoryAccess create(Object type, long size) {
111 /** Completely bogus */
112 return new RawMemoryAccess(100, size);
113 }
114
115 public static RawMemoryAccess create(Object type, long base,
116 long size) {
117 return new RawMemoryAccess(base, size);
118 }
119
120
121 // METHODS IN SPECS
122
123 /** Get the byte at the given offset.
124 *
125 * @param offset The offset at which to read the byte.
126 * @return The byte read.
127 * @throws OffsetOutOfBoundsException The offset is invalid.
128 * @throws SizeOutOfBoundsException The size is negative or extends into
129 * an invalid address range.
130 */
131 public byte getByte(long offset)
132 throws OffsetOutOfBoundsException, SizeOutOfBoundsException {
133 // TODO
134
135 return 0;
136 }
137
138 /** Gets <code>nunber</code> bytes starting at the given offset and
139 * assign them to the byte array starting at the position
140 * <code>low</code>.
141 *
142 * @param offset The offset at which to start reading.
143 * @param bytes The array into which the read items are placed.
144 * @param low the offset which is the starting point in the given array for
145 * the read items to be placed.
146 * @param number The number of items to read.
147 * @return The integer read.
148 * @throws OffsetOutOfBoundsException The offset is invalid.
149 * @throws SizeOutOfBoundsException The size is negative or extends into
150 * an invalid address range.
151 */
152 public void getBytes(long offset, byte[] bytes, int low, int number)
153 throws OffsetOutOfBoundsException, SizeOutOfBoundsException {
154 for (int i = 0; i < number; i++)
155 bytes[low + i] = getByte(offset + i);
156 }
157
158 /** Gets the <code>int</code> at the given offset.
159 *
160 * @param offset The offset at which to read the integer.
161 * @throws OffsetOutOfBoundsException The offset is invalid.
162 * @throws SizeOutOfBoundsException The size is negative or extends into
163 * an invalid address range.
164 */
165 public int getInt(long offset)
166 throws OffsetOutOfBoundsException, SizeOutOfBoundsException {
167 // TODO
168
169 return 0;
170 }
171
172 /** Gets <code>number</code> ints starting at the given offset and
173 * assign them to the int array passed at position <code>low</code>.
174 *
175 * @param offset The offset at which to start reading.
176 * @param ints The array into which the read items are placed.
177 * @param low The offset which is the starting point in the given array for
178 * the read items to be placed.
179 * @param number The number of items to read.
180 * @throws OffsetOutOfBoundsException The offset is invalid.
181 * @throws SizeOutOfBoundsException The size is negative or extends into
182 * an invalid address range.
183 */
184 public void getInts(long offset, int[] ints, int low, int number)
185 throws OffsetOutOfBoundsException, SizeOutOfBoundsException {
186 for (int i = 0; i < number; i++)
187 ints[low + i] = getByte(offset + i);
188 }
189
190 /** Gets the <code>long</code> at the given offset.
191 *
192 * @param offset The offset at which to read the long.
193 * @return The long read.
194 * @throws OffsetOutOfBoundsException The offset is invalid.
195 * @throws SizeOutOfBoundsException The size is negative or extends into
196 * an invalid address range.
197 */
198 public long getLong(long offset)
199 throws OffsetOutOfBoundsException, SizeOutOfBoundsException {
200 // TODO
201
202 return 0;
203 }
204
205 /** Gets <code>number</code> longs starting at the given offset and assign
206 * them to the long array passed starting at position <code>low</code>.
207 *
208 * @param offset The offset at which to start reading.
209 * @param longs The array into which the read items are placed.
210 * @param low The offset which is the starting point in the given array
211 * for the read items to be placed.
212 * @param number The number of items to read.
213 * @throws OffsetOutOfBoundsException The offset is invalid.
214 * @throws SizeOutOfBoundsException The size is negative or extends into
215 * an invalid address range.
216 */
217 public void getLongs(long offset, long[] longs, int low, int number)
218 throws OffsetOutOfBoundsException, SizeOutOfBoundsException {
219 for (int i = 0; i < number; i++)
220 longs[low + i] = getLong(offset + i);
221 }
222
223 /** Gets the virtual memory location at which the memory region is mapped.
224 *
225 * @return The virtual address to which this is mapped (for reference purposes).
226 * Same as the base address if virtual memory is not supported.
227 */
228 public long getMappedAddress() {
229 // TODO
230
231 return 0;
232 }
233
234 /** Gets the <code>short</code> at the given offset.
235 *
236 * @param offset The offset at which to read the short.
237 * @return The short read.
238 * @throws OffsetOutOfBoundsException The offset is invalid.
239 * @throws SizeOutOfBoundsException The size is negative or extends into
240 * an invalid address range.
241 */
242 public short getShort(long offset)
243 throws OffsetOutOfBoundsException, SizeOutOfBoundsException {
244 // TODO
245
246 return 0;
247 }
248
249 /** Gets <code>number</code> shorts starting at the give offset and assign
250 * them to the short array passed starting at position <code>low</code>.
251 *
252 * @param offset The offset at which to start reading.
253 * @param shorts The array into which the read items are placed.
254 * @param low The offset which is the starting point in the given array for
255 * the read items to be placed.
256 * @param number The number of items to read.
257 * @throws OffsetOutOfBoundsException The offset is invalid.
258 * @throws SizeOutOfBoundsException The size is negative or extends into
259 * an invalid address range.
260 */
261 public void getShorts(long offset, short[] shorts, int low, int number)
262 throws OffsetOutOfBoundsException, SizeOutOfBoundsException {
263 for (int i = 0; i < number; i++)
264 shorts[low + i] = getShort(offset + i);
265 }
266
267 /** Maps the physical memory range into virtual memory. No-op if the system
268 * doesn't support virtual memory.
269 */
270 public long map() {
271 // TODO
272
273 return 0;
274 }
275
276 /** Maps the physical memory range into virtual memory at the specified location.
277 * No-op if the system doesn't support virtual memory.
278 *
279 * @param base The location to map at the virtual memory space.
280 * @return The starting point of the virtual memory.
281 */
282 public long map(long base) {
283 // TODO
284
285 return 0;
286 }
287
288 /** Maps the physical memory range into virtual memory. No-op if the system
289 * doesn't support virtual memory.
290 *
291 * @param base The location to map at the virtual memory space.
292 * @param size The size of the block to map in.
293 * @return The starting point of the virtual memory.
294 */
295 public long map(long base, long size) {
296 // TODO
297
298 return 0;
299 }
300
301 /** Sets the byte at the given offset.
302 *
303 * @param offset The offset at which to write the byte.
304 * @param value The byte to write.
305 * @throws OffsetOutOfBoundsException The offset is invalid.
306 * @throws SizeOutOfBoundsException The size is negative or extends into
307 * an invalid address range.
308 */
309 public void setByte(long offset, byte value)
310 throws OffsetOutOfBoundsException, SizeOutOfBoundsException {
311 // TODO
312 }
313
314 /** Sets <code>number</code> bytes starting at the give offset from
315 * the byte array passed starting at position <code>low</code>.
316 *
317 * @param offset The offset at which to start writing.
318 * @param bytes The array from which the items are obtained.
319 * @param low The offset which is the starting point in the given array
320 * for the items to be obtained.
321 * @param number The number of items to write.
322 * @throws OffsetOutOfBoundsException The offset is invalid.
323 * @throws SizeOutOfBoundsException The size is negative or extends into
324 * an invalid address range.
325 */
326 public void setBytes(long offset, byte[] bytes, int low, int number)
327 throws OffsetOutOfBoundsException, SizeOutOfBoundsException {
328 for (int i = 0; i < number; i++)
329 setByte(offset + i, bytes[low + i]);
330 }
331
332 /** Sets the <code>int</code> at the given offset.
333 *
334 * @param offset The offset at which to write the integer.
335 * @param value The integer to write.
336 * @throws OffsetOutOfBoundsException The offset is invalid.
337 * @throws SizeOutOfBoundsException The size is negative or extends into
338 * an invalid address range.
339 */
340 public void setInt(long offset, int value)
341 throws OffsetOutOfBoundsException, SizeOutOfBoundsException {
342 // TODO
343 }
344
345 /** Sets <code>number</code> ints starting at the given offset from
346 * the int array passed starting at position <code>low</code>.
347 *
348 * @param offset The offset at which to start writing.
349 * @param ints The array from which the itmes are obtained.
350 * @param low The offset which is the starting point in the given array
351 * for the items to be obtained.
352 * @param number The number of items to write.
353 * @throws OffsetOutOfBoundsException The offset is invalid.
354 * @throws SizeOutOfBoundsException The size is negative or extends
355 * into an invalid address range.
356 */
357 public void setInts(long offset, int[] ints, int low, int number)
358 throws OffsetOutOfBoundsException, SizeOutOfBoundsException {
359 for (int i = 0; i < number; i++)
360 setInt(offset + i, ints[low + i]);
361 }
362
363 /** Sets the <code>long</code> at the given offset.
364 *
365 * @param offset The offset at which to write the long.
366 * @param value The long to write.
367 * @throws OffsetOutOfBoundsException The offset in invalid.
368 * @throws SizeOutOfBoundsException The size is negative or extends
369 * into an invalid address range.
370 */
371 public void setLong(long offset, long value)
372 throws OffsetOutOfBoundsException, SizeOutOfBoundsException {
373 // TODO
374 }
375
376 /** Sets <code>number</code> longs starting at the given offset from
377 * the long array passed starting at position <code>low</code>.
378 *
379 * @param offset The offset at which to start writing.
380 * @param longs The array from which the items are obtained.
381 * @param low The offset which is the starting point in the given
382 * array for the items to be obtained.
383 * @param number The number of items to write.
384 * @throws OffsetOutOfboundsException The offset is invalid.
385 * @throws SizeOutOfBoundsException The size is negative or extends
386 * into an invalid address range.
387 */
388 public void setLongs(long offset, long[] longs, int low, int number)
389 throws OffsetOutOfBoundsException, SizeOutOfBoundsException {
390 for (int i = 0; i < number; i++)
391 setLong(offset + i, longs[low + i]);
392 }
393
394 /** Sets the <code>short</code> at the given offset.
395 *
396 * @param offset The offset at which to write the short.
397 * @param value The short to write.
398 * @throws OffsetOutOfBoundsException The offset is invalid.
399 * @throws SizeOutOfBoundsException The size is negative or extends
400 * into an invalid address range.
401 */
402 public void setShort(long offset, short value)
403 throws OffsetOutOfBoundsException, SizeOutOfBoundsException {
404 // TODO
405 }
406
407 /** Sets <code>number</code> shorts starting at the given offset from
408 * the short array passed starting at position <code>low</code>.
409 *
410 * @param offset The offset at which to start writing.
411 * @param shorts The array from which the items are obtained.
412 * @param low The offset which is the starting point in the given array
413 * for the items to be obtained.
414 * @param number The number of items to write.
415 * @throws OffsetOutOfBoundsException The offset is invalid.
416 * @throws SizeOutOfBoundsException The size is negative or extends
417 * into an invalid address range.
418 */
419 public void setShorts(long offset, short[] shorts, int low, int number)
420 throws OffsetOutOfBoundsException, SizeOutOfBoundsException {
421 for (int i = 0; i < number; i++)
422 setLong(offset + i, shorts[low + i]);
423 }
424
425 /** Unmap the physical memory range from virtual memory. No-op if the
426 * system doesn't support virtual memory.
427 */
428 public void unmap() {
429 // TODO
430 }
431
432 /** Construct a RawMemoryAccess area at offset bytes from the
433 * base of this area.
434 */
435 public RawMemoryAccess subregion(long offset, long size) {
436 return new RawMemoryAccess(offset, size);
437 }
438 }