Mercurial > hg > graal-compiler

comparison agent/src/share/classes/sun/jvm/hotspot/debugger/Address.java @ 0:a61af66fc99e jdk7-b24

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Initial load
author duke
date Sat, 01 Dec 2007 00:00:00 +0000
parents
children ba764ed4b6f2
comparison
equal deleted inserted replaced
-1:000000000000 0:a61af66fc99e
1 /*
2 * Copyright 2000-2002 Sun Microsystems, Inc. All Rights Reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.
8 *
9 * This code is distributed in the hope that it will be useful, but WITHOUT
10 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
12 * version 2 for more details (a copy is included in the LICENSE file that
13 * accompanied this code).
14 *
15 * You should have received a copy of the GNU General Public License version
16 * 2 along with this work; if not, write to the Free Software Foundation,
17 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
18 *
19 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
20 * CA 95054 USA or visit www.sun.com if you need additional information or
21 * have any questions.
22 *
23 */
24
25 package sun.jvm.hotspot.debugger;
26
27 /** <P> This is the bottom-most interface which abstracts address
28 access for both debugging and introspection. In the situation of
29 debugging a target VM, these routines can throw the specified
30 RuntimeExceptions to indicate failure and allow recovery of the
31 debugging system. If these are used for introspecting the current
32 VM and implementing functionality in it, however, it is expected
33 that these kinds of failures will not occur and, in fact, a crash
34 will occur if the situation arises where they would have been
35 thrown. </P>
36
37 <P> Addresses are immutable. Further, it was decided not to expose
38 the representation of the Address (and provide a corresponding
39 factory method from, for example, long to Address). Unfortunately,
40 because of the existence of C and "reuse" of low bits of pointers,
41 it is occasionally necessary to perform logical operations like
42 masking off the low bits of an "address". While these operations
43 could be used to generate arbitrary Address objects, allowing this
44 is not the intent of providing these operations. </P>
45
46 <P> This interface is able to fetch all Java primitive types,
47 addresses, oops, and C integers of arbitrary size (see @see
48 sun.jvm.hotspot.types.CIntegerType for further discussion). Note
49 that the result of the latter is restricted to fitting into a
50 64-bit value and the high-order bytes will be silently discarded
51 if too many bytes are requested. </P>
52
53 <P> Implementations may have restrictions, for example that the
54 Java-related routines may not be called until a certain point in
55 the bootstrapping process once the sizes of the Java primitive
56 types are known. (The current implementation has that property.)
57 </P>
58
59 <P> A note of warning: in C addresses, when represented as
60 integers, are usually represented with unsigned types.
61 Unfortunately, there are no unsigned primitive types in Java, so
62 care will have to be taken in the implementation of this interface
63 if using longs as the representation for 64-bit correctness. This
64 is not so simple for the comparison operators. </P> */
65
66 public interface Address {
67
68 /** This is stated explicitly here because it is important for
69 implementations to understand that equals() and hashCode() must
70 absolutely, positively work properly -- i.e., two Address
71 objects representing the same address are both equal (via
72 equals()) and have the same hash code. */
73 public boolean equals(Object arg);
74
75 /** This is stated explicitly here because it is important for
76 implementations to understand that equals() and hashCode() must
77 absolutely, positively work properly -- i.e., two Address
78 objects representing the same address are both equal (via
79 equals()) and have the same hash code. */
80 public int hashCode();
81
82 //
83 // C/C++-related routines
84 //
85
86 public long getCIntegerAt (long offset, long numBytes, boolean isUnsigned)
87 throws UnmappedAddressException, UnalignedAddressException;
88 /** This returns null if the address at the given offset is NULL. */
89 public Address getAddressAt (long offset) throws UnmappedAddressException, UnalignedAddressException;
90
91 //
92 // Java-related routines
93 //
94
95 public boolean getJBooleanAt (long offset) throws UnmappedAddressException, UnalignedAddressException;
96 public byte getJByteAt (long offset) throws UnmappedAddressException, UnalignedAddressException;
97 public char getJCharAt (long offset) throws UnmappedAddressException, UnalignedAddressException;
98 public double getJDoubleAt (long offset) throws UnmappedAddressException, UnalignedAddressException;
99 public float getJFloatAt (long offset) throws UnmappedAddressException, UnalignedAddressException;
100 public int getJIntAt (long offset) throws UnmappedAddressException, UnalignedAddressException;
101 public long getJLongAt (long offset) throws UnmappedAddressException, UnalignedAddressException;
102 public short getJShortAt (long offset) throws UnmappedAddressException, UnalignedAddressException;
103 /** This returns null if the address at the given offset is NULL. */
104 public OopHandle getOopHandleAt (long offset)
105 throws UnmappedAddressException, UnalignedAddressException, NotInHeapException;
106
107 //
108 // C/C++-related mutators. These throw UnmappedAddressException if
109 // the target is read-only (for example, a core file rather than an
110 // active process), if the target address is unmapped, or if it is
111 // read-only. The implementation may supply extra detail messages.
112 //
113
114 /** Sets a C integer numBytes in size at the specified offset. Note
115 that there is no "unsigned" flag for the accessor since the
116 value will not be sign-extended; the number of bytes are simply
117 copied from the value into the target address space. */
118 public void setCIntegerAt(long offset, long numBytes, long value);
119
120 /** Sets an Address at the specified location. */
121 public void setAddressAt(long offset, Address value);
122
123 //
124 // Java-related mutators -- see above.
125 //
126
127 public void setJBooleanAt (long offset, boolean value)
128 throws UnmappedAddressException, UnalignedAddressException;
129 public void setJByteAt (long offset, byte value)
130 throws UnmappedAddressException, UnalignedAddressException;
131 public void setJCharAt (long offset, char value)
132 throws UnmappedAddressException, UnalignedAddressException;
133 public void setJDoubleAt (long offset, double value)
134 throws UnmappedAddressException, UnalignedAddressException;
135 public void setJFloatAt (long offset, float value)
136 throws UnmappedAddressException, UnalignedAddressException;
137 public void setJIntAt (long offset, int value)
138 throws UnmappedAddressException, UnalignedAddressException;
139 public void setJLongAt (long offset, long value)
140 throws UnmappedAddressException, UnalignedAddressException;
141 public void setJShortAt (long offset, short value)
142 throws UnmappedAddressException, UnalignedAddressException;
143 public void setOopHandleAt (long offset, OopHandle value)
144 throws UnmappedAddressException, UnalignedAddressException;
145
146 //
147 // Arithmetic operations -- necessary evil.
148 //
149
150 /** This throws an UnsupportedOperationException if this address happens
151 to actually be an OopHandle, because interior object pointers
152 are not allowed. Negative offsets are allowed and handle the
153 subtraction case. */
154 public Address addOffsetTo (long offset) throws UnsupportedOperationException;
155
156 /** This method had to be added in order to support heap iteration
157 in the debugging system, and is effectively the dangerous
158 operation of allowing interior object pointers. For this reason
159 it was kept as a separate API and its use is forbidden in the
160 non-debugging (i.e., reflective system) case. It is strongly
161 recommended that this not be called by clients: it is currently
162 wrapped up in the Space's iteration mechanism. */
163 public OopHandle addOffsetToAsOopHandle(long offset) throws UnsupportedOperationException;
164
165 /** Performs the subtraction "this - arg", returning the resulting
166 offset in bytes. Note that this must handle a null argument
167 properly, and can be used to convert an Address into a long for
168 further manipulation, but that the reverse conversion is not
169 possible. (FIXME: any signed/unsigned issues? Should this work
170 for OopHandles?) */
171 public long minus(Address arg);
172
173 /** Performs unsigned comparison "this < arg".
174 (FIXME: should this work for OopHandles?) */
175 public boolean lessThan (Address arg);
176 /** Performs unsigned comparison "this <= arg".
177 (FIXME: should this work for OopHandles?) */
178 public boolean lessThanOrEqual (Address arg);
179 /** Performs unsigned comparison "this > arg".
180 (FIXME: should this work for OopHandles?) */
181 public boolean greaterThan (Address arg);
182 /** Performs unsigned comparison "this >= arg".
183 (FIXME: should this work for OopHandles?) */
184 public boolean greaterThanOrEqual(Address arg);
185
186 /** This throws an UnsupportedOperationException if this address happens
187 to actually be an OopHandle. Performs a logical "and" operation
188 of the bits of the address and the mask (least significant bits
189 of the Address and the mask are aligned) and returns the result
190 as an Address. Returns null if the result was zero. */
191 public Address andWithMask(long mask) throws UnsupportedOperationException;
192
193 /** This throws an UnsupportedOperationException if this address happens
194 to actually be an OopHandle. Performs a logical "or" operation
195 of the bits of the address and the mask (least significant bits
196 of the Address and the mask are aligned) and returns the result
197 as an Address. Returns null if the result was zero. */
198 public Address orWithMask(long mask) throws UnsupportedOperationException;
199
200 /** This throws an UnsupportedOperationException if this address happens
201 to actually be an OopHandle. Performs a logical "exclusive or"
202 operation of the bits of the address and the mask (least
203 significant bits of the Address and the mask are aligned) and
204 returns the result as an Address. Returns null if the result was
205 zero. */
206 public Address xorWithMask(long mask) throws UnsupportedOperationException;
207 }