Target Communication Framework Services - Registers

Registers Service

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 trunkated 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.

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",
        PROP_PARENT_ID = "ParentID",
        PROP_PROCESS_ID = "ProcessID",
        PROP_NAME = "Name",
        PROP_DESCRIPTION = "Description",
        PROP_SIZE = "Size",
        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";
        
    /**
     * 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 complete map of context properties.
         * @return map of context properties.
         */
        Map<String,Object> 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);
    }
    
    /**
     * 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 {
        void doneGet(IToken token, Exception error, byte[] 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);
    }
}