mirror of
https://github.com/NationalSecurityAgency/ghidra.git
synced 2025-10-03 17:59:46 +02:00
Merge remote-tracking branch 'origin/GP-5319_James_source_map_help_improvements--SQUASHED'
This commit is contained in:
Ryan Kurtz
commit
aaf910bd82
1 changed files with 107 additions and 102 deletions
|
|
@ -11,129 +11,11 @@
|
||||||
</HEAD>
|
</HEAD>
|
||||||
|
|
||||||
<BODY>
|
<BODY>
|
||||||
<H1>Source File Information</H1>
|
|
||||||
|
|
||||||
<P>Ghidra can store information about the source files for a program, including their locations
|
|
||||||
in the build environment and the correspondence between lines of source code and addresses in a
|
|
||||||
program. A common source of this information is debug data, such as DWARF or PDB.</P>
|
|
||||||
|
|
||||||
<P>A major use case of this information is to synchronize Ghidra with an IDE, such as
|
|
||||||
Eclipse.</P>
|
|
||||||
|
|
||||||
<H2>Source Files</H2>
|
|
||||||
|
|
||||||
<P>A source file record in Ghidra consists of three pieces of information:</P>
|
|
||||||
|
|
||||||
<BLOCKQUOTE>
|
|
||||||
<OL>
|
|
||||||
<LI>A path, which must be an absolute, normalized path using forward slashes.
|
|
||||||
E.g., "/usr/src/main/file.c", "/C:/Users/Ghidra/sourceFile.cc".</LI>
|
|
||||||
|
|
||||||
<LI>A <I>SourceFileIdType</I>, which can be NONE, UNKNOWN, TIMESTAMP_64, MD5, SHA1, SHA256,
|
|
||||||
or SHA512.</LI>
|
|
||||||
|
|
||||||
<LI>An identifier, which is the value of the identifier as a byte array.</LI>
|
|
||||||
</OL>
|
|
||||||
</BLOCKQUOTE>
|
|
||||||
|
|
||||||
<H2>Source Map Entries</H2>
|
|
||||||
|
|
||||||
<P>A <I>Source Map Entry</I> associates a source file and a line number to an address or
|
|
||||||
address range in a program. It consists of:</P>
|
|
||||||
|
|
||||||
<BLOCKQUOTE>
|
|
||||||
<OL>
|
|
||||||
<LI>A source file.</LI>
|
|
||||||
|
|
||||||
<LI>A line number.</LI>
|
|
||||||
|
|
||||||
<LI>A base address.</LI>
|
|
||||||
|
|
||||||
<LI>A length. If the length is non-zero, the entry defines an address range, otherwise it
|
|
||||||
defines an address.</LI>
|
|
||||||
</OL>
|
|
||||||
</BLOCKQUOTE><BR>
|
|
||||||
<BR>
|
|
||||||
|
|
||||||
|
|
||||||
<P>Source map entries are constrained as follows:</P>
|
|
||||||
|
|
||||||
<BLOCKQUOTE>
|
|
||||||
<UL>
|
|
||||||
<LI>An address in a program may not have duplicate (same source file, line number, base
|
|
||||||
address, and length) source file entries.</LI>
|
|
||||||
|
|
||||||
<LI>Given two source map entries with non-zero lengths, their associated address ranges
|
|
||||||
must be either identical or distinct (i.e., no partial overlaps). Multiple source maps
|
|
||||||
entries based at the same address are allowed as long as they obey this restriction. Length
|
|
||||||
zero entries may occur anywhere, including within ranges corresponding to entries of
|
|
||||||
non-zero lengths.</LI>
|
|
||||||
</UL>
|
|
||||||
</BLOCKQUOTE><BR>
|
|
||||||
<BR>
|
|
||||||
|
|
||||||
|
|
||||||
<H2>Source File Manager</H2>
|
|
||||||
|
|
||||||
<P>Source files and source map entries are managed by a program's source file manager (accessed
|
|
||||||
via Program.getSourceFileManager()). A source file must be added to a program before it can
|
|
||||||
used in a source map entry.</P>
|
|
||||||
|
|
||||||
<BLOCKQUOTE>
|
|
||||||
<P><IMG src="help/shared/note.png" alt="Note" border="0">Note that adding source files,
|
|
||||||
removing source files, or changing the source map requires an exclusive checkout if
|
|
||||||
the program is in a shared Ghidra repository. Reading the source file list or source map does
|
|
||||||
not require an exclusive checkout.</P>
|
|
||||||
<BR>
|
|
||||||
</BLOCKQUOTE><BR>
|
|
||||||
<BR>
|
|
||||||
|
|
||||||
|
|
||||||
<H2>Source Path Transformations</H2>
|
|
||||||
|
|
||||||
<P>Source file path information can be sent to an external tool, such as an IDE. However, there
|
|
||||||
is no guarantee that a path recorded for a source file exists on the machine running Ghidra.
|
|
||||||
For instance, you could use Ghidra running under Linux to analyze a Windows program with source
|
|
||||||
file information. An additional complication is that the program may be in a shared Ghidra
|
|
||||||
repository where users have different operating systems or local file systems. We solve this
|
|
||||||
issue by allowing users to modify source file paths. The modifications are stored locally for
|
|
||||||
each user and are not checked in to a shared repository.</P>
|
|
||||||
|
|
||||||
<P>A note on terminology: to avoid overuse of the word "map", we use "map" when discussing the
|
|
||||||
association of a source file and a line number to an address and length in a program (the
|
|
||||||
"source file map"). We use the word "transform" when discussing user-determined modifications
|
|
||||||
of a source file's path.</P>
|
|
||||||
|
|
||||||
<P>There are two type of source path transforms:</P>
|
|
||||||
|
|
||||||
<BLOCKQUOTE>
|
|
||||||
<OL>
|
|
||||||
<LI><I>File Transforms</I>, which entirely replace a source file's path with another file
|
|
||||||
path.</LI>
|
|
||||||
|
|
||||||
<LI><I>Directory Transforms</I>, which replace a parent directory of a source file's path
|
|
||||||
with another directory. For example, the directory transform "/src/ -> "/usr/test/files/"
|
|
||||||
would transform the path "/src/dir1/file.c" to "/usr/test/files/dir1/file.c".</LI>
|
|
||||||
</OL>
|
|
||||||
</BLOCKQUOTE><BR>
|
|
||||||
<BR>
|
|
||||||
|
|
||||||
|
|
||||||
<P>Given a source file, the transformed path is determined as follows. If there is a file
|
|
||||||
transform for that particular file, the file transform is applied. Otherwise, the most specific
|
|
||||||
directory transform (i.e., the one replacing the longest initial segment of the path) is
|
|
||||||
applied. If no transform is applied, the user may opt to use the untransformed path.</P>
|
|
||||||
|
|
||||||
<P>Source file path transformations are managed using a <I>SourcePathTransformer</I>. Path
|
|
||||||
transformations can be managed using the actions on the <A href="#Source_Files_Table">Source
|
|
||||||
Files Table</A>. In a script, you can get the path transformer for a program via the static
|
|
||||||
method <I>UserDataPathTransformer.getPathTransformer(Program)</I>. Note that modifications to
|
|
||||||
the path transformer are not affected by undo or redo actions in Ghidra.</P>
|
|
||||||
|
|
||||||
<H1><A name="Source_Files_Table_Plugin"></A>Source Files Table Plugin</H1>
|
<H1><A name="Source_Files_Table_Plugin"></A>Source Files Table Plugin</H1>
|
||||||
|
|
||||||
<P>This plugin shows the source file information associated with the current program and allows
|
<P>This plugin shows the source file information (described <A href=
|
||||||
the user to manage source file path transforms.</P>
|
"#Source_File_Information">below</A>) associated with the current program and allows the user
|
||||||
|
to manage source file path transforms.</P>
|
||||||
|
|
||||||
<H2><A name="Source_Files_Table"></A>Source Files Table</H2>
|
<H2><A name="Source_Files_Table"></A>Source Files Table</H2>
|
||||||
|
|
||||||
|
|
@ -187,43 +69,166 @@
|
||||||
<BLOCKQUOTE>
|
<BLOCKQUOTE>
|
||||||
<H3><A name="View_Source"></A>View Source</H3>
|
<H3><A name="View_Source"></A>View Source</H3>
|
||||||
|
|
||||||
<P>This Listing action is enabled if there is source map information
|
<P>This Listing action is enabled if there is source map information for an address. It will
|
||||||
for an address. It will open the corresponding source file at the
|
open the corresponding source file at the appropriate line in a source code viewer (currently
|
||||||
appropriate line in a source code viewer (currently Eclipse and VS Code
|
Eclipse and VS Code are supported). Options for configuring the viewer are described <A href=
|
||||||
are supported). Options for configuring the viewer are described
|
"#Source_Files_Table_Plugin_Options">below</A>. If there are multiple source map entries
|
||||||
<A href="#Source_Files_Table_Plugin_Options"> below</A>. If there are
|
defined for an address, the user will be prompted to select which one to send to the viewer.
|
||||||
multiple source map entries defined for an address, the user will be
|
Performing this action on a particular line of the Source Map Listing field will open the
|
||||||
prompted to select which one to send to the viewer. Performing
|
corresponding file in the viewer even if there are multiple entries defined at the current
|
||||||
this action on a particular line of the Source Map Listing field will
|
address.</P>
|
||||||
open the corresponding file in the viewer even if there are multiple
|
|
||||||
entries defined at the current address.
|
|
||||||
</P>
|
|
||||||
|
|
||||||
</BLOCKQUOTE>
|
</BLOCKQUOTE>
|
||||||
|
|
||||||
|
|
||||||
<H2><A name="Source_Files_Table_Plugin_Options"></A>Plugin Options</H2>
|
<H2><A name="Source_Files_Table_Plugin_Options"></A>Plugin Options</H2>
|
||||||
|
|
||||||
|
<P>These options can be changed from the Code Browser via Edit->-Tool Options->Source
|
||||||
|
Files and Transforms.</P>
|
||||||
|
|
||||||
<BLOCKQUOTE>
|
<BLOCKQUOTE>
|
||||||
<H3><A name="Use_Existing_As_Default"></A>Use Existing As Default</H3>
|
<H3><A name="Use_Existing_As_Default"></A>Use Existing As Default</H3>
|
||||||
|
|
||||||
<P>If enabled, the SourcePathTransformer will just return a SourceFile's path if
|
<P>If enabled, the SourcePathTransformer will just return a SourceFile's path if no transform
|
||||||
no transform applies to the file.</P>
|
applies to the file.</P>
|
||||||
|
|
||||||
<H3><A name="Viewer_for_Source_Files"></A>Viewer for Source Files</H3>
|
<H3><A name="Viewer_for_Source_Files"></A>Viewer for Source Files</H3>
|
||||||
<P> Selects the viewer to use for source files. The supported viewers are Eclipse
|
|
||||||
and Visual Studio Code. Your viewer of choice must be configured via the
|
|
||||||
appropriate option in the Front-End tool.
|
|
||||||
|
|
||||||
|
<P>Selects the viewer to use for source files. The supported viewers are Eclipse and Visual
|
||||||
|
Studio Code. Your viewer of choice must be configured via the appropriate option in the
|
||||||
|
Front-End tool (aka Ghidra Project Window).</P>
|
||||||
</BLOCKQUOTE>
|
</BLOCKQUOTE>
|
||||||
|
|
||||||
|
<H1><A name="Source_File_Information"></A>Source File Information</H1>
|
||||||
|
|
||||||
|
<P>Ghidra can store information about the source files for a program, including their locations
|
||||||
|
in the build environment and the correspondence between lines of source code and addresses in a
|
||||||
|
program. A common source of this information is debug data, such as DWARF or PDB.</P>
|
||||||
|
|
||||||
|
<P>A major use case of this information is to synchronize Ghidra with an IDE, such as
|
||||||
|
Eclipse.</P>
|
||||||
|
|
||||||
|
<H2>Source Files</H2>
|
||||||
|
|
||||||
|
<P>A source file record in Ghidra consists of three pieces of information:</P>
|
||||||
|
|
||||||
|
<BLOCKQUOTE>
|
||||||
|
<OL>
|
||||||
|
<LI>A path, which must be an absolute, normalized path using forward slashes. E.g.,
|
||||||
|
"/usr/src/main/file.c", "/C:/Users/Ghidra/sourceFile.cc".</LI>
|
||||||
|
|
||||||
|
<LI>A <I>SourceFileIdType</I>, which can be NONE, UNKNOWN, TIMESTAMP_64, MD5, SHA1, SHA256,
|
||||||
|
or SHA512.</LI>
|
||||||
|
|
||||||
|
<LI>An identifier, which is the value of the identifier as a byte array.</LI>
|
||||||
|
</OL>
|
||||||
|
</BLOCKQUOTE>
|
||||||
|
|
||||||
|
<H2>Source Map Entries</H2>
|
||||||
|
|
||||||
|
<P>A <I>Source Map Entry</I> associates a source file and a line number to an address or
|
||||||
|
address range in a program. It consists of:</P>
|
||||||
|
|
||||||
|
<BLOCKQUOTE>
|
||||||
|
<OL>
|
||||||
|
<LI>A source file.</LI>
|
||||||
|
|
||||||
|
<LI>A line number.</LI>
|
||||||
|
|
||||||
|
<LI>A base address.</LI>
|
||||||
|
|
||||||
|
<LI>A length. If the length is non-zero, the entry defines an address range, otherwise it
|
||||||
|
defines an address.</LI>
|
||||||
|
</OL>
|
||||||
|
</BLOCKQUOTE><BR>
|
||||||
|
<BR>
|
||||||
|
|
||||||
|
|
||||||
|
<P>Source map entries are constrained as follows:</P>
|
||||||
|
|
||||||
|
<BLOCKQUOTE>
|
||||||
|
<UL>
|
||||||
|
<LI>An address in a program may not have duplicate (same source file, line number, base
|
||||||
|
address, and length) source file entries.</LI>
|
||||||
|
|
||||||
|
<LI>Given two source map entries with non-zero lengths, their associated address ranges
|
||||||
|
must be either identical or distinct (i.e., no partial overlaps). Multiple source maps
|
||||||
|
entries based at the same address are allowed as long as they obey this restriction. Length
|
||||||
|
zero entries may occur anywhere, including within ranges corresponding to entries of
|
||||||
|
non-zero lengths.</LI>
|
||||||
|
</UL>
|
||||||
|
</BLOCKQUOTE><BR>
|
||||||
|
<BR>
|
||||||
|
|
||||||
|
|
||||||
|
<H2>Source File Manager</H2>
|
||||||
|
|
||||||
|
<P>Source files and source map entries are managed by a program's source file manager. A source
|
||||||
|
file must be added to a program before it can used in a source map entry. The DWARF, PDB, and
|
||||||
|
Go analyzers add source files and source map entries to a program by default. There are no GUI
|
||||||
|
actions to add source files or source map entries to a program, but such information can be
|
||||||
|
added to a program via a Ghidra Script. There are example scripts in the "SourceMapping" script
|
||||||
|
category.</P>
|
||||||
|
|
||||||
|
<BLOCKQUOTE>
|
||||||
|
<P><IMG src="help/shared/note.png" alt="Note" border="0">Note that adding source files,
|
||||||
|
removing source files, or changing the source map requires an exclusive checkout if the
|
||||||
|
program is in a shared Ghidra repository. Reading the source file list or source map does not
|
||||||
|
require an exclusive checkout.</P>
|
||||||
|
<BR>
|
||||||
|
</BLOCKQUOTE><BR>
|
||||||
|
<BR>
|
||||||
|
|
||||||
|
|
||||||
|
<H2>Source Path Transformations</H2>
|
||||||
|
|
||||||
|
<P>Source file path information can be sent to an external tool, such as an IDE. However, there
|
||||||
|
is no guarantee that a path recorded for a source file exists on the machine running Ghidra.
|
||||||
|
For instance, you could use Ghidra running under Linux to analyze a Windows program with source
|
||||||
|
file information. An additional complication is that the program may be in a shared Ghidra
|
||||||
|
repository where users have different operating systems or local file systems. We solve this
|
||||||
|
issue by allowing users to modify source file paths. The modifications are stored locally for
|
||||||
|
each user and are not checked in to a shared repository.</P>
|
||||||
|
|
||||||
|
<P>A note on terminology: to avoid overuse of the word "map", we use "map" when discussing the
|
||||||
|
association of a source file and a line number to an address and length in a program (the
|
||||||
|
"source file map"). We use the word "transform" when discussing user-determined modifications
|
||||||
|
of a source file's path.</P>
|
||||||
|
|
||||||
|
<P>There are two type of source path transforms:</P>
|
||||||
|
|
||||||
|
<BLOCKQUOTE>
|
||||||
|
<OL>
|
||||||
|
<LI><I>File Transforms</I>, which entirely replace a source file's path with another file
|
||||||
|
path.</LI>
|
||||||
|
|
||||||
|
<LI><I>Directory Transforms</I>, which replace a parent directory of a source file's path
|
||||||
|
with another directory. For example, the directory transform "/src/ ->
|
||||||
|
"/usr/test/files/" would transform the path "/src/dir1/file.c" to
|
||||||
|
"/usr/test/files/dir1/file.c".</LI>
|
||||||
|
</OL>
|
||||||
|
</BLOCKQUOTE><BR>
|
||||||
|
<BR>
|
||||||
|
|
||||||
|
|
||||||
|
<P>Given a source file, the transformed path is determined as follows. If there is a file
|
||||||
|
transform for that particular file, the file transform is applied. Otherwise, the most specific
|
||||||
|
directory transform (i.e., the one replacing the longest initial segment of the path) is
|
||||||
|
applied. If no transform is applied, the user may opt to use the untransformed path.</P>
|
||||||
|
|
||||||
|
<P>Source file path transformations are managed using a <I>SourcePathTransformer</I>. Path
|
||||||
|
transformations can be managed using the actions on the <A href="#Source_Files_Table">Source
|
||||||
|
Files Table</A>. In a script, you can get the path transformer for a program via the static
|
||||||
|
method <I>UserDataPathTransformer.getPathTransformer(Program)</I>. Note that modifications to
|
||||||
|
the path transformer are not affected by undo or redo actions in Ghidra.</P>
|
||||||
|
|
||||||
<P class="relatedtopic">Related Topics:</P>
|
<P class="relatedtopic">Related Topics:</P>
|
||||||
|
|
||||||
<UL>
|
<UL>
|
||||||
<LI><A href="help/topics/CodeBrowserPlugin/CodeBrowserOptions.htm#Source_Map_Field">Source
|
<LI><A href="help/topics/CodeBrowserPlugin/CodeBrowserOptions.htm#Source_Map_Field">Source
|
||||||
Map Field</A></LI>
|
Map Field</A></LI>
|
||||||
<LI><A href="help/topics/EclipseIntegration/EclipseIntegration.htm"> Eclipse Integration</A>
|
|
||||||
</LI>
|
<LI><A href="help/topics/EclipseIntegration/EclipseIntegration.htm">Eclipse
|
||||||
|
Integration</A></LI>
|
||||||
|
|
||||||
<LI><A href="help/topics/VSCodeIntegration/VSCodeIntegration.htm">Visual Studio Code
|
<LI><A href="help/topics/VSCodeIntegration/VSCodeIntegration.htm">Visual Studio Code
|
||||||
Integration</A></LI>
|
Integration</A></LI>
|
||||||
</UL><BR>
|
</UL><BR>
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue