001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package org.apache.harmony.luni.platform;
019:
020: import java.io.IOException;
021:
022: /**
023: * IMemorySystem
024: *
025: */
026: public interface IMemorySystem {
027:
028: public final int MMAP_READ_ONLY = 1;
029:
030: public final int MMAP_READ_WRITE = 2;
031:
032: public final int MMAP_WRITE_COPY = 4;
033:
034: /**
035: * Answers true if the platform is little endian, otherwise it may be
036: * assumed to be big endian..
037: *
038: * @return true if the platform is little endian.
039: */
040: public boolean isLittleEndian();
041:
042: /**
043: * Answers the platform pointer size.
044: *
045: * @return the native platform pointer size, in bytes.
046: */
047: public int getPointerSize();
048:
049: /**
050: * Allocates and returns a pointer to space for a memory block of
051: * <code>length</code> bytes. The space is uninitialized and may be larger
052: * than the number of bytes requested; however, the guaranteed usable memory
053: * block is exactly <code>length</code> bytes long.
054: *
055: * @param length
056: * number of bytes requested.
057: * @return the address of the start of the memory block.
058: * @throws OutOfMemoryError
059: * if the request cannot be satisfied.
060: */
061: public long malloc(long length) throws OutOfMemoryError;
062:
063: /**
064: * Deallocates space for a memory block that was previously allocated by a
065: * call to {@link #malloc(long) malloc(long)}. The number of bytes freed is
066: * identical to the number of bytes acquired when the memory block was
067: * allocated. If <code>address</code> is zero the method does nothing.
068: * <p>
069: * Freeing a pointer to a memory block that was not allocated by
070: * <code>malloc()</code> has unspecified effect.
071: * </p>
072: *
073: * @param address
074: * the address of the memory block to deallocate.
075: */
076: public void free(long address);
077:
078: /**
079: * Places <code>value</code> into first <code>length</code> bytes of the
080: * memory block starting at <code>address</code>.
081: * <p>
082: * The behavior is unspecified if
083: * <code>(address ... address + length)</code> is not wholly within the
084: * range that was previously allocated using <code>malloc()</code>.
085: * </p>
086: *
087: * @param address
088: * the address of the first memory location.
089: * @param value
090: * the byte value to set at each location.
091: * @param length
092: * the number of byte-length locations to set.
093: */
094: public void memset(long address, byte value, long length);
095:
096: /**
097: * Copies <code>length</code> bytes from <code>srcAddress</code> to
098: * <code>destAddress</code>. Where any part of the source memory block
099: * and the destination memory block overlap <code>memmove()</code> ensures
100: * that the original source bytes in the overlapping region are copied
101: * before being overwritten.
102: * <p>
103: * The behavior is unspecified if
104: * <code>(srcAddress ... srcAddress + length)</code> and
105: * <code>(destAddress ... destAddress + length)</code> are not both wholly
106: * within the range that was previously allocated using
107: * <code>malloc()</code>.
108: * </p>
109: *
110: * @param destAddress
111: * the address of the destination memory block.
112: * @param srcAddress
113: * the address of the source memory block.
114: * @param length
115: * the number of bytes to move.
116: */
117: public void memmove(long destAddress, long srcAddress, long length);
118:
119: /**
120: * Copies <code>length</code> bytes from the memory block at
121: * <code>address</code> into the byte array <code>bytes</code> starting
122: * at element <code>offset</code> within the byte array.
123: * <p>
124: * The behavior of this method is undefined if the range
125: * <code>(address ... address + length)</code> is not within a memory
126: * block that was allocated using {@link #malloc(long) malloc(long)}.
127: * </p>
128: *
129: * @param address
130: * the address of the OS memory block from which to copy bytes.
131: * @param bytes
132: * the byte array into which to copy the bytes.
133: * @param offset
134: * the index of the first element in <code>bytes</code> that
135: * will be overwritten.
136: * @param length
137: * the total number of bytes to copy into the byte array.
138: * @throws NullPointerException
139: * if <code>bytes</code> is <code>null</code>.
140: * @throws IndexOutOfBoundsException
141: * if <code>offset + length > bytes.length</code>.
142: */
143: public void getByteArray(long address, byte[] bytes, int offset,
144: int length) throws NullPointerException,
145: IndexOutOfBoundsException;
146:
147: /**
148: * Copies <code>length</code> bytes from the byte array <code>bytes</code>
149: * into the memory block at <code>address</code>, starting at element
150: * <code>offset</code> within the byte array.
151: * <p>
152: * The behavior of this method is undefined if the range
153: * <code>(address ... address + length)</code> is not within a memory
154: * block that was allocated using {@link #malloc(long) malloc(long)}.
155: * </p>
156: *
157: * @param address
158: * the address of the OS memory block into which to copy the
159: * bytes.
160: * @param bytes
161: * the byte array from which to copy the bytes.
162: * @param offset
163: * the index of the first element in <code>bytes</code> that
164: * will be read.
165: * @param length
166: * the total number of bytes to copy from <code>bytes</code>
167: * into the memory block.
168: * @throws NullPointerException
169: * if <code>bytes</code> is <code>null</code>.
170: * @throws IndexOutOfBoundsException
171: * if <code>offset + length > bytes.length</code>.
172: */
173: public void setByteArray(long address, byte[] bytes, int offset,
174: int length) throws NullPointerException,
175: IndexOutOfBoundsException;
176:
177: // Primitive get & set methods
178: public byte getByte(long address);
179:
180: /**
181: * Sets the given single byte value at the given address.
182: * <p>
183: * The behavior is unspecified if <code>address</code> is not in the range
184: * that was previously allocated using <code>malloc()</code>.
185: * </p>
186: *
187: * @param address
188: * the address at which to set the byte value.
189: * @param value
190: * the value to set.
191: */
192: public void setByte(long address, byte value);
193:
194: /**
195: * Gets the value of the signed two-byte integer stored in platform byte
196: * order at the given address.
197: * <p>
198: * The behavior is unspecified if <code>(address ... address + 2)</code>
199: * is not wholly within the range that was previously allocated using
200: * <code>malloc()</code>.
201: * </p>
202: *
203: * @param address
204: * the platform address of the start of the two-byte value.
205: * @return the value of the two-byte integer as a Java <code>short</code>.
206: */
207: public short getShort(long address);
208:
209: public short getShort(long address, Endianness endianness);
210:
211: /**
212: * Sets the value of the signed two-byte integer at the given address in
213: * platform byte order.
214: * <p>
215: * The behavior is unspecified if <code>(address ... address + 2)</code>
216: * is not wholly within the range that was previously allocated using
217: * <code>malloc()</code>.
218: * </p>
219: *
220: * @param address
221: * the platform address of the start of the two-byte value.
222: * @param value
223: * the value of the two-byte integer as a Java <code>short</code>.
224: */
225: public void setShort(long address, short value);
226:
227: public void setShort(long address, short value,
228: Endianness endianness);
229:
230: /**
231: * Gets the value of the signed four-byte integer stored in platform
232: * byte-order at the given address.
233: * <p>
234: * The behavior is unspecified if <code>(address ... address + 4)</code>
235: * is not wholly within the range that was previously allocated using
236: * <code>malloc()</code>.
237: * </p>
238: *
239: * @param address
240: * the platform address of the start of the four-byte value.
241: * @return the value of the four-byte integer as a Java <code>int</code>.
242: */
243: public int getInt(long address);
244:
245: public int getInt(long address, Endianness endianness);
246:
247: /**
248: * Sets the value of the signed four-byte integer at the given address in
249: * platform byte order.
250: * <p>
251: * The behavior is unspecified if <code>(address ... address + 4)</code>
252: * is not wholly within the range that was previously allocated using
253: * <code>malloc()</code>.
254: * </p>
255: *
256: * @param address
257: * the platform address of the start of the four-byte value.
258: * @param value
259: * the value of the four-byte integer as a Java <code>int</code>.
260: */
261: public void setInt(long address, int value);
262:
263: public void setInt(long address, int value, Endianness endianness);
264:
265: /**
266: * Gets the value of the signed eight-byte integer stored in platform byte
267: * order at the given address.
268: * <p>
269: * The behavior is unspecified if <code>(address ... address + 8)</code>
270: * is not wholly within the range that was previously allocated using
271: * <code>malloc()</code>.
272: * </p>
273: *
274: * @param address
275: * the platform address of the start of the eight-byte value.
276: * @return the value of the eight-byte integer as a Java <code>long</code>.
277: */
278: public long getLong(long address);
279:
280: public long getLong(long address, Endianness endianness);
281:
282: /**
283: * Sets the value of the signed eight-byte integer at the given address in
284: * the platform byte order.
285: * <p>
286: * The behavior is unspecified if <code>(address ... address + 8)</code>
287: * is not wholly within the range that was previously allocated using
288: * <code>malloc()</code>.
289: * </p>
290: *
291: * @param address
292: * the platform address of the start of the eight-byte value.
293: * @param value
294: * the value of the eight-byte integer as a Java
295: * <code>long</code>.
296: */
297: public void setLong(long address, long value);
298:
299: public void setLong(long address, long value, Endianness endianness);
300:
301: /**
302: * Gets the value of the IEEE754-format four-byte float stored in platform
303: * byte order at the given address.
304: * <p>
305: * The behavior is unspecified if <code>(address ... address + 4)</code>
306: * is not wholly within the range that was previously allocated using
307: * <code>malloc()</code>.
308: * </p>
309: *
310: * @param address
311: * the platform address of the start of the eight-byte value.
312: * @return the value of the four-byte float as a Java <code>float</code>.
313: */
314: public float getFloat(long address);
315:
316: public float getFloat(long address, Endianness endianness);
317:
318: /**
319: * Sets the value of the IEEE754-format four-byte float stored in platform
320: * byte order at the given address.
321: * <p>
322: * The behavior is unspecified if <code>(address ... address + 4)</code>
323: * is not wholly within the range that was previously allocated using
324: * <code>malloc()</code>.
325: * </p>
326: *
327: * @param address
328: * the platform address of the start of the eight-byte value.
329: * @param value
330: * the value of the four-byte float as a Java <code>float</code>.
331: */
332: public void setFloat(long address, float value);
333:
334: public void setFloat(long address, float value,
335: Endianness endianness);
336:
337: /**
338: * Gets the value of the IEEE754-format eight-byte float stored in platform
339: * byte order at the given address.
340: * <p>
341: * The behavior is unspecified if <code>(address ... address + 8)</code>
342: * is not wholly within the range that was previously allocated using
343: * <code>malloc()</code>.
344: * </p>
345: *
346: * @param address
347: * the platform address of the start of the eight-byte value.
348: * @return the value of the eight-byte float as a Java <code>double</code>.
349: */
350: public double getDouble(long address);
351:
352: public double getDouble(long address, Endianness endianness);
353:
354: /**
355: * Sets the value of the IEEE754-format eight-byte float store in platform
356: * byte order at the given address.
357: * <p>
358: * The behavior is unspecified if <code>(address ... address + 8)</code>
359: * is not wholly within the range that was previously allocated using
360: * <code>malloc()</code>.
361: * </p>
362: *
363: * @param address
364: * the platform address of the start of the eight-byte value.
365: * @param value
366: * the value of the eight-byte float as a Java
367: * <code>double</code>.
368: */
369: public void setDouble(long address, double value);
370:
371: public void setDouble(long address, double value,
372: Endianness endianness);
373:
374: /**
375: * Gets the value of the platform pointer at the given address.
376: * <p>
377: * The length of the platform pointer is defined by
378: * <code>POINTER_SIZE</code>.
379: * </p>
380: * The behavior is unspecified if
381: * <code>(address ... address + POINTER_SIZE)</code> is not wholly within
382: * the range that was previously allocated using <code>malloc()</code>.
383: * </p>
384: *
385: * @param address
386: * the platform address of the start of the platform pointer.
387: * @return the value of the platform pointer as a Java <code>long</code>.
388: */
389: public long getAddress(long address);
390:
391: /**
392: * Sets the value of the platform pointer at the given address.
393: * <p>
394: * The length of the platform pointer is defined by
395: * <code>POINTER_SIZE</code>. This method only sets
396: * <code>POINTER_SIZE</code> bytes at the given address.
397: * </p>
398: * The behavior is unspecified if
399: * <code>(address ... address + POINTER_SIZE)</code> is not wholly within
400: * the range that was previously allocated using <code>malloc()</code>.
401: * </p>
402: *
403: * @param address
404: * the platform address of the start of the platform pointer.
405: * @param value
406: * the value of the platform pointer as a Java <code>long</code>.
407: */
408: public void setAddress(long address, long value);
409:
410: /**
411: * TODO: JavaDoc
412: *
413: * @param fileDescriptor
414: * @param alignment
415: * @param size
416: * @param mapMode
417: * @return
418: * @throws IOException
419: */
420: public long mmap(long fileDescriptor, long alignment, long size,
421: int mapMode) throws IOException;
422:
423: /**
424: * TODO: JavaDoc
425: *
426: * @param addr
427: * @throws IOException
428: */
429: public void unmap(long addr, long size);
430:
431: /**
432: * TODO: JavaDoc
433: */
434: public void load(long addr, long size);
435:
436: /**
437: * TODO: JavaDoc
438: */
439: public boolean isLoaded(long addr, long size);
440:
441: /**
442: * TODO : JavaDoc
443: */
444: public void flush(long addr, long size);
445:
446: }
|