1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
|
/*******************************************************************************
* Copyright (c) 2004, 2006 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.debug.core.model;
import java.math.BigInteger;
import org.eclipse.debug.core.DebugException;
/**
* Extensions to {@link org.eclipse.debug.core.model.IMemoryBlock}. Allows
* for bytes to be accessed in a larger address space, and for state information
* to be provided for each byte.
* <p>
* Clients may optionally implement this interface when providing implementations of
* {@link org.eclipse.debug.core.model.IMemoryBlock}.
* </p>
* @since 3.1
* @see org.eclipse.debug.core.model.MemoryByte
*/
public interface IMemoryBlockExtension extends IMemoryBlock {
/**
* Returns the expression used to create this memory block. An expression can
* be used as name for a memory block and typically represents an expression
* used to compute a base address for a memory block.
*
* @return the expression used to create this memory block
*/
public String getExpression();
/**
* Returns the base address of this memory block as a big integer. The
* address is in terms of addressable units.
*
* @return the base address of this memory block
* @throws DebugException if unable to retrieve the base address
*/
public BigInteger getBigBaseAddress() throws DebugException;
/**
* Returns the hard start address of this memory block as a big integer, or
* <code>null</code> if none. A <code>null</code> start address indicates that
* memory may be retrieved at any address less than this memory block's base
* address.
*
* @return the hard start address of this memory block or <code>null</code>
* @throws DebugException if unable to retrieve the start address of this memory block.
*/
public BigInteger getMemoryBlockStartAddress() throws DebugException;
/**
* Returns the hard end address of this memory block as a big integer, or
* <code>null</code> if none. A <code>null</code> end address indicates that
* memory may be retrieved from any positive offset relative to the base address
* of this memory block.
*
* @return the hard end address of this memory block or <code>null</code>
* @throws DebugException if unable to retrieve the end address of this memory block.
*/
public BigInteger getMemoryBlockEndAddress() throws DebugException;
/**
* Returns the length of this memory block, or -1 if unbounded.
* Returns "end address - start address" for a memory block with a fixed
* length (i.e. when both start and end address are known).
* Returns -1 for an unbounded memory block (i.e. when start or end address is
* <code>null</code>).
*
* @return length of this memory block or -1 if unbounded
* @throws DebugException if unable to retrieve the length of this memory block.
*/
public BigInteger getBigLength() throws DebugException;
/**
* Returns the address size of this memory block in number of bytes. The address
* size indicates the number of bytes used to construct an address.
*
* @return address size in number of bytes
* @throws DebugException if unable to retrieve the address size
*/
public int getAddressSize() throws DebugException;
/**
* Returns whether the base address of this memory block can be modified.
*
* @return whether the base address of this memory block can be modified
* @throws DebugException is unable to determine if base address modification is supported
*/
public boolean supportBaseAddressModification() throws DebugException;
/**
* Returns whether this memory block manages the change state of its bytes.
* <p>
* If a memory block manages changes the memory block is responsible for
* setting the <code>CHANGED</code> state of its <code>MemoryByte</code>'s
* returned from <code>getBytesFromAddress</code> and
* <code>getBytesFromOffset</code>. The changed state of a byte should
* be updated each time a thread suspends in a memory block's target.
* </p>
* @return whether this memory block manages the change state of its bytes
*/
public boolean supportsChangeManagement();
/**
* Sets the base address of this memory block to the given address.
*
* @param address new base address
* @throws DebugException if unable to modify the base address, or modification
* of the base address fails
*/
public void setBaseAddress(BigInteger address) throws DebugException;
/**
* Returns bytes from this memory block based on the base address and
* addressable size of this memory block.
* <p>
* A memory block may be asked to retrieve bytes beyond it's start
* or end address. If a memory block is unable to retrieve memory outside
* these boundaries, implementations should return memory bytes with
* the <code>READABLE</code> bit turned off for each byte outside
* the of the accessible range. An exception should not be thrown in this
* case.
* </p>
* @param unitOffset zero based offset into this memory block at which to start
* retrieving bytes in terms of addressable units. Client should retrieve
* memory starting from "base address + offset".
* @param addressableUnits the number of addressable units to retrieve
* @return an array of bytes from this memory block based on the given offset
* and number of units. The size of the array returned must to be equal to
* <code>units</code> * <code>getAddressableSize()</code>.
* @throws DebugException if unable to retrieve the specified bytes due to
* a failure communicating with the target
* @see MemoryByte
*/
public MemoryByte[] getBytesFromOffset(BigInteger unitOffset, long addressableUnits) throws DebugException;
/**
* Returns bytes from this memory block based on the given address and the
* addressable size of this memory block.
* <p>
* A memory block may be asked to retrieve bytes beyond it's start
* or end address. If a memory block is unable to retrieve memory outside
* these boundaries, implementations should return memory bytes with
* the <code>READABLE</code> bit turned off for each byte outside
* the of the accessible range. An exception should not be thrown in this
* case.
* </p>
* @param address address at which to begin retrieving bytes in terms
* of addressable units
* @param units is the number of addressable units of memory to retrieve
* @return an array of bytes from this memory block based on the given address
* and number of units. The size of the array returned must to be equal to
* <code>units</code> * <code>getAddressableSize()</code>.
* @throws DebugException if unable to retrieve the specified bytes due to
* a failure communicating with the target
* @see MemoryByte
*/
public MemoryByte[] getBytesFromAddress(BigInteger address, long units) throws DebugException;
/**
* Sets bytes in this memory block at the specified offset within this memory block to
* the specified bytes. The offset is zero based. After successfully modifying the
* specified bytes, a debug event should be fired with a kind of <code>CHANGE</code>.
*
* @param offset the zero based offset at which to set the new value. Modify
* the memory starting from base address + offset.
* @param bytes replacement bytes
* @exception DebugException if this method fails. Reasons include:
* <ul><li>Failure communicating with the debug target. The DebugException's
* status code contains the underlying exception responsible for
* the failure.</li>
* <li>This memory block does not support value modification</li>
* <li>The specified offset is greater than or equal to the length
* of this memory block, or the number of bytes specified goes
* beyond the end of this memory block (index of out of range)</li>
* </ul>
* @see org.eclipse.debug.core.DebugEvent
*/
public void setValue(BigInteger offset, byte[] bytes) throws DebugException;
/**
* Connects the given client to this memory block. Allows a memory block
* to know when it is being monitored. Has no effect if an identical
* client is already connected.
* <p>
* Memory blocks supporting change management may selectively turn off
* change management when no clients are connected, for reasons of
* efficiency. Clients that require access to change state information
* are required to connect to a memory block before change information
* is considered to be valid.
* </p>
* @param client the client to connect
*/
public void connect(Object client);
/**
* Disconnects the given client from this memory block. Has no effect if
* an identical client is not already connected.
*
* @param client the client to disconnect
*/
public void disconnect(Object client);
/**
* Returns the possibly empty list of clients currently connected to this
* memory block.
*
* @return the possibly empty list of clients currently connected to this
* memory block
*/
public Object[] getConnections();
/**
* Dispose this memory block. Connected clients are disconnected.
* @throws DebugException if the memory block cannot be disposed.
*/
public void dispose() throws DebugException;
/**
* Returns the origin of this memory block.
*
* @return the origin of this memory block
*/
public IMemoryBlockRetrieval getMemoryBlockRetrieval();
/**
* Returns this memory block's addressable size in number of bytes. The addressable size
* of memory block indicates the minimum number of bytes that can be retrieved as
* a single unit.
*
* @return this memory block's addressable size
* @throws DebugException if the addressable size cannot be obtained.
*/
public int getAddressableSize() throws DebugException;
}
|
