/*******************************************************************************
 * Copyright (c) 2009, 2010 Nokia 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:
 * Nokia - Initial API and implementation
 *******************************************************************************/

package org.eclipse.cdt.debug.edc.services;

import java.util.Map;

import org.eclipse.cdt.core.IAddress;
import org.eclipse.cdt.debug.edc.IAddressExpressionEvaluator;
import org.eclipse.cdt.debug.edc.disassembler.IDisassembler;
import org.eclipse.cdt.debug.edc.tcf.extension.services.ISimpleRegisters;
import org.eclipse.cdt.dsf.concurrent.RequestMonitor;
import org.eclipse.cdt.dsf.datamodel.IDMContext;
import org.eclipse.cdt.dsf.debug.service.IRunControl.IExecutionDMContext;
import org.eclipse.cdt.dsf.service.IDsfService;
import org.eclipse.tm.tcf.services.IRegisters;

/**
 * DSF service that provides data peculiar to the environment the debugger is
 * targeting. The environment here includes such things as target hardware, OS
 * if any, and UI preferences for the debugger. <br>
 * This service is supposed to be called by other DSF services so that they can
 * be target independent as much as possible.
 */
public interface ITargetEnvironment extends IDsfService {

	public final static String ARCH_X86 = "x86";
	public final static String ARCH_ARM = "ARM";

	public final static String OS_UNKNOWN = "unknown";
	public final static String OS_WIN32 = "win32";
	public final static String OS_LINUX = "linux";
	public final static String OS_SYMBIAN = "symbian";

	/**
	 * Get the string name of the target system architecture.
	 * 
	 * @return string name which is one of the predefined ARCH_xx string in
	 *         {@link ITargetEnvironment}. Cannot be null.
	 */
	public String getArchitecture();

	/**
	 * Get the string name of the target operating system (if any).
	 * 
	 * @return string name which is one of the predefined OS_xx string in
	 *         {@link ITargetEnvironment}. Cannot be null.
	 *         {@link ITargetEnvironment#OS_UNKNOWN} if the OS is unknown. Empty
	 *         string if there is no OS running.
	 */
	public String getOS();

	/**
	 * Get sizes of all basic C/C++ data types.
	 * 
	 * @return list of sizes, in bytes, of C/C++ data types. The returned map
	 *         should have TypeUtils#BASIC_TYPE_XXX constants for its keys, and
	 *         type sizes for their values
	 */
	public Map<Integer, Integer> getBasicTypeSizes();

	/**
	 * Get size of pointer data type
	 * 
	 * @return list of sizes, in bytes, of C/C++ data types
	 */
	public int getPointerSize();

	/**
	 * Get size of an enumeration data type
	 * 
	 * @return list of sizes, in bytes, of C/C++ data types
	 */
	public int getEnumSize();

	/**
	 * Get whether plain "char" is signed
	 * 
	 * @return whether "plain" char is signed
	 */
	public boolean isCharSigned();

	/**
	 * Get ID of program counter (PC) register. E.g. for X86, it could be "EIP". <br>
	 * <br>
	 * (This is temporarily needed with our current TCF {@link ISimpleRegisters}
	 * service. After we implement the TCF {@link IRegisters} service, this can
	 * be removed.)
	 * 
	 * @return string representation of the register ID.
	 */
	public String getPCRegisterID();

	/**
	 * Get length in bytes of the longest instruction in target architecture.
	 * This return value does not have to be precise, but must be larger than
	 * size of the longest instruction.
	 * 
	 * @return
	 */
	public int getLongestInstructionLength();

	/**
	 * Get breakpoint instruction that is used to set software breakpoint.<br>
	 * <br>
	 * For architecture like x86 the breakpoint instruction is invariant
	 * ("int 3" or "0xcc") thus the arguments are ignored. But for processor
	 * like ARM the instruction varies depending on processor mode (ARM or
	 * THUMB) in give context.
	 * 
	 * @param context
	 *            the runtime context, usually a process.
	 * @param address
	 *            runtime absolute address where to set a breakpoint.
	 * 
	 * @return byte array of the instruction.
	 */
	public byte[] getBreakpointInstruction(IDMContext context, IAddress address);

	/**
	 * Allows for modification or addition of target specific breakpoint
	 * properties before breakpoints are set. Note that this applies to TCF
	 * breakpoint service breakpoints.
	 * 
	 * @param context
	 *            the runtime context, usually a process.
	 * @param address
	 *            runtime absolute address where to set a breakpoint.
	 * @param properties
	 *            properties map
	 */
	public void updateBreakpointProperties(IDMContext context, IAddress address, Map<String, Object> properties);

	/**
	 * Is the target processor in little-endian ?
	 * 
	 * @param context
	 *            context for which the check is based on. For most cases this
	 *            argument can be ignored.
	 * @return
	 */
	public boolean isLittleEndian(IDMContext context);

	/**
	 * Get disassembler for the target.
	 * 
	 * @return {@link IDisassembler} object. Can be null which means
	 *         disassembler is not implemented yet for the target.
	 */
	public IDisassembler getDisassembler();

	/**
	 * Get address expression evaluator for the target.
	 * 
	 * @return {@link IAddressExpressionEvaluator} object. null means it's not
	 *         available yet for the target.
	 */
	public IAddressExpressionEvaluator getAddressExpressionEvaluator();

	/**
	 * In some target environments, user may specify two or more executables
	 * (including things like DLL) to debug in one debug session. This API
	 * allows the target environment to tell EDC in which executable(s) it wants
	 * EDC to try to set startup breakpoint.
	 * 
	 * @param exeName
	 *            a name with or without path.
	 * @return true if the environment wants EDC to try setting startup
	 *         breakpoint in the executable. False otherwise.
	 * @since 2.0
	 */
	public boolean needStartupBreakpointInExecutable(String exeName);
	
	/**
	 * Get minimum size of a memory block that is read and stored in memory
	 * cache. For instance, if the size is 64 bytes, then for a memory read
	 * request that requests 4 bytes, the debugger will read and cache 64 bytes.
	 * Different targets may prefer different size.
	 * 
	 * @return size in bytes. zero (0) means to just cache the number of bytes
	 *         actually requested.
	 */
	public int getMemoryCacheMinimumBlockSize();
	
	/**
	 * Get value of any given property.<br>
	 * <br>
	 * This generic API allows getting any new target property without adding
	 * new API that breaks backward compatibility.
	 * 
	 * @param propertyKey
	 * @return
	 */
	public String getProperty(String propertyKey);

	/**
	 * Check if instruction(s) at PC are glue code (e.g. jump table for call to
	 * DLL functions on Windows), if yes, step past them. Otherwise just do
	 * nothing.<br>
	 * This is only called when we perform stepping.
	 * 
	 * @param dmc
	 *            the execution context, usually a thread.
	 * @param pc
	 *            program counter.
	 * @param rm
	 * @since 3.0
	 */
	public void stepPastGlueCode(IExecutionDMContext dmc, IAddress pc,
			RequestMonitor rm);
}