mirror of
https://github.com/NationalSecurityAgency/ghidra.git
synced 2025-10-03 09:49:23 +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>
|
||||
|
||||
<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>
|
||||
|
||||
<P>This plugin shows the source file information associated with the current program and allows
|
||||
the user to manage source file path transforms.</P>
|
||||
<P>This plugin shows the source file information (described <A href=
|
||||
"#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>
|
||||
|
||||
|
|
@ -187,44 +69,167 @@
|
|||
<BLOCKQUOTE>
|
||||
<H3><A name="View_Source"></A>View Source</H3>
|
||||
|
||||
<P>This Listing action is enabled if there is source map information
|
||||
for an address. It will open the corresponding source file at the
|
||||
appropriate line in a source code viewer (currently Eclipse and VS Code
|
||||
are supported). Options for configuring the viewer are described
|
||||
<A href="#Source_Files_Table_Plugin_Options"> below</A>. If there are
|
||||
multiple source map entries defined for an address, the user will be
|
||||
prompted to select which one to send to the viewer. Performing
|
||||
this action on a particular line of the Source Map Listing field will
|
||||
open the corresponding file in the viewer even if there are multiple
|
||||
entries defined at the current address.
|
||||
</P>
|
||||
|
||||
<P>This Listing action is enabled if there is source map information for an address. It will
|
||||
open the corresponding source file at the appropriate line in a source code viewer (currently
|
||||
Eclipse and VS Code are supported). Options for configuring the viewer are described <A href=
|
||||
"#Source_Files_Table_Plugin_Options">below</A>. If there are multiple source map entries
|
||||
defined for an address, the user will be prompted to select which one to send to the viewer.
|
||||
Performing this action on a particular line of the Source Map Listing field will open the
|
||||
corresponding file in the viewer even if there are multiple entries defined at the current
|
||||
address.</P>
|
||||
</BLOCKQUOTE>
|
||||
|
||||
|
||||
<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>
|
||||
<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
|
||||
no transform applies to the file.</P>
|
||||
<P>If enabled, the SourcePathTransformer will just return a SourceFile's path if no transform
|
||||
applies to the file.</P>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<UL>
|
||||
<LI><A href="help/topics/CodeBrowserPlugin/CodeBrowserOptions.htm#Source_Map_Field">Source
|
||||
Map Field</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/EclipseIntegration/EclipseIntegration.htm">Eclipse
|
||||
Integration</A></LI>
|
||||
|
||||
<LI><A href="help/topics/VSCodeIntegration/VSCodeIntegration.htm">Visual Studio Code
|
||||
Integration</A></LI>
|
||||
</UL><BR>
|
||||
<BR>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue