| /******************************************************************************* |
| * Copyright (c) 2004, 2005 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 retreive 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 spcified 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 replcement 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; |
| } |