/*******************************************************************************
 * Copyright (c) 2007, 2013 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 org.eclipse.tcf.services;

import java.util.Collection;
import java.util.Map;

import org.eclipse.tcf.protocol.IService;
import org.eclipse.tcf.protocol.IToken;


/**
 * IRegisters service provides access to target CPU register values and properties.
 *
 * @noimplement This interface is not intended to be implemented by clients.
 */
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 */
        PROP_OFFSET = "Offset";                 /** Number, when present describes the offset in the data of the parent register where the value of a field can be found. */

    /**
     * Values of context property "Role".
     */
    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 */

    /**
     * Search filter properties.
     */
    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 context data retrieval is done.
         * @param token - command handle
         * @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 token - command handle
         * @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 process ID, if applicable.
         * @return process ID.
         */
        String getProcessID();

        /**
         * 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 consist 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 endianness of the context.
         * Big endian means decreasing numeric significance with increasing bit number.
         * The endianness is used to encode and decode values of get, getm, set and setm commands.
         * @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<String> canSearch();

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

        /**
         * Get the offset in the data of the parent register where the value of a field can be found
         * @return offset.
         */
        int getOffset();

        /**
         * Get complete map of context properties.
         * @return map of all available 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);

        /**
         * 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, Exception error, 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 id);
    }
}