Skip to content

Commit

Permalink
GP-4410 - Version Tracking - Added support for deleting matches; Adde…
Browse files Browse the repository at this point in the history 
…d table column filters
  • Loading branch information
@dragonmacher
dragonmacher committed Jul 18, 2024
1 parent 76977bd commit 9f73d23
Show file tree
Hide file tree
Showing 36 changed files with 1,337 additions and 701 deletions.
1 change: 1 addition & 0 deletions Ghidra/Features/VersionTracking/build.gradle
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ project.ext.excludeFromParallelIntegrationTests = true

dependencies {
api project(":Base")
runtimeOnly project(":CodeCompare")

testImplementation project(path: ':Project', configuration: 'testArtifacts')
testImplementation project(path: ':SoftwareModeling', configuration: 'testArtifacts')
Expand Down
219 changes: 144 additions & 75 deletions ...nTracking/src/main/help/help/topics/VersionTrackingPlugin/providers/VT_Matches_Table.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -315,9 +315,56 @@ <H2><A name="Matches_Actions"></A>Match Table Actions</H2>

<P align="left"><A name="Clear_Match"></A>The <b>Clear Match</b> <IMG src="images/undo-apply.png" border="0">
action will reset the match to unaccepted and undo any applied markup.</P>



<P align="left"><A name="Remove_Match"></A>The <b>Remove Match</b> <IMG src="images/edit-delete.png" border="0">
action will remove a manually created match from the matches table.</P>
action will remove the selected match(es).</P>

<BLOCKQUOTE>
<P><IMG src="help/shared/warning.png" alt="Note" border="0">

As of Ghidra 11.2, Version Tracking supports deleting matches. Any match that has
not been accepted can be deleted without confirmation. However, if you attempt to
delete an <B>accepted match</B> that is the <B>last match for an association</B>, then
you will be prompted to confirm your decision.
</P>
<P>
Generally, we suggest users should not delete accepted matches. The more matches that
are accepted, the better the Version Tracking results, since user choices affect
future match scores. Keeping accepted matches and the applied markup provides
future analysis with more corroborating details. Contrastingly, deleting accepted
matches while keeping applied markup will remove supporting evidence that the user has
already substantiated.
</P>
<BLOCKQUOTE>
<P><IMG src="help/shared/tip.png">An alternative to deleting matches is to
simply filter them out of the table once they have been applied. You can also tag
any matches you wish to ignore and then use the <A HREF="#VT_Advanced_Filters">
advanced filters</a> to hide any matches with those tags.
</P>
</BLOCKQUOTE>
<P>
It is important to understand what happens in Version Tracking when deleting a match.
You will have to make a decision before deleting whether you want to keep any changes
made to the destination program when you accepted a given match or whether you wish to
remove that markup. When deleting an accepted match:
</P>
<BLOCKQUOTE>
<P>
<U>To keep all applied markup</U>, simply delete the match and, when
prompted, choose <B>Delete Accepted Matches</B>. This choice will delete the match and
its markup items, but <B>any applied markup item content will remain in the destination
program.</B> Alternatively, when prompted, you can choose <B>Finish</B> which will
close the prompt dialog and will not delete the remaining accepted matches or markup.
<P>
<U>To remove all applied markup</U>, then you must first
<A HREF="#Clear_Match">clear</A> the match before executing the remove action. The clear
action will remove applied markup. After clearing the match, then you can remove
the match and no markup will remain in the destination program.
</P>
</BLOCKQUOTE>

</BLOCKQUOTE>

<P align="left"><A name="Make_Selections"></A>The <b>Make Selections</b> <IMG src="Icons.MAKE_SELECTION_ICON" border="0">
action will create selections in the source and destination tools for all matches selected in the table.</P>
Expand Down Expand Up @@ -400,79 +447,101 @@ <H2><A name="Matches_Actions"></A>Match Table Actions</H2>

<H2><A name="Match_Filters"></A>Match Filters</H2>

<BLOCKQUOTE>
<P align="left">The match table has an extensive assortment of filters. There
are several commonly used filter controls at the bottom of the table:
<ol>
<li><b>Text Filter</b> - allows you to filter based on any text in the table
</li>
<li><b>Score Filter</b> - allows you to filter on a range of scores. All scores
are between 0 and 1
</li>
<li><b>Confidence Filter</b> - allows you to filter a range of confidence values.
All confidence values will be greater than -9.999 and smaller than 9.999.
</li>
<li><b>Length Filter</b> - is used to filter out
functions that are smaller than some number
</li>
</ol>

</P>

<P>Finally, the <IMG src="images/view-filter.png" border="0"> will show the ancillary filters
available. The table below lists and describes the available filters. When an ancillary
filter is applied, the icon will change to <IMG src="images/lightbulb.png" border="0"> .
Further, the icon may occasionally flash as a reminder that there is a filter applied.</P>
<BR>
<TABLE border="1" width="90%">
<TR>
<TH nowrap>Filter Name</TH>

<TH>Description</TH>
</TR>

<TR>
<TD valign="top">Match Type</TD>

<TD valign="top">This filter allows the user to show only function or data matches.</TD>
</TR>

<TR>
<TD valign="top" nowrap>Association Status</TD>

<TD valign="top">This filter allows the user to show only matches whose assocation
has one of the included status types. A useful setting
for this filter is to turn off all but the <B>Available</B> status. This will cause the
table to act like a "To Do" list.</TD>
</TR>
<TR>
<TD valign="top">Symbol Type</TD>

<TD valign="top">This filter allows the user to show only matches whose source or
destination labels are of one of the included symbol types.</TD>
</TR>

<TR>
<TD valign="top">Algorithms</TD>

<TD valign="top">This filter allows the user to show only matches that were generated
by one of the included types of correlating algorithms</TD>
</TR>
<TR>
<TD valign="top">Address Range</TD>

<TD valign="top">This filter allows the user to show only matches whose source or
destination address is within the specified range.</TD>
</TR>
<TR>
<TD valign="top">Tags</TD>

<TD valign="top">This filter allows the user to show only matches whose tag is an
included tag.</TD>
</TR>


</TABLE>
<BLOCKQUOTE>

<H3>Table Filters</H3>


<BLOCKQUOTE>
<P align="left">The match table has an extensive assortment of filters. There
are several commonly used filter controls at the bottom of the table:
<ol>
<li><b>Text Filter</b> - allows you to filter based on any text in the table
</li>
<li><b>Score Filter</b> - allows you to filter on a range of scores. All scores
are between 0 and 1
</li>
<li><b>Confidence Filter</b> - allows you to filter a range of confidence values.
All confidence values will be greater than -9.999 and smaller than 9.999.
</li>
<li><b>Length Filter</b> - is used to filter out
functions that are smaller than some number
</li>
</ol>

</P>
</BLOCKQUOTE>


<A NAME="VT_Advanced_Filters"></A>
<H3>Advanced Filters</H3>

<BLOCKQUOTE>

<P>Finally, the <IMG src="icon.version.tracking.unfiltered" border="0"> will show the ancillary filters
available. The table below lists and describes the available filters. When an ancillary
filter is applied, the icon will change to <IMG src="icon.version.tracking.filtered" border="0"> .
Further, the icon may occasionally flash as a reminder that there is a filter applied.</P>
<BR>
<TABLE border="1" width="90%">
<TR>
<TH nowrap>Filter Name</TH>

<TH>Description</TH>
</TR>

<TR>
<TD valign="top">Match Type</TD>

<TD valign="top">This filter allows the user to show only function or data matches.</TD>
</TR>

<TR>
<TD valign="top" nowrap>Association Status</TD>

<TD valign="top">This filter allows the user to show only matches whose assocation
has one of the included status types. A useful setting
for this filter is to turn off all but the <B>Available</B> status. This will cause the
table to act like a "To Do" list.</TD>
</TR>
<TR>
<TD valign="top">Symbol Type</TD>

<TD valign="top">This filter allows the user to show only matches whose source or
destination labels are of one of the included symbol types.</TD>
</TR>

<TR>
<TD valign="top">Algorithms</TD>

<TD valign="top">This filter allows the user to show only matches that were generated
by one of the included types of correlating algorithms</TD>
</TR>
<TR>
<TD valign="top">Address Range</TD>

<TD valign="top">This filter allows the user to show only matches whose source or
destination address is within the specified range.</TD>
</TR>
<TR>
<TD valign="top">Tags</TD>

<TD valign="top">This filter allows the user to show only matches whose tag is an
included tag.</TD>
</TR>


</TABLE>
</BLOCKQUOTE>

<H3>Table Column Filters</H3>

<BLOCKQUOTE>
The matches table also supports
<A HREF="help/topics/Trees/GhidraTreeFilter.html#Column_Filters">
Table Column Filters</A> for creating complex filters for individual table columns.
</BLOCKQUOTE>

</BLOCKQUOTE>

</BLOCKQUOTE> <!-- end of top-level blockquote -->
Expand Down
63 changes: 28 additions & 35 deletions ...es/VersionTracking/src/main/java/ghidra/feature/vt/api/db/AssociationDatabaseManager.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,7 @@
import java.util.*;

import db.*;
import ghidra.feature.vt.api.impl.MarkupItemStorage;
import ghidra.feature.vt.api.impl.VTEvent;
import ghidra.feature.vt.api.impl.*;
import ghidra.feature.vt.api.main.*;
import ghidra.feature.vt.api.util.VTAssociationStatusException;
import ghidra.framework.data.OpenMode;
Expand Down Expand Up @@ -138,33 +137,13 @@ public MarkupItemStorage addMarkupItem(MarkupItemStorage markupItemStorage) {
return createMarkupItemDB(markupItemStorage);
}

void removeMarkupItem(MarkupItemStorageDB appliedMarkupItemDB) {
// non-interface method; internal API use
public void removeStoredMarkupItems(List<MarkupItemImpl> impls) {

VTAssociationDB association = (VTAssociationDB) appliedMarkupItemDB.getAssociation();

validateAcceptedState(appliedMarkupItemDB, association);

try {
markupItemTableAdapter.removeMatchMarkupItemRecord(appliedMarkupItemDB.getKey());
}
catch (IOException e) {
session.dbError(e);
}
}

private void validateAcceptedState(MarkupItemStorageDB appliedItem,
VTAssociationDB association) {
//
// For any 'applied' markup item we assume that its association will be 'ACCEPTED'. The
// exception to this rule is when we have markup items in the database, but that are not
// applied (like when we change the destination address without applying)
//
VTAssociationStatus associationStatus = association.getStatus();
VTMarkupItemStatus status = appliedItem.getStatus();
if (status.isUnappliable()) {
if (associationStatus != ACCEPTED) {
throw new AssertException("Cannot have an applied markup item with an " +
"association that is not ACCEPTED");
for (MarkupItemImpl impl : impls) {
MarkupItemStorage storage = impl.getStorage();
if (storage instanceof MarkupItemStorageDB storageDb) {
removeMarkupRecord(storageDb.getKey());
}
}
}
Expand Down Expand Up @@ -251,17 +230,31 @@ VTAssociationDB getOrCreateAssociationDB(Address sourceAddress, Address destinat
}

void removeAssociation(VTAssociation association) {
VTAssociationDB existingAssociation = (VTAssociationDB) association;
long id = existingAssociation.getKey();

// Update the association status so that we update any blocked associations
VTAssociationDB associationDB = (VTAssociationDB) association;
VTAssociationStatus status = association.getStatus();
if (status == ACCEPTED) {
associationDB.setStatus(AVAILABLE);
associationDB.setInvalid();
unblockRelatedAssociations(associationDB);
for (AssociationHook hook : associationHooks) {
hook.associationCleared(associationDB);
}
}

VTAssociationDB associationDb = (VTAssociationDB) association;
long id = associationDb.getKey();
try {
associationDb.removeMarkupItems();
associationTableAdapter.removeAssociaiton(id);
session.setChanged(VTEvent.ASSOCIATION_REMOVED, existingAssociation, null);
session.setChanged(VTEvent.ASSOCIATION_REMOVED, associationDb, null);
}
catch (IOException e) {
session.dbError(e);
}
associationCache.delete(id);
existingAssociation.setInvalid();
associationDb.setInvalid();

}

Expand Down Expand Up @@ -507,7 +500,7 @@ private void verifyAssociationContainsNoAppliedMarkupItems(VTAssociation associa
throws VTAssociationStatusException {
if (association.hasAppliedMarkupItems()) {
throw new VTAssociationStatusException(
"VTMarkupItemManager contains applied " + "markup items");
"VTMarkupItemManager contains applied markup items");
}
}

Expand Down Expand Up @@ -623,9 +616,9 @@ void removeAssociationHook(AssociationHook hook) {
associationHooks.remove(hook);
}

void removeMarkupRecord(DBRecord record) {
void removeMarkupRecord(long key) {
try {
markupItemTableAdapter.removeMatchMarkupItemRecord(record.getKey());
markupItemTableAdapter.removeMarkupItemRecord(key);
}
catch (IOException e) {
session.dbError(e);
Expand Down
5 changes: 3 additions & 2 deletions .../Features/VersionTracking/src/main/java/ghidra/feature/vt/api/db/MarkupItemStorageDB.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,7 @@ public MarkupItemStorage reset() {
try {
MarkupItemStorage storage = new MarkupItemStorageImpl(getAssociation(), getMarkupType(),
getSourceAddress(), getDestinationAddress(), getDestinationAddressSource());
associationManager.removeMarkupRecord(record);
associationManager.removeMarkupRecord(record.getKey());
return storage;
}
finally {
Expand All @@ -144,7 +144,8 @@ public MarkupItemStorage reset() {
}

@Override
public MarkupItemStorage setDestinationAddress(Address destinationAddress, String addressSource) {
public MarkupItemStorage setDestinationAddress(Address destinationAddress,
String addressSource) {
if (destinationAddress == null) {
destinationAddress = Address.NO_ADDRESS;
}
Expand Down
4 changes: 4 additions & 0 deletions Ghidra/Features/VersionTracking/src/main/java/ghidra/feature/vt/api/db/VTAssociationDB.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -296,4 +296,8 @@ public Collection<VTMarkupItem> getMarkupItems(TaskMonitor monitor) throws Cance
public boolean hasAppliedMarkupItems() {
return markupManager.hasAppliedMarkupItems();
}

void removeMarkupItems() {
markupManager.removeMarkupItems();
}
}
5 changes: 3 additions & 2 deletions ...rsionTracking/src/main/java/ghidra/feature/vt/api/db/VTMatchMarkupItemTableDBAdapter.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ public static VTMatchMarkupItemTableDBAdapter getAdapter(DBHandle dbHandle, Open

public abstract RecordIterator getRecords() throws IOException;

public abstract void removeMatchMarkupItemRecord(long key) throws IOException;
public abstract void removeMarkupItemRecord(long key) throws IOException;

public abstract DBRecord getRecord(long key) throws IOException;

Expand All @@ -70,5 +70,6 @@ public static VTMatchMarkupItemTableDBAdapter getAdapter(DBHandle dbHandle, Open

public abstract int getRecordCount();

public abstract DBRecord createMarkupItemRecord(MarkupItemStorage markupItem) throws IOException;
public abstract DBRecord createMarkupItemRecord(MarkupItemStorage markupItem)
throws IOException;
}
Loading

0 comments on commit 9f73d23

Please sign in to comment.