Skip to main content
summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
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.java247
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);
+ }
+}

Back to the top