# Target Communication Framework Services - Registers

- Commands
  - Get Context
  - Get Children
  - Set Register
  - Get Register
- Events
- API

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

## 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:

- Adequately reflects target hardware registers layout;
- Consistent with the lingo/terminology of the processor manuals;
- Intuitive to a user.

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:

- `"ID" : <string>` - ID of the context, same as getContext command argument.
- `"ParentID" : <string>` - ID of a parent context.
- `"ProcessID" : <string>` - process ID.
- `"Name" : <string>` - context name.
- `"Description" : <string>` - context description.
- `"Formats" : <array of string>` - value formats available for register get/set commands.
- `"Readable" : <boolean>` - true if context value can be read.
- `"ReadOnce" : <boolean>` - true if reading the context (register) destroys its current value - it can be read only once.
- `"Writeable" : <boolean>` - true if context value can be written.
- `"WriteOnce" : <boolean>` - true if register value can not be overwritten - every write counts.
- `"SideEffects" : <boolean>` - true if writing the context can change values of other registers.
- `"Volatile" : <boolean>` - true if the register value can change even when target is stopped.
- `"Float" : <boolean>` - true if the register value is a floating-point value.
- `"BigEndian" : <boolean>` - true if big endian, which means decreasing numeric significance with increasing bit number.
- `"LeftToRight" : <boolean>` - true if the lowest numbered bit (i.e. bit #0 or bit #1, depending on "FirstBit" value) should be shown to user as the left-most bit.
- `"FirstBit" : <int>` - 0 or 1. If the context has bit field children, bit positions of the fields can be zero-based or 1-based.
- `"Bits" : <array of int>` - if context is a bit field, contains the field bit numbers in the parent context.
- `"Values" : <array of named values>` - predefined names (mnemonics) for some of context values.

### 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 format> • <string: value> •

Writes value into given register context. Context ID must be one returned by getContexts. Value format must be one that is supported by the register context. Client can get list of supported formats from context attributes.

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> • <string: value format> •

Reads register value from given register context. Context ID must be one returned by getContexts. Value format must be one that is supported by the register context. Client can get list of supported formats from context attributes.

Result message:

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

Error report provides integer error code and a short, human readable explanation of error. Value is formatted according to requested format.

## 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_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 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 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);
        }
    }