diff options
Diffstat (limited to 'plugins/com.windriver.tcf.api/src/com/windriver/tcf/api/services/IMemory.java')
-rw-r--r-- | plugins/com.windriver.tcf.api/src/com/windriver/tcf/api/services/IMemory.java | 247 |
1 files changed, 247 insertions, 0 deletions
diff --git a/plugins/com.windriver.tcf.api/src/com/windriver/tcf/api/services/IMemory.java b/plugins/com.windriver.tcf.api/src/com/windriver/tcf/api/services/IMemory.java new file mode 100644 index 000000000..0f01c4a95 --- /dev/null +++ b/plugins/com.windriver.tcf.api/src/com/windriver/tcf/api/services/IMemory.java @@ -0,0 +1,247 @@ +/******************************************************************************* + * Copyright (c) 2007 Wind River Systems, Inc. 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: + * Wind River Systems - initial API and implementation + *******************************************************************************/ +package com.windriver.tcf.api.services; + +import java.util.Map; + +import com.windriver.tcf.api.protocol.IService; +import com.windriver.tcf.api.protocol.IToken; + +/** + * IMemory service provides basic operations to read/write memory on a target. + */ +public interface IMemory extends IService { + + static final String NAME = "Memory"; + + /** + * Context property names. + */ + static final String + PROP_ID = "ID", + PROP_PARENT_ID = "ParentID", + PROP_PROCESS_ID = "ProcessID", + PROP_BIG_ENDIAN = "BigEndian", + PROP_ADDRESS_SIZE = "AddressSize"; + + /** + * Retrieve context info for given context ID. + * + * @param id – context ID. + * @param done - call back interface called when operation is completed. + */ + IToken getContext(String id, DoneGetContext done); + + /** + * Client call back interface for getContext(). + */ + interface DoneGetContext { + /** + * Called when context data retrieval is done. + * @param error – error description if operation failed, null if succeeded. + * @param context – context data. + */ + void doneGetContext(IToken token, Exception error, MemoryContext context); + } + + /** + * Retrieve contexts available for memory commands. + * A context corresponds to an execution thread, process, address space, etc. + * A context can belong to a parent context. Contexts hierarchy can be simple + * plain list or it can form a tree. It is up to target agent developers to choose + * layout that is most descriptive for a given target. Context IDs are valid across + * all services. In other words, all services access same hierarchy of contexts, + * with same IDs, however, each service accesses its own subset of context's + * attributes and functionality, which is relevant to that service. + * + * @param parent_context_id – parent context ID. Can be null – + * to retrieve top level of the hierarchy, or one of context IDs retrieved + * by previous getChildren commands. + * @param done - call back interface called when operation is completed. + */ + IToken getChildren(String parent_context_id, DoneGetChildren done); + + /** + * Client call back interface for getChildren(). + */ + interface DoneGetChildren { + /** + * Called when context list retrieval is done. + * @param error – error description if operation failed, null if succeeded. + * @param context_ids – array of available context IDs. + */ + void doneGetChildren(IToken token, Exception error, String[] context_ids); + } + + /** + * Memory access mode: + * Carry on when some of the memory cannot be accessed and + * return MemoryError at the end if any of the bytes + * were not processed correctly. + */ + final static int MODE_CONTINUEONERROR = 0x1; + + /** + * Memory access mode: + * Verify result of memory operations (by reading and comparing). + */ + final static int MODE_VERIFY = 0x2; + + interface MemoryContext { + + /** + * Retrieve context ID. + * Same as (String)getProperties().get(“ID”) + */ + String getID(); + + /** + * Retrieve parent context ID. + * Same as (String)getProperties().get(“ParentID”) + */ + String getParentID(); + + /** + * Retrieves process ID, if applicable. + * @return process system ID. + */ + int getProcessID(); + + /** + * Retrieve memory endianess. + * @return true if memory id big-endian. + */ + boolean isBigEndian(); + + /** + * Retrieve memory address size. + * @return number of bytes used to store memory address value. + */ + int getAddressSize(); + + /** + * Retrieve context properties. + */ + Map<String,Object> getProperties(); + + /** + * Set target memory. + * If 'word_size' is 0 it means client does not care about word size. + */ + IToken set(Number addr, int word_size, byte[] buf, + int offs, int size, int mode, DoneMemory done); + + /** + * Read target memory. + */ + IToken get(Number addr, int word_size, byte[] buf, + int offs, int size, int mode, DoneMemory done); + + /** + * Fill target memory with given pattern. + * 'size' is number of bytes to fill. + */ + IToken fill(Number addr, int word_size, byte[] value, + int size, int mode, DoneMemory done); + } + + /** + * Client call back interface for set(), get() and fill() commands. + */ + interface DoneMemory { + public void doneMemory(IToken token, MemoryError error); + } + + class MemoryError extends Exception { + + private static final long serialVersionUID = 1L; + + public MemoryError(String msg) { + super(msg); + } + } + + /** + * ErrorOffset interface can be implemented by MemoryError object, + * which is returned by get, set and fill commands. + * + * get/set/fill () returns this exception when reading failed + * for some but not all bytes, and MODE_CONTINUEONERROR + * has been set in mode. (For example, when only part of the request + * translates to valid memory addresses.) + * Exception.getMessage can be used for generalized message of the + * possible reasons of partial memory operation. + */ + interface ErrorOffset { + + // Error may have per byte information + final static int + BYTE_VALID = 0x00, + BYTE_UNKNOWN = 0x01, // e.g. out of range + BYTE_INVALID = 0x02, + BYTE_CANNOT_READ = 0x04, + BYTE_CANNOT_WRITE = 0x08; + + int getStatus(int offset); + + /** + * Returns the detail message string about the + * byte associated with specified location. + * @return the detail error message string. + */ + String getMessage(int offset); + + } + + /** + * Add memory service event listener. + * @param listener - event listener implementation. + */ + void addListener(MemoryListener listener); + + /** + * Remove memory service event listener. + * @param listener - event listener implementation. + */ + void removeListener(MemoryListener listener); + + /** + * Memory event listener is notified when memory context hierarchy + * changes, and when memory is modified by memory service commands. + */ + interface MemoryListener { + + /** + * Called when a new memory access context(s) is created. + */ + void contextAdded(MemoryContext[] contexts); + + /** + * Called when a memory access context(s) properties changed. + */ + void contextChanged(MemoryContext[] contexts); + + /** + * Called when memory access context(s) is removed. + */ + void contextRemoved(String[] context_ids); + + /** + * Called when target memory content was changed and clients + * need to update themselves. Clients, at least, should invalidate + * corresponding cached memory data. + * Not every change is notified - it is not possible, + * only those, which are not caused by normal execution of the debuggee. + * ‘addr’ and ‘size’ can be null if unknown. + */ + void memoryChanged(String context_id, Number[] addr, long[] size); + } +} |