Candidate release of source code.

Ghidra/Features/SourceCodeLookup/src/main/help/help/TOC_Source.xml

@@ -0,0 +1,54 @@
+<?xml version='1.0' encoding='ISO-8859-1' ?>
+<!-- 
+
+	This is an XML file intended to be parsed by the Ghidra help system.  It is loosely based 
+	upon the JavaHelp table of contents document format.  The Ghidra help system uses a 
+	TOC_Source.xml file to allow a module with help to define how its contents appear in the 
+	Ghidra help viewer's table of contents.  The main document (in the Base module) 
+	defines a basic structure for the 
+	Ghidra table of contents system.  Other TOC_Source.xml files may use this structure to insert
+	their files directly into this structure (and optionally define a substructure).
+	
+	
+	In this document, a tag can be either a <tocdef> or a <tocref>.  The former is a definition
+	of an XML item that may have a link and may contain other <tocdef> and <tocref> children.  
+	<tocdef> items may be referred to in other documents by using a <tocref> tag with the 
+	appropriate id attribute value.  Using these two tags allows any module to define a place 
+	in the table of contents system (<tocdef>), which also provides a place for 
+	other TOC_Source.xml files to insert content (<tocref>).  
+	
+	During the help build time, all TOC_Source.xml files will be parsed and	validated to ensure
+	that all <tocref> tags point to valid <tocdef> tags.  From these files will be generated
+	<module name>_TOC.xml files, which are table of contents files written in the format 
+	desired by the JavaHelp system.   Additionally, the genated files will be merged together
+	as they are loaded by the JavaHelp system.  In the end, when displaying help in the Ghidra
+	help GUI, there will be on table of contents that has been created from the definitions in 
+	all of the modules' TOC_Source.xml files.
+
+	
+	Tags and Attributes
+	
+	<tocdef>
+	-id          - the name of the definition (this must be unique across all TOC_Source.xml files)	
+	-text        - the display text of the node, as seen in the help GUI
+	-target**    - the file to display when the node is clicked in the GUI
+	-sortgroup   - this is a string that defines where a given node should appear under a given
+	               parent.  The string values will be sorted by the JavaHelp system using
+	               a javax.text.RulesBasedCollator.  If this attribute is not specified, then
+	               the text of attribute will be used.
+
+	<tocref>
+	-id			 - The id of the <tocdef> that this reference points to 
+	
+	**The URL for the target is relative and should start with 'help/topics'.  This text is 
+	used by the Ghidra help system to provide a universal starting point for all links so that
+	they can be resolved at runtime, across modules.
+	
+	
+-->
+
+
+<tocroot>
+
+
+</tocroot>                  

Ghidra/Features/SourceCodeLookup/src/main/help/help/shared/Frontpage.css

@@ -0,0 +1,58 @@
+/* ###
+ * IP: GHIDRA
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * 
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/*
+									WARNING!
+    This file is copied to all help directories.  If you change this file, you must copy it 
+    to each src/main/help/help/shared directory.									
+									
+	
+	Java Help Note:  JavaHelp does not accept sizes (like in 'margin-top') in anything but 
+	px (pixel) or with no type marking. 
+
+*/ 
+
+body { margin-bottom: 50px; margin-left: 10px; margin-right: 10px; margin-top: 10px; } /* some padding to improve readability */ 
+li { font-family:times new roman; font-size:14pt; }
+h1 { color:#000080; font-family:times new roman; font-size:36pt; font-style:italic; font-weight:bold; text-align:center; }
+h2 { margin: 10px; margin-top: 20px; color:#984c4c; font-family:times new roman; font-size:18pt; font-weight:bold; }
+h3 { margin-left: 10px; margin-top: 20px; color:#0000ff; font-family:times new roman; font-size:14pt; font-weight:bold;  }
+h4 { margin-left: 10px; margin-top: 20px; font-family:times new roman; font-size:14pt; font-style:italic; }
+ 
+/*
+	 P tag code.  Most of the help files nest P tags inside of blockquote tags (the was the 
+	 way it had been done in the beginning).  The net effect is that the text is indented.  In 
+	 modern HTML we would use CSS to do this.  We need to support the Ghidra P tags, nested in
+	 blockquote tags, as well as naked P tags.  The following two lines accomplish this.  Note
+	 that the 'blockquote p' definition will inherit from the first 'p' definition.
+*/
+p { margin-left: 40px; font-family:times new roman; font-size:14pt; }
+blockquote p { margin-left: 10px; }
+
+p.providedbyplugin { color:#7f7f7f; margin-left: 10px; font-size:14pt; margin-top:100px  }
+p.ProvidedByPlugin { color:#7f7f7f; margin-left: 10px; font-size:14pt; margin-top:100px }
+p.relatedtopic { color:#800080; margin-left: 10px; font-size:14pt; }
+p.RelatedTopic { color:#800080; margin-left: 10px; font-size:14pt; }
+
+/* 
+	We wish for a tables to have space between it and the preceding element, so that text
+	is not too close to the top of the table.  Also, nest the table a bit so that it is clear
+	the table relates to the preceding text.
+*/
+table { margin-left: 20px; margin-top: 10px; width: 80%;}
+td { font-family:times new roman; font-size:14pt; vertical-align: top; }
+th { font-family:times new roman; font-size:14pt; font-weight:bold; background-color: #EDF3FE; }
+
+code { color: black; font-family: courier new; font-size: 14pt; }

Ghidra/Features/SourceCodeLookup/src/main/help/help/topics/SourceCodeLookupPlugin/Source_Code_Lookup.html

@@ -0,0 +1,106 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+
+<HTML>
+  <HEAD>
+    <META name="generator" content=
+    "HTML Tidy for Java (vers. 2009-12-01), see jtidy.sourceforge.net">
+    <META http-equiv="Content-Language" content="en-us">
+    <META http-equiv="Content-Type" content="text/html; charset=windows-1252">
+
+    <TITLE>Source Code Lookup Plugin</TITLE>
+    <LINK rel="stylesheet" type="text/css" href="../../shared/Frontpage.css">
+    <META name="generator" content="Microsoft FrontPage 4.0">
+  </HEAD>
+
+  <BODY>
+    <H1><A name="Source_Code_Lookup_Plugin"></A>Source Code Lookup Plugin</H1>
+
+    <BLOCKQUOTE>
+      <P><I>Source Code Lookup</I> attempts to look up a symbol contained within a Ghidra program,
+      in the source of a C/C++ Eclipse project.</P>
+
+      <P><IMG src="../../shared/note.png" alt="" border="0"> <B>This plugin requires that Eclipse,
+      the Eclipse GhidraDev plugin, and the Eclipse CDT plugin are installed on your system.</B></P>
+
+      <H2>Setting up Eclipse</H2>
+
+      <BLOCKQUOTE>
+        <OL>
+          <LI>Install Eclipse.  The <I>Minimum Requirements</I> section of 
+          <B><I>Extensions/Eclipse/GhidraDev/GhidraDev_README.html</I></B> describes what versions
+          of Eclipse are supported.  Note that Eclipse is not provided by Ghidra...it must obtained
+          independently.</LI>
+          
+          <LI>Install the Eclipse GhidraDev plugin into Eclipse. See 
+          <B><I>Extensions/Eclipse/GhidraDev/GhidraDev_README.html</I></B> 
+          for information on how to install the GhidraDev plugin into Eclipse.  Your Ghidra
+          distribution provides the most up-to-date version of the GhidraDev plugin at the time of
+          that distribution's release.</LI>
+          
+          <LI>Install the Eclipse CDT plugin into Eclipse.  The <I>Minimum Requirements</I> section 
+          of <B><I>Extensions/Eclipse/GhidraDev/GhidraDev_README.html</I></B> describes what 
+          versions of the CDT are supported.  Note that the CDT is not provided by Ghidra...it must
+          be obtained independently.</LI>
+          
+          <LI>Create a new C/C++ project (<B>File &rarr; New &rarr; Project...</B>) and give it a
+          name<FONT size="3"></FONT>. The other options do not matter for this plugin.</LI>
+
+          <LI>Drag any source code for the binary into the Eclipse project</LI>
+
+          <LI>Change the Eclipse indexer settings if necessary (Right click on your project and
+          select <B>Properties &rarr; C/C++ General &rarr; Indexer</B>). Options such as "Index
+          source files not included in the build" and "Index unused headers" will make sure that
+          all of the files in the project get indexed if you have partial source code</LI>
+
+          <LI>Edit the GhidraDev Eclipse preferences to point to the project you want to search
+          (<B>Eclipse</B> or <B>Window &rarr; Preferences... &rarr; GhidraDev &rarr; Symbol
+          Lookup &rarr; Project Name</B>). The name used here must match the name of the C++ project
+          created in above.</LI>
+        </OL>
+      </BLOCKQUOTE>
+
+      <H2>Using Source Code Lookup</H2>
+
+      <BLOCKQUOTE>
+        <P>To use the source code lookup feature, place the <A href=
+        "help/topics/CodeBrowserPlugin/CodeBrowser.htm">Listing</A> cursor on the symbol you want
+        to lookup and choose from the menu <B>Navigation &rarr; Go To Symbol Source</B>.</P>
+        <P>You can also execute this action when your cursor is in the <A href=
+        "help/topics/DecompilePlugin/Decompiler.htm">Decompiler</A>.<P>
+      </BLOCKQUOTE>
+
+      <H2>Troubleshooting</H2>
+
+      <BLOCKQUOTE>
+        <UL>
+          <LI>
+            The port numbers may not match between Ghidra and Eclipse 
+
+            <UL>
+              <LI>Check that the Ghidra port (Ghidra Front End GUI: <B>Edit &rarr; Tool Options... 
+              &rarr; Eclipse Integration &rarr; Symbol Lookup Port</B>) matches the Eclipse port 
+              (<B>Preferences &rarr; GhidraDev &rarr; Symbol Lookup &rarr; Port</B>)</LI>
+            </UL>
+          </LI>
+
+          <LI>
+            The Eclipse plugin may be using the wrong project 
+
+            <UL>
+              <LI>Select the C/C++ project to be used by the Eclipse plugin (<B>Preferences &rarr;
+              GhidraDev &rarr; Symbol Lookup &rarr; Project Name</B>)</LI>
+            </UL>
+          </LI>
+        </UL>
+      </BLOCKQUOTE>
+
+      <P class="providedbyplugin">Provided by: <I>Source Code Lookup Plugin</I></P>
+
+      <P class="relatedtopic">Related Topics:</P>
+
+      <UL>
+        <LI><A href="help/topics/CodeBrowserPlugin/CodeBrowser.htm">Code Browser</A></LI>
+      </UL>
+    </BLOCKQUOTE>
+  </BODY>
+</HTML>

Ghidra/Features/SourceCodeLookup/src/main/java/ghidra/app/plugin/core/scl/SourceCodeLookupPlugin.java

@@ -0,0 +1,250 @@
+/* ###
+ * IP: GHIDRA
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * 
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package ghidra.app.plugin.core.scl;
+
+import java.awt.event.KeyEvent;
+import java.io.*;
+import java.net.Socket;
+
+import docking.ActionContext;
+import docking.action.*;
+import ghidra.app.CorePluginPackage;
+import ghidra.app.context.ProgramLocationActionContext;
+import ghidra.app.decompiler.*;
+import ghidra.app.events.ProgramLocationPluginEvent;
+import ghidra.app.plugin.PluginCategoryNames;
+import ghidra.app.plugin.ProgramPlugin;
+import ghidra.app.plugin.core.eclipse.EclipseConnection;
+import ghidra.app.plugin.core.eclipse.EclipseIntegrationOptionsPlugin;
+import ghidra.app.plugin.core.navigation.locationreferences.*;
+import ghidra.app.services.EclipseIntegrationService;
+import ghidra.app.util.demangler.DemangledObject;
+import ghidra.app.util.demangler.DemanglerUtil;
+import ghidra.framework.options.ToolOptions;
+import ghidra.framework.plugintool.PluginInfo;
+import ghidra.framework.plugintool.PluginTool;
+import ghidra.framework.plugintool.util.PluginStatus;
+import ghidra.framework.plugintool.util.ToolConstants;
+import ghidra.util.HelpLocation;
+import ghidra.util.Msg;
+
+//@formatter:off
+@PluginInfo(
+	status = PluginStatus.RELEASED,
+	packageName = CorePluginPackage.NAME,
+	category = PluginCategoryNames.MISC,
+	shortDescription = "Source Code Lookup Plugin",
+	description = "Plugin to send requests to the development IDE to lookup symbols in source files.",
+	servicesRequired = { EclipseIntegrationService.class },
+	eventsConsumed = { ProgramLocationPluginEvent.class }
+)
+//@formatter:on
+public class SourceCodeLookupPlugin extends ProgramPlugin {
+
+	private static final String ACTION_NAME = "Go To Symbol Source";
+
+	private static final String CDT_START = "org.eclipse.cdt.core_";
+
+	private DockingAction lookupSourceCodeAction;
+
+	public SourceCodeLookupPlugin(PluginTool tool) {
+		super(tool, false, false);
+	}
+
+	@Override
+	protected void dispose() {
+		super.dispose();
+	}
+
+	@Override
+	public void init() {
+		super.init();
+
+		lookupSourceCodeAction = new DockingAction("Source Code Lookup", getName()) {
+			@Override
+			public void actionPerformed(ActionContext context) {
+				lookupSymbol();
+			}
+
+			@Override
+			public boolean isEnabledForContext(ActionContext context) {
+				return context instanceof ProgramLocationActionContext;
+			}
+		};
+
+		// put the menu bar data with the GoTo action group--at the end
+		lookupSourceCodeAction.setMenuBarData(
+			new MenuData(new String[] { ToolConstants.MENU_NAVIGATION, ACTION_NAME }, null, "GoTo",
+				MenuData.NO_MNEMONIC, "z"));
+
+		// TODO: having this action in the decompiler and the listing causes issues in terms of
+		// how to define the group/menu position.  For now, just put the menu in the main menu bar.
+		// lookupSourceCodeAction.setPopupMenuData(new MenuData(POPUP_PATH, null, "Label",
+		// MenuData.NO_MNEMONIC, "z"));
+		lookupSourceCodeAction.setKeyBindingData(new KeyBindingData(KeyEvent.VK_F3, 0));
+		lookupSourceCodeAction.setHelpLocation(
+			new HelpLocation("SourceCodeLookupPlugin", "Source_Code_Lookup_Plugin"));
+		tool.addAction(lookupSourceCodeAction);
+	}
+
+	private void lookupSymbol() {
+
+		String symbolText = getSymbolText();
+		if (symbolText == null) {
+			return;
+		}
+
+		String demangled = attemptToDemangle(symbolText);
+		if (demangled != null) {
+			symbolText = demangled;
+		}
+
+		EclipseIntegrationService service = tool.getService(EclipseIntegrationService.class);
+		ToolOptions options = service.getEclipseIntegrationOptions();
+		int port = options.getInt(EclipseIntegrationOptionsPlugin.SYMBOL_LOOKUP_PORT_OPTION, -1);
+		if (port < 0 || port > Short.MAX_VALUE) {
+			service.handleEclipseError(
+				"Option \"" + EclipseIntegrationOptionsPlugin.SYMBOL_LOOKUP_PORT_OPTION +
+					"\" is not valid.  Cannot connect to Eclipse.",
+				true, null);
+			return;
+		}
+		while (true) {
+			EclipseConnection connection = service.connectToEclipse(port);
+			Socket clientSocket = connection.getSocket();
+			if (clientSocket == null) {
+				handleUnableToConnect(connection);
+				return;
+			}
+			try (BufferedReader input =
+				new BufferedReader(new InputStreamReader(clientSocket.getInputStream()));
+					PrintStream output = new PrintStream(clientSocket.getOutputStream())) {
+
+				output.print(symbolText + "\n");
+				output.flush();
+
+				String reply = input.readLine();
+				Msg.debug(this, reply);
+				tool.setStatusInfo(reply);
+
+				if (symbolText.startsWith("_")) {
+					symbolText = symbolText.substring(1);
+				}
+				else {
+					break;
+				}
+			}
+			catch (IOException e) {
+				// shouldn't happen
+				Msg.showError(this, null, "Unexpected Exception",
+					"Unexpected exception " + "connecting to source lookup editor", e);
+				return;
+			}
+			finally {
+				try {
+					clientSocket.close();
+				}
+				catch (IOException e) {
+					// Nothing to do
+				}
+			}
+		}
+	}
+
+	private String getSymbolText() {
+		String symbolText = null;
+
+		if (currentLocation instanceof DecompilerLocation) {
+			DecompilerLocation decompilerLocation = (DecompilerLocation) currentLocation;
+			ClangToken token = decompilerLocation.getToken();
+			if (token == null) {
+				return null;
+			}
+
+			if (token instanceof ClangFieldToken || token instanceof ClangFuncNameToken ||
+				token instanceof ClangLabelToken || token instanceof ClangTypeToken) {
+				symbolText = token.getText();
+			}
+
+// TODO: we could improve the logic for finding lookup text: we could use the datatype values,
+//	     like those below to make a better name.  There could be other tricks we could do,
+//		 depending upon the token type and its information.  For now, just use the text for types
+//	     that may be valid.
+//
+//				if (symbolText == null) {
+//					if (token instanceof ClangFieldToken) {
+//						symbolText = tokenName;
+//					}
+//					else if (token instanceof ClangTypeToken) {
+//						symbolText = tokenName;
+//					}
+//				}
+//			}
+
+		}
+		else {
+			LocationDescriptor locationDescriptor =
+				ReferenceUtils.getLocationDescriptor(currentLocation);
+			if (locationDescriptor == null) {
+				return null;
+			}
+			symbolText = getSymbolTextFromLocation(locationDescriptor);
+		}
+		return symbolText;
+	}
+
+	private String getSymbolTextFromLocation(LocationDescriptor locationDescriptor) {
+		if (locationDescriptor.getClass() == AddressLocationDescriptor.class) {
+			return null;
+		}
+		return locationDescriptor.getLabel();
+	}
+
+	private String attemptToDemangle(String nameToDemangle) {
+		if (nameToDemangle == null) {
+			return null;
+		}
+		DemangledObject demangledObject = DemanglerUtil.demangle(nameToDemangle);
+		if (demangledObject != null) {
+			return demangledObject.getName();
+		}
+		return null;
+	}
+
+	private void handleUnableToConnect(EclipseConnection connection) {
+		EclipseIntegrationService service = tool.getService(EclipseIntegrationService.class);
+		try {
+			if (!service.isEclipseFeatureInstalled(
+				(dir, filename) -> filename.startsWith(CDT_START))) {
+				Msg.showWarn(this, null, "No CDT Installed",
+					"No CDT installed in Eclipse. You must install the CDT before\n" +
+						"using the source code lookup plugin.");
+				return;
+			}
+		}
+		catch (FileNotFoundException e) {
+			// Eclipse is not installed.
+		}
+
+		if (connection.getProcess() != null) {
+			Msg.showWarn(this, null, "Ports May Not Match",
+				"The port used by Ghidra may not match the port used by Eclipse.\nMake sure " +
+					"the port in the Ghidra options (Edit -> Tool Options... -> Source Code Lookup) \n" +
+					"matches the port in the Eclipse preference page " +
+					"(Preferences -> Ghidra -> Ghidra Symbol Lookup).");
+		}
+	}
+}