View Javadoc
1   /*
2    * Copyright (c) 2000, 2009, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.
8    *
9    * This code is distributed in the hope that it will be useful, but WITHOUT
10   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
12   * version 2 for more details (a copy is included in the LICENSE file that
13   * accompanied this code).
14   *
15   * You should have received a copy of the GNU General Public License version
16   * 2 along with this work; if not, write to the Free Software Foundation,
17   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
18   *
19   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
20   * or visit www.oracle.com if you need additional information or have any
21   * questions.
22   *
23   */
24  
25  package sun.jvm.hotspot.debugger;
26  
27  import java.util.*;
28  import sun.jvm.hotspot.debugger.cdbg.CDebugger;
29  
30  public interface Debugger extends SymbolLookup, ThreadAccess {
31    /** Indicates whether this underlying debugger can provide a list of
32        currently-running processes. */
33    public boolean hasProcessList() throws DebuggerException;
34  
35    /** Provide a snapshot of the list of currently-running processes in
36        the form of a List of ProcessInfo objects. Must only be called
37        if hasProcessList(), above, returns true. */
38    public List getProcessList() throws DebuggerException;
39  
40    /** If an error occurs during attachment (i.e., "no such process"),
41        the thrown DebuggerException will contain a description of the
42        error in its message string. */
43    public void attach(int processID) throws DebuggerException;
44  
45    /** This attaches the debugger to the given coreFileName, which is
46        assumed to have been generated from the specified
47        executableName. If an error occurs during loading of the core
48        file (i.e., "no such file"), the thrown DebuggerException will
49        contain a description of the error in its message string. */
50    public void attach(String executableName, String coreFileName)
51      throws DebuggerException;
52  
53    /** Detach from the remote process. Returns false if not currently
54        attached. */
55    public boolean detach() throws DebuggerException;
56  
57    /** Parse an address from a hex string in the format "0xFFFFFFFF".
58        The length of the address (i.e., 32 or 64 bits) is platform
59        dependent. This method should ONLY be used by routines which
60        need to interact with the user and parse a string entered by
61        hand; for example, a graphical user interface. This routine
62        should NOT be used to subvert the current safety mechanisms in
63        the system which prevent arbitrary conversion from Address to
64        long and back. */
65    public Address parseAddress(String addressString)
66      throws NumberFormatException, DebuggerException;
67  
68    /** Returns the 64-bit value of an Address. This method should ONLY
69        be used when implementing a debugger which needs to interface to
70        C and which needs a unique identifier for certain objects. */
71    public long getAddressValue(Address addr) throws DebuggerException;
72  
73    /** Support for remote debugging. Get the name of the operating
74        system on which this debugger is running (to be able to properly
75        configure the local system). Typical return values are
76        "solaris", "linux", "win32"; see utilities/PlatformInfo.java. */
77    public String getOS() throws DebuggerException;
78  
79    /** Support for remote debugging. Get the name of the CPU type on
80        which this debugger is running (to be able to properly configure
81        the local system). Typical return values are "sparc", "x86"; see
82        utilities/PlatformInfo.java. */
83    public String getCPU() throws DebuggerException;
84  
85    /** Retrieve the machine description for the underlying hardware for
86        the cases in which we need to do, for example, machine-dependent
87        byte swapping */
88    public MachineDescription getMachineDescription() throws DebuggerException;
89  
90    /** Find out whether this debugger has a console available on which
91        commands can be executed; see executeCommandOnConsole, below.
92        This is an interim routine designed to allow access to the
93        underlying dbx process on Solaris until we have disassembly,
94        etc. in the SA. */
95    public boolean hasConsole() throws DebuggerException;
96  
97    /** If the underlying debugger has a console (as dbx does), this
98        provides access to it. Takes in a platform-dependent String,
99        executes it on the debugger's console, and returns any output as
100       a String. */
101   public String consoleExecuteCommand(String cmd) throws DebuggerException;
102 
103   /** If the underlying debugger has a console, this returns the
104       debugger-specific prompt which should be displayed. */
105   public String getConsolePrompt() throws DebuggerException;
106 
107   /** If this platform supports C/C++ debugging via the CDebugger
108       interface, returns a CDebugger object; otherwise returns
109       null. */
110   public CDebugger getCDebugger() throws DebuggerException;
111 
112   /** the following methods are intended only for RemoteDebuggerClient */
113   public long getJBooleanSize();
114   public long getJByteSize();
115   public long getJCharSize();
116   public long getJDoubleSize();
117   public long getJFloatSize();
118   public long getJIntSize();
119   public long getJLongSize();
120   public long getJShortSize();
121   public long getHeapOopSize();
122   public long getNarrowOopBase();
123   public int  getNarrowOopShift();
124   public long getKlassPtrSize();
125   public long getNarrowKlassBase();
126   public int  getNarrowKlassShift();
127 
128   public ReadResult readBytesFromProcess(long address, long numBytes)
129     throws DebuggerException;
130 
131   public void writeBytesToProcess(long address, long numBytes, byte[] data)
132     throws UnmappedAddressException, DebuggerException;
133 }