IMemoryBlockExtension


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