Target Communication Framework Services - Registers

Registers Service

Version History

Version Date Change
0.1 2008-01-10 Initial contribution
0.2 2008-04-23 Added get/set multiple
1.0 2008-05-06 Approved
1.1 2009-03-16 Added search command and several context properties

Overview

The service provides basic operations to read/write CPU and hardware registers. Command and event parameters are encoded as zero terminated JSON strings.

The service uses standard format for error reports, see Error Report Format.

In addition to commands that can set/get individual register context values, the service defines commands to set/get values at multiple locations. This allows:
  1. to get/set multiple register contexts in one command
  2. to specify offset and size for get/set on large register groups
  3. to get/set truncated register values, e.g. only the low 32 bits of a 64-bit register

Commands

Get Context


C • <token> • Registers • getContext • <string: context ID>

The command retrieves context info for given context ID. A context corresponds to an register, register group, register bit field, etc. Exact meaning of a context depends on the target. Target agent should define contexts hierarchy that is:

Reply:


R • <token><error report><context data><context data>
    ⇒ null
    ⇒ <object>

Context data object should, at least, contain member "ID" : <string>. Context data is expected to be cached by clients. Service sends contextChanged event to notify changes in context data.

Predefined register context properties are:

Get Children


C • <token> • Registers • getChildren • <string: parent context ID>

The command requests a list of contexts available for registers access commands.

Parent context ID is usually a thread ID retrieved through Run Control Service or one of context IDs retrieved by previous getChildren commands. Contexts hierarchy can be simple plain list of registers, or it can form a tree of register groups, registers and bit fields. It is up to target agent developers to choose layout that is most descriptive for a given target.

Reply:


R • <token><error report><array of context IDs>

<array of context IDs>
    ⇒ null
    ⇒ [ ]
    ⇒ [ <context ID list> ]

<context ID list><string: context ID><context ID list> , <string: context ID>

Set Register


C • <token> • Registers • set • <string: context ID><string: value>

Writes value into given register context. Context ID must be one returned by getContexts. Value is BASE64 encoded byte array of binary data. Array size should match the size of the register.

Result message:


R • <token><error report>

Error report provides integer error code and a short, human readable explanation of error.

Get Register


C • <token> • Registers • get • <string: context ID>

Reads register value from given register context. Context ID must be one returned by getContexts.

Result message:


R • <token><error report><string: value>

Error report provides integer error code and a short, human readable explanation of error. Value is BASE64 encoded byte array of binary data. Array size should match the size of the register.

Set Multiple Registers


C • <token> • Registers • setm • <array of locations><string: value><array of locations>
    ⇒ [ <location list> ]

<location list><location><location list> , <location>

<location>
    ⇒ [ <string: register context ID> , <int: offset in bytes> , <int: size in bytes> ]

Writes value into given list of locations in registers. Each location is represented by 3-element array that consists of context ID, offset in the context in bytes and value size in bytes. Value is BASE64 encoded byte array of binary data. Byte array size should match the sum of location sizes.

Result message:


R • <token><error report>

Error report provides integer error code and a short, human readable explanation of error.

Get Multiple Registers


C • <token> • Registers • getm • <array of locations><array of locations>
    ⇒ [ <location list> ]

<location list><location><location list> , <location>

<location>
    ⇒ [ <string: register context ID> , <int: offset in bytes> , <int: size in bytes> ]

Reads register values from given list of locations in registers. Each location is represented by 3-element array that consists of context ID, offset in the context in bytes and value size in bytes.

Result message:


R • <token><error report><string: value>

Error report provides integer error code and a short, human readable explanation of error. Value is BASE64 encoded byte array of binary data. Byte array size should match the sum of location sizes.

Search for Registers


C • <token> • Registers • search • <string: start context ID> • <object:filter properties>

Search returns a path to each context with properties matching the filter. A path consists of a list of context ids starting with a direct child of the start context up to the found context. Search is only supported for properties listed in the CanSearch property.

Predefined filter object properties are:

Result message:


R • <token><error report><array of context Paths><array of context Paths>
    ⇒ null
    ⇒ [ ]
    ⇒ [ <context Path list> ]

<context Path list><array of context IDs><context Path list> , <array of context IDs>

Error report provides integer error code and a short, human readable explanation of error. In the result, each matching context is provided with the path of parents starting with the direct children of the starting node up to the matching node. Multiple found entries are returned as an array of those paths.

Example Assume the following context hierarchy:

{"Name" : "Core", "ID":"ID_C"}
        {"Name" : "Group0", "ID":"ID_G0", "Role":"CORE"}
                {"Name" : "PC", "ID":"ID_PC", "Role":"PC"}
                {"Name" : "SP", "ID":"ID_SP", "Role":"SP"}
        {"Name" : "Group1", "ID":"ID_G1"}
                {"Name" : "R0", "ID":"ID_R0"}
With this setup, the following commands and responses could take place:

C • "1234" • Registers • search • "ID_C" • {"Name":"Name", "EqualValue":"PC"} •
R • "1234" • [["ID_G0", "ID_PC"]] •

C • "1235" • Registers • search • "ID_C" • {"Name":"Role", "EqualValue":"CORE"} •
R • "1235" • [["ID_G0"]] •

Events

Registers service broadcasts notification events when registers contexts are changed, and when a register content is altered by "set" commands.


E • Registers • contextChanged •
E • Registers • registerChanged • <string: context ID>

API

/**
 * 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",                         /** String, ID of the context */
        PROP_PARENT_ID = "ParentID",            /** String, ID of a parent context */
        PROP_PROCESS_ID = "ProcessID",          /** String, process ID */
        PROP_NAME = "Name",                     /** String, context name */
        PROP_DESCRIPTION = "Description",       /** String, context description */
        PROP_SIZE = "Size",                     /** Number, context size in bytes. Byte arrays in get/set commands should be same size */
        PROP_READBLE = "Readable",              /** Boolean, true if context value can be read */
        PROP_READ_ONCE = "ReadOnce",            /** Boolean, true if reading the context (register) destroys its current value */
        PROP_WRITEABLE = "Writeable",           /** Boolean, true if context value can be written */
        PROP_WRITE_ONCE = "WriteOnce",          /** Boolean, true if register value can not be overwritten - every write counts */
        PROP_SIDE_EFFECTS = "SideEffects",      /** Boolean, true if writing the context can change values of other registers */
        PROP_VOLATILE = "Volatile",             /** Boolean, true if the register value can change even when target is stopped */
        PROP_FLOAT = "Float",                   /** Boolean, true if the register value is a floating-point value */
        PROP_BIG_ENDIAN = "BigEndian",          /** Boolean, true if big endian */
        PROP_LEFT_TO_RIGHT = "LeftToRight",     /** Boolean, true if the lowest numbered bit should be shown to user as the left-most bit */
        PROP_FIST_BIT = "FirstBit",             /** Number, bit numbering base (0 or 1) to use when showing bits to user */
        PROP_BITS = "Bits",                     /** Number, if context is a bit field, contains the field bit numbers in the parent context */
        PROP_VALUES = "Values",                 /** Array of Map, predefined names (mnemonics) for some of context values */
        PROP_MEMORY_ADDRESS = "MemoryAddress",  /** Number, the address of a memory mapped register */
        PROP_MEMORY_CONTEXT = "MemoryContext",  /** String, the context ID of a memory context in which a memory mapped register is located */
        PROP_CAN_SEARCH = "CanSearch",          /** Array of String, a list of attribute names which can be searched for starting on this context */
        PROP_ROLE = "Role";                     /** String, the role the register plays in a program execution */

    /**
     * Role property names.
     */
    static final String
        ROLE_PC = "PC",                         /** Program counter. Defines instruction to execute next */
        ROLE_SP = "SP",                         /** Register defining the current stack pointer location */
        ROLE_FP = "FP",                         /** Register defining the current frame pointer location */
        ROLE_RET = "RET",                       /** Register used to store the return address for calls */
        ROLE_CORE = "CORE";                     /** Indicates register or register groups which belong to the core state */

    /**
     * Filter property names.
     */
    static final String
        SEARCH_NAME = "Name",                   /** The name of the property this filter applies too */
        SEARCH_EQUAL_VALUE = "EqualValue";      /** The value which is searched for */


    /**
     * 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 contexts 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 contexts data 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 context size in bytes.
         * Byte arrays in get()/set() methods should be same size.
         * Hardware register can be smaller then this size, for example in case
         * when register size is not an even number of bytes. In such case implementation
         * should add/remove padding that consists of necessary number of zero bits.
         * @return context size in bytes.
         */
        int getSize();

        /**
         * 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 the address of a memory mapped register.
         * @return address.
         */
        Number getMemoryAddress();

        /**
         * Get the context ID of a memory context in which a memory mapped register is located.
         * @return memory context ID.
         */
        String getMemoryContext();

        /**
         * Get a list of property names which can be searched for starting on this context
         * @return collection of property names.
         */
        Collection canSearch();

        /**
         * Get the role the register plays in a program execution.
         * @return role name.
         */
        String getRole();

        /**
         * Get complete map of context properties.
         * @return map of all available context properties.
         */
        Map getProperties();

        /**
         * Read value of the context.
         * @param done - call back object.
         * @return - pending command handle.
         */
        IToken get(DoneGet done);

        /**
         * Set value of the context.
         * @param value - value to write into the context.
         * @param done - call back object.
         * @return - pending command handle.
         */
        IToken set(byte[] value, DoneSet done);

       /**
         * Search register contexts that passes given search filter.
         * Search is only supported for properties listed in the "CanSearch" property.
         * @param filter - properties bag that defines search filter.
         * @param done - call back object.
         * @return - pending command handle.
         */
         IToken search(Map<String,Object> filter, DoneSearch done);
    }

    /**
     * A register context can have predefined names (mnemonics) for some its values.
     * NamedValue objects represent such values.
     */
    interface NamedValue {
        /**
         * Get value associated with the name.
         * @return the value as an array of bytes.
         */
        byte[] getValue();

        /**
         * Get name (mnemonic) of the value.
         * @return value name.
         */
        String getName();

        /**
         * Get human readable description of the value.
         * @return value description.
         */
        String getDescription();
    }

    /**
     * Read values of multiple locations in registers.
     * @param locs - array of data locations.
     * @param done - call back object.
     * @return - pending command handle.
     */
    IToken getm(Location[] locs, DoneGet done);

    /**
     * Set values of multiple locations in registers.
     * @param locs - array of data locations.
     * @param value - value to write into the context.
     * @param done - call back object.
     * @return - pending command handle.
     */
    IToken setm(Location[] locs, byte[] value, DoneSet done);

    /**
     * Class Location represents value location in register context
     */
    final class Location {
        /** Register context ID */
        public final String id;

        /** offset in the context, in bytes */
        public final int offs;

        /** value size in bytes */
        public final int size;

        public Location(String id, int offs, int size) {
            this.id = id;
            this.offs = offs;
            this.size = size;
        }
    }

    /**
     * 'get' command call back interface.
     */
    interface DoneGet {
        /**
         * Called when value retrieval is done.
         * @param token - command handle
         * @param error - error description if operation failed, null if succeeded.
         * @param value - context value as array of bytes.
         */
        void doneGet(IToken token, Exception error, byte[] value);
    }

    /**
     * 'set' command call back interface.
     */
    interface DoneSet {
        /**
         * Called when value setting is done.
         * @param token - command handle.
         * @param error - error description if operation failed, null if succeeded.
         */
        void doneSet(IToken token, Exception error);
    }

    /**
     * 'search' command call back interface.
     */
    interface DoneSearch {
        /**
         * Called when context search is done.
         * @param token - command handle.
         * @param error - error description if operation failed, null if succeeded.
         * @param paths - array of paths to each context with properties matching the filter
         */
        void doneSearch(IToken token, String[][] paths);
    }

    /**
     * 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.
         * At least, changes caused by "set" command should be notified.
         * @param id - register context ID.
         */
        void registerChanged(String context_id);
    }
}