Skip to main content
aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat (limited to 'plugins/com.windriver.tcf.api/src/com/windriver/tcf/api/services/IRegisters.java')
-rw-r--r--plugins/com.windriver.tcf.api/src/com/windriver/tcf/api/services/IRegisters.java318
1 files changed, 318 insertions, 0 deletions
diff --git a/plugins/com.windriver.tcf.api/src/com/windriver/tcf/api/services/IRegisters.java b/plugins/com.windriver.tcf.api/src/com/windriver/tcf/api/services/IRegisters.java
new file mode 100644
index 000000000..2cf4de1f4
--- /dev/null
+++ b/plugins/com.windriver.tcf.api/src/com/windriver/tcf/api/services/IRegisters.java
@@ -0,0 +1,318 @@
+/*******************************************************************************
+ * 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;
+
+/**
+ * IRegisters service provides access to target CPU register values and properties.
+ */
+public interface IRegisters extends IService {
+
+ static final String NAME = "Registers";
+
+ /**
+ * Context property names.
+ */
+ static final String
+ PROP_ID = "ID",
+ PROP_PARENT_ID = "ParentID",
+ PROP_PROCESS_ID = "ProcessID",
+ PROP_NAME = "Name",
+ PROP_DESCRIPTION = "Description",
+ PROP_FORMATS = "Formats",
+ PROP_READBLE = "Readable",
+ PROP_READ_ONCE = "ReadOnce",
+ PROP_WRITEABLE = "Writeable",
+ PROP_WRITE_ONCE = "WriteOnce",
+ PROP_SIDE_EFFECTS = "SideEffects",
+ PROP_VOLATILE = "Volatile",
+ PROP_FLOAT = "Float",
+ PROP_BIG_ENDIAN = "BigEndian",
+ PROP_LEFT_TO_RIGHT = "LeftToRight",
+ PROP_FIST_BIT = "FirstBit",
+ PROP_BITS = "Bits",
+ PROP_VALUES = "Values";
+
+ /**
+ * Standard known formats for register data.
+ */
+ static final String
+ FORMAT_BINARY = "Binary",
+ FORMAT_OCTAL = "Octal",
+ FORMAT_DECIMAL = "Decimal",
+ FORMAT_HEX = "Hex",
+ FORMAT_NATURAL = "Natural";
+
+ /**
+ * 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, RegistersContext context);
+ }
+
+ /**
+ * Retrieve contexts available for registers commands.
+ * A context corresponds to an execution thread, stack frame, registers group, 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);
+ }
+
+ /**
+ * RegistersContext objects represent register groups, registers and bit fields.
+ */
+ interface RegistersContext {
+ /**
+ * Get Context ID.
+ * @return context ID.
+ */
+ String getID();
+
+ /**
+ * Get parent context ID.
+ * @return parent context ID.
+ */
+ String getParentID();
+
+ /**
+ * Get context (register, register group, bit field) name.
+ * @return context name.
+ */
+ String getName();
+
+ /**
+ * Get context description.
+ * @return context description.
+ */
+ String getDescription();
+
+ /**
+ * Get value formats available for register get/set commands.
+ * See FORMAT_* for knows format IDs definition.
+ * @return array of supported format IDs.
+ */
+ String[] getAvailableFormats();
+
+ /**
+ * Check if context value can be read.
+ * @return true if can read value of the context.
+ */
+ boolean isReadable();
+
+ /**
+ * Check if reading the context (register) destroys its current value -
+ * it can be read only once.
+ * @return true if read-once register.
+ */
+ boolean isReadOnce();
+
+ /**
+ * Check if context value can be written.
+ * @return true if can write value of the context.
+ */
+ boolean isWriteable();
+
+ /**
+ * Check if register value can not be overwritten - every write counts.
+ * @return true if write-once register.
+ */
+ boolean isWriteOnce();
+
+ /**
+ * Check if writing the context can change values of other registers.
+ * @return true if has side effects.
+ */
+ boolean hasSideEffects();
+
+ /**
+ * Check if the register value can change even when target is stopped.
+ * @return true if the register value can change at any time.
+ */
+ boolean isVolatile();
+
+ /**
+ * Check if the register value is a floating-point value.
+ * @return true if a floating-point register.
+ */
+ boolean isFloat();
+
+ /**
+ * Check endianess of the context.
+ * Big endian means decreasing numeric significance with increasing bit number.
+ * @return true if big endian.
+ */
+ boolean isBigEndian();
+
+ /**
+ * Check if the lowest numbered bit (i.e. bit #0 or bit #1 depending on
+ * getFirstBitNumber() value) should be shown to user as the left-most bit or
+ * the right-most bit.
+ * @return true if the first bit is left-most bit.
+ */
+ boolean isLeftToRight();
+
+ /**
+ * If the context has bit field children, bit positions of the fields
+ * can be zero-based or 1-based.
+ * @return first bit position - 0 or 1.
+ */
+ int getFirstBitNumber();
+
+ /**
+ * If context is a bit field, get the field bit numbers in parent context.
+ * @return array of bit numbers.
+ */
+ int[] getBitNumbers();
+
+ /**
+ * A context can have predefined names (mnemonics) for some its values.
+ * This method returns a list of such named values.
+ * @return array of named values or null.
+ */
+ NamedValue[] getNamedValues();
+
+ /**
+ * Get complete map of context properties.
+ * @return map of context properties.
+ */
+ Map<String,Object> getProperties();
+
+ /**
+ * Read value of the context.
+ * @param format - ID of a format to use for result value.
+ * @param done - call back object.
+ * @return - pending command handle.
+ */
+ IToken get(String format, DoneGet done);
+
+ /**
+ * Set value of the context.
+ * @param format - ID of a format used for value.
+ * @param value - value to write into the context.
+ * @param done - call back object.
+ * @return - pending command handle.
+ */
+ IToken set(String format, String value, DoneSet done);
+ }
+
+ /**
+ * A register context can have predefined names (mnemonics) for some its values.
+ * NamedValue objects represent such values.
+ */
+ interface NamedValue {
+ /**
+ * Get number associated with this named value.
+ * @return the value as a number.
+ */
+ Number getValue();
+
+ /**
+ * Get name (mnemonic) of the value.
+ * @return value name.
+ */
+ String getName();
+
+ /**
+ * Get human readable description of the value.
+ * @return value description.
+ */
+ String getDescription();
+ }
+
+ /**
+ * 'get' command call back interface.
+ */
+ interface DoneGet {
+ void doneGet(IToken token, Exception error, String value);
+ }
+
+ /**
+ * 'set' command call back interface.
+ */
+ interface DoneSet {
+ void doneSet(IToken token, Exception error);
+ }
+
+ /**
+ * Add registers service event listener.
+ * @param listener - event listener implementation.
+ */
+ void addListener(RegistersListener listener);
+
+ /**
+ * Remove registers service event listener.
+ * @param listener - event listener implementation.
+ */
+ void removeListener(RegistersListener listener);
+
+ /**
+ * Registers event listener is notified when registers context hierarchy
+ * changes, and when a register is modified by the service commands.
+ */
+ interface RegistersListener {
+
+ /**
+ * Called when register context properties changed.
+ * Most targets have static set of registers and register properties.
+ * Such targets never generate this event. However, some targets,
+ * for example, JTAG probes, allow user to modify register definitions.
+ * Clients should flush all cached register context data.
+ */
+ void contextChanged();
+
+ /**
+ * Called when register content was changed and clients
+ * need to update themselves. Clients, at least, should invalidate
+ * corresponding cached registers data.
+ * Not every change is notified - it is not possible,
+ * only those, which are not caused by normal execution of the debuggee.
+ */
+ void registerChanged(String context_id);
+ }
+}

Back to the top