yetangitu/ghidra
1
0
Fork 0
mirror of https://github.com/NationalSecurityAgency/ghidra.git synced 2025-10-06 03:50:02 +02:00
Code Issues Releases Wiki Activity

GP-5891: Include Debugger javadocs in the build.

Browse source
This commit is contained in:
Dan 2025-08-11 13:12:28 +00:00
parent 483cd9a799
commit ce96f8551d
51 changed files with 223 additions and 222 deletions
Download patch file Download diff file Expand all files Collapse all files

5
Ghidra/Debug/Debugger-api/build.gradle
View file

@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License. * you may not use this file except in compliance with the License.
* You may obtain a copy of the License at * You may obtain a copy of the License at
* *
* http://www.apache.org/licenses/LICENSE-2.0 * http://www.apache.org/licenses/LICENSE-2.0
* *
* Unless required by applicable law or agreed to in writing, software * Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, * distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@ -18,6 +18,7 @@ apply from: "${rootProject.projectDir}/gradle/javaProject.gradle"
apply from: "${rootProject.projectDir}/gradle/jacocoProject.gradle" apply from: "${rootProject.projectDir}/gradle/jacocoProject.gradle"
apply from: "${rootProject.projectDir}/gradle/javaTestProject.gradle" apply from: "${rootProject.projectDir}/gradle/javaTestProject.gradle"
apply from: "${rootProject.projectDir}/gradle/distributableGhidraModule.gradle" apply from: "${rootProject.projectDir}/gradle/distributableGhidraModule.gradle"
apply from: "${rootProject.projectDir}/gradle/javadoc.gradle"
apply plugin: 'eclipse' apply plugin: 'eclipse'
eclipse.project.name = 'Debug Debugger-api' eclipse.project.name = 'Debug Debugger-api'

4
Ghidra/Debug/Debugger-api/src/main/java/ghidra/app/services/DebuggerPlatformService.java
View file

@ -38,8 +38,8 @@ public interface DebuggerPlatformService {
* <p> * <p>
* If the trace's current mapper is applicable to the object, it will be returned. Otherwise, * If the trace's current mapper is applicable to the object, it will be returned. Otherwise,
* the service will query the opinions for a new mapper, as in * the service will query the opinions for a new mapper, as in
* {@link #getNewMapper(TraceObject)} and set it as the current mapper before returning. If a * {@link #getNewMapper(Trace, TraceObject, long)} and set it as the current mapper before
* new mapper is set, the trace is also initialized for that mapper. * returning. If a new mapper is set, the trace is also initialized for that mapper.
* *
* @param trace the trace * @param trace the trace
* @param object the object for which a mapper is desired * @param object the object for which a mapper is desired

8
Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/emulation/DebuggerPcodeEmulatorFactory.java
View file

@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License. * you may not use this file except in compliance with the License.
* You may obtain a copy of the License at * You may obtain a copy of the License at
* *
* http://www.apache.org/licenses/LICENSE-2.0 * http://www.apache.org/licenses/LICENSE-2.0
* *
* Unless required by applicable law or agreed to in writing, software * Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, * distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@ -22,10 +22,6 @@ import ghidra.util.classfinder.ExtensionPoint;
/** /**
* A factory for configuring and creating a Debugger-integrated emulator * A factory for configuring and creating a Debugger-integrated emulator
*
* <p>
* See {@link BytesDebuggerPcodeEmulatorFactory} for the default implementation. See the Taint
* Analyzer for the archetype of alternative implementations.
*/ */
public interface DebuggerPcodeEmulatorFactory extends ExtensionPoint { public interface DebuggerPcodeEmulatorFactory extends ExtensionPoint {
// TODO: Config options, use ModelFactory as a model // TODO: Config options, use ModelFactory as a model

8
Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/emulation/DebuggerPcodeMachine.java
View file

@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License. * you may not use this file except in compliance with the License.
* You may obtain a copy of the License at * You may obtain a copy of the License at
* *
* http://www.apache.org/licenses/LICENSE-2.0 * http://www.apache.org/licenses/LICENSE-2.0
* *
* Unless required by applicable law or agreed to in writing, software * Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, * distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@ -20,10 +20,6 @@ import ghidra.pcode.exec.trace.TracePcodeMachine;
/** /**
* A Debugger-integrated emulator (or p-code machine) * A Debugger-integrated emulator (or p-code machine)
* *
* <p>
* A common implementation is an emulator with concrete plus some auxiliary state. To realize such a
* machine, please see {@link AuxDebuggerPcodeEmulator} and {@link AuxDebuggerEmulatorPartsFactory}.
*
* @param <T> the type of values in the machine's memory and registers * @param <T> the type of values in the machine's memory and registers
*/ */
public interface DebuggerPcodeMachine<T> extends TracePcodeMachine<T> { public interface DebuggerPcodeMachine<T> extends TracePcodeMachine<T> {

7
Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/emulation/PcodeDebuggerAccess.java
View file

@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License. * you may not use this file except in compliance with the License.
* You may obtain a copy of the License at * You may obtain a copy of the License at
* *
* http://www.apache.org/licenses/LICENSE-2.0 * http://www.apache.org/licenses/LICENSE-2.0
* *
* Unless required by applicable law or agreed to in writing, software * Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, * distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@ -26,8 +26,7 @@ import ghidra.trace.model.thread.TraceThread;
* In addition to the trace "coordinates" encapsulated by {@link PcodeTraceAccess}, this * In addition to the trace "coordinates" encapsulated by {@link PcodeTraceAccess}, this
* encapsulates the tool controlling a session and the session's target. This permits p-code * encapsulates the tool controlling a session and the session's target. This permits p-code
* executor/emulator states to access target data and to access session data, e.g., data from mapped * executor/emulator states to access target data and to access session data, e.g., data from mapped
* static images. It supports the same method chain pattern as {@link PcodeTraceAccess}, but * static images. It supports the same method chain pattern as {@link PcodeTraceAccess}.
* starting with {@link DefaultPcodeDebuggerAccess}.
*/ */
public interface PcodeDebuggerAccess extends PcodeTraceAccess { public interface PcodeDebuggerAccess extends PcodeTraceAccess {
@Override @Override

16
Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/target/Target.java
View file

@ -519,8 +519,10 @@ public interface Target {
* be recorded into the trace <em>before</em> this method returns. If the request is * be recorded into the trace <em>before</em> this method returns. If the request is
* unsuccessful, this method throw an exception. * unsuccessful, this method throw an exception.
* *
* @param address the starting address * @param platform the platform whose language defines the registers
* @param data the bytes to write * @param thread the thread whose register to write
* @param frame the frame level, usually 0.
* @param value the register and value to write
*/ */
void writeRegister(TracePlatform platform, TraceThread thread, int frame, RegisterValue value); void writeRegister(TracePlatform platform, TraceThread thread, int frame, RegisterValue value);
@ -548,7 +550,7 @@ public interface Target {
* @param thread if a register, the thread whose registers to examine * @param thread if a register, the thread whose registers to examine
* @param frame the frame level, usually 0. * @param frame the frame level, usually 0.
* @param address the address of the variable * @param address the address of the variable
* @param size the size of the variable. Ignored for memory * @param length the size of the variable. Ignored for memory
* @return true if the variable can be mapped to the target * @return true if the variable can be mapped to the target
*/ */
boolean isVariableExists(TracePlatform platform, TraceThread thread, int frame, Address address, boolean isVariableExists(TracePlatform platform, TraceThread thread, int frame, Address address,
@ -558,8 +560,7 @@ public interface Target {
* @see #writeVariable(TracePlatform, TraceThread, int, Address, byte[]) * @see #writeVariable(TracePlatform, TraceThread, int, Address, byte[])
*/ */
CompletableFuture<Void> writeVariableAsync(TracePlatform platform, TraceThread thread, CompletableFuture<Void> writeVariableAsync(TracePlatform platform, TraceThread thread,
int frame, int frame, Address address, byte[] data);
Address address, byte[] data);
/** /**
* Write a variable (memory or register) of the given thread or the process * Write a variable (memory or register) of the given thread or the process
@ -571,7 +572,7 @@ public interface Target {
* {@link #writeMemory(Address, byte[])}. * {@link #writeMemory(Address, byte[])}.
* *
* @param thread the thread. Ignored (may be null) if address is in memory * @param thread the thread. Ignored (may be null) if address is in memory
* @param frameLevel the frame, usually 0. Ignored if address is in memory * @param frame the frame, usually 0. Ignored if address is in memory
* @param address the starting address * @param address the starting address
* @param data the value to write * @param data the value to write
*/ */
@ -665,7 +666,8 @@ public interface Target {
* This will first attempt to kill the target gracefully. In addition, and whether or not the * This will first attempt to kill the target gracefully. In addition, and whether or not the
* target is successfully terminated, the target will be dissociated from its trace, and the * target is successfully terminated, the target will be dissociated from its trace, and the
* target will be invalidated. To attempt only a graceful termination, check * target will be invalidated. To attempt only a graceful termination, check
* {@link #collectActions(ActionName, ActionContext)} with {@link ActionName#KILL}. * {@link #collectActions(ActionName, ActionContext, ObjectArgumentPolicy)} with
* {@link ActionName#KILL}.
*/ */
void forceTerminate(); void forceTerminate();

2
Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/tracermi/RemoteMethod.java
View file

@ -117,7 +117,7 @@ public interface RemoteMethod {
* Check the type of an argument. * Check the type of an argument.
* *
* <p> * <p>
* This is a hack, because {@link TraceObjectSchema} expects {@link TargetObject}, or a * This is a hack, because {@link TraceObjectSchema} expects {@link TraceObject}, or a
* primitive. We instead need {@link TraceObject}. I'd add the method to the schema, except that * primitive. We instead need {@link TraceObject}. I'd add the method to the schema, except that
* trace stuff is not in its dependencies. * trace stuff is not in its dependencies.
* *

9
Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/tracermi/TraceRmiAcceptor.java
View file

@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License. * you may not use this file except in compliance with the License.
* You may obtain a copy of the License at * You may obtain a copy of the License at
* *
* http://www.apache.org/licenses/LICENSE-2.0 * http://www.apache.org/licenses/LICENSE-2.0
* *
* Unless required by applicable law or agreed to in writing, software * Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, * distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@ -34,6 +34,7 @@ public interface TraceRmiAcceptor {
* *
* @return the connection, if successful * @return the connection, if successful
* @throws IOException if there was an error * @throws IOException if there was an error
* @throws CancelledException if {@link #cancel()} is called, usually from the user canceling
*/ */
TraceRmiConnection accept() throws IOException, CancelledException; TraceRmiConnection accept() throws IOException, CancelledException;
@ -64,8 +65,8 @@ public interface TraceRmiAcceptor {
* *
* <p> * <p>
* If a different thread has called {@link #accept()}, it will fail. In this case, both * If a different thread has called {@link #accept()}, it will fail. In this case, both
* {@linkplain TraceRmiServiceListener#acceptCancelled(TraceRmiAcceptor)} and * {@link TraceRmiServiceListener#acceptCancelled(TraceRmiAcceptor)} and
* {@linkplain TraceRmiServiceListener#acceptFailed(Exception)} may be invoked. * {@link TraceRmiServiceListener#acceptFailed(TraceRmiAcceptor, Exception)} may be invoked.
*/ */
void cancel(); void cancel();
} }

5
Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/tracermi/TraceRmiServiceListener.java
View file

@ -86,8 +86,9 @@ public interface TraceRmiServiceListener {
* *
* <p> * <p>
* The acceptor remains valid until one of three events occurs: * The acceptor remains valid until one of three events occurs:
* {@linkplain} #connected(TraceRmiConnection, ConnectMode, TraceRmiAcceptor)}, * {@link #connected(TraceRmiConnection, ConnectMode, TraceRmiAcceptor)},
* {@linkplain} #acceptCancelled(TraceRmiAcceptor)}, or {@linkplain} #acceptFailed(Exception)}. * {@link #acceptCancelled(TraceRmiAcceptor)}, or
* {@link #acceptFailed(TraceRmiAcceptor, Exception)}.
* *
* @param acceptor the acceptor waiting * @param acceptor the acceptor waiting
*/ */

1
Ghidra/Debug/Debugger-rmi-trace/build.gradle
View file

@ -19,6 +19,7 @@ apply from: "${rootProject.projectDir}/gradle/helpProject.gradle"
apply from: "${rootProject.projectDir}/gradle/jacocoProject.gradle" apply from: "${rootProject.projectDir}/gradle/jacocoProject.gradle"
apply from: "${rootProject.projectDir}/gradle/javaTestProject.gradle" apply from: "${rootProject.projectDir}/gradle/javaTestProject.gradle"
apply from: "${rootProject.projectDir}/gradle/distributableGhidraModule.gradle" apply from: "${rootProject.projectDir}/gradle/distributableGhidraModule.gradle"
apply from: "${rootProject.projectDir}/gradle/javadoc.gradle"
apply from: "${rootProject.projectDir}/gradle/hasProtobuf.gradle" apply from: "${rootProject.projectDir}/gradle/hasProtobuf.gradle"
apply from: "${rootProject.projectDir}/gradle/hasPythonPackage.gradle" apply from: "${rootProject.projectDir}/gradle/hasPythonPackage.gradle"

14
Ghidra/Debug/Debugger-rmi-trace/src/main/java/ghidra/debug/spi/tracermi/TraceRmiLaunchOpinion.java
View file

@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License. * you may not use this file except in compliance with the License.
* You may obtain a copy of the License at * You may obtain a copy of the License at
* *
* http://www.apache.org/licenses/LICENSE-2.0 * http://www.apache.org/licenses/LICENSE-2.0
* *
* Unless required by applicable law or agreed to in writing, software * Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, * distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@ -22,7 +22,6 @@ import ghidra.app.plugin.core.debug.service.tracermi.TraceRmiHandler;
import ghidra.app.services.InternalTraceRmiService; import ghidra.app.services.InternalTraceRmiService;
import ghidra.debug.api.tracermi.TraceRmiLaunchOffer; import ghidra.debug.api.tracermi.TraceRmiLaunchOffer;
import ghidra.framework.options.Options; import ghidra.framework.options.Options;
import ghidra.framework.plugintool.PluginTool;
import ghidra.program.model.listing.Program; import ghidra.program.model.listing.Program;
import ghidra.util.classfinder.ExtensionPoint; import ghidra.util.classfinder.ExtensionPoint;
@ -30,15 +29,14 @@ import ghidra.util.classfinder.ExtensionPoint;
* A factory of launch offers * A factory of launch offers
* *
* <p> * <p>
* Each factory is instantiated only once for the entire application, even when multiple tools are * Each opinion is instantiated only once for the entire application, even when multiple tools are
* open. Thus, {@link #init(PluginTool)} and {@link #dispose(PluginTool)} will be invoked for each * open.
* tool.
*/ */
public interface TraceRmiLaunchOpinion extends ExtensionPoint { public interface TraceRmiLaunchOpinion extends ExtensionPoint {
/** /**
* Register any options * Register any options
* *
* @param tool the tool * @param options the tool options
*/ */
default void registerOptions(Options options) { default void registerOptions(Options options) {
} }
@ -75,7 +73,7 @@ public interface TraceRmiLaunchOpinion extends ExtensionPoint {
* @param plugin the Trace RMI launcher service plugin. <b>NOTE:</b> to get access to the Trace * @param plugin the Trace RMI launcher service plugin. <b>NOTE:</b> to get access to the Trace
* RMI (connection) service, use the {@link InternalTraceRmiService}, so that the * RMI (connection) service, use the {@link InternalTraceRmiService}, so that the
* offers can register the connection's resources. See * offers can register the connection's resources. See
* {@link TraceRmiHandler#registerResources(Collection)}. Resource registration is * {@link TraceRmiHandler#registerTerminals(Collection)}. Terminal registration is
* required for the Disconnect button to completely terminate the back end. * required for the Disconnect button to completely terminate the back end.
* @param program the current program. While this is not <em>always</em> used by the launcher, * @param program the current program. While this is not <em>always</em> used by the launcher,
* it is implied that the user expects the debugger to do something with the current * it is implied that the user expects the debugger to do something with the current

1
Ghidra/Debug/Debugger/build.gradle
View file

@ -18,6 +18,7 @@ apply from: "${rootProject.projectDir}/gradle/helpProject.gradle"
apply from: "${rootProject.projectDir}/gradle/jacocoProject.gradle" apply from: "${rootProject.projectDir}/gradle/jacocoProject.gradle"
apply from: "${rootProject.projectDir}/gradle/javaTestProject.gradle" apply from: "${rootProject.projectDir}/gradle/javaTestProject.gradle"
apply from: "${rootProject.projectDir}/gradle/distributableGhidraModule.gradle" apply from: "${rootProject.projectDir}/gradle/distributableGhidraModule.gradle"
apply from: "${rootProject.projectDir}/gradle/javadoc.gradle"
apply plugin: 'eclipse' apply plugin: 'eclipse'
eclipse.project.name = 'Debug Debugger' eclipse.project.name = 'Debug Debugger'

4
Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/stack/StackUnwinder.java
View file

@ -58,12 +58,12 @@ import ghidra.util.task.TaskMonitor;
* <p> * <p>
* The usage pattern is typically: * The usage pattern is typically:
* *
* <pre> * <pre>{@code
* StackUnwinder unwinder = new StackUnwinder(tool, coordinates.getPlatform()); * StackUnwinder unwinder = new StackUnwinder(tool, coordinates.getPlatform());
* for (AnalysisUnwoundFrame<WatchValue> frame : unwinder.frames(coordinates.frame(0), monitor)) { * for (AnalysisUnwoundFrame<WatchValue> frame : unwinder.frames(coordinates.frame(0), monitor)) {
* // check and/or cache the frame * // check and/or cache the frame
* } * }
* </pre> * }</pre>
* *
* <p> * <p>
* Typically, a frame is sought either by its level or by its function. Once found, several * Typically, a frame is sought either by its level or by its function. Once found, several

4
Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/stack/SymPcodeExecutorState.java
View file

@ -214,8 +214,8 @@ public class SymPcodeExecutorState implements PcodeExecutorState<Sym> {
* <p> * <p>
* There are two cases: * There are two cases:
* <ul> * <ul>
* <li>PC:Register => location is PC.reg.address * <li>{@code PC:Register => location is PC.reg.address}</li>
* <li>PC:Deref => location is [Stack]:PC.offset * <li>{@code PC:Deref => location is [Stack]:PC.offset}</li>
* </ul> * </ul>
* *
* @return the address (stack offset or register) of the return address * @return the address (stack offset or register) of the return address

6
Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/stack/UnwindAnalysis.java
View file

@ -419,16 +419,16 @@ public class UnwindAnalysis {
* function return.</li> * function return.</li>
* <li>Examine the symbol in the program counter register. This gives the location (register * <li>Examine the symbol in the program counter register. This gives the location (register
* or stack offset) of the return address. This strategy should work whether or not a link * or stack offset) of the return address. This strategy should work whether or not a link
* register is involved. See {@link SymPcodeExecutorState#computeAddressOfReturn()}. * register is involved. See {@link SymPcodeExecutorState#computeAddressOfReturn()}.</li>
* <li>Examine the symbol in the stack pointer register, again. It should be a stack offset. * <li>Examine the symbol in the stack pointer register, again. It should be a stack offset.
* That offset is the "stack adjustment." See {@link UnwindInfo#adjust()}, * That offset is the "stack adjustment." See {@link UnwindInfo#adjust()},
* {@link UnwindInfo#computeNextSp(Address)}, and * {@link UnwindInfo#computeNextSp(Address)}, and
* {@link SymPcodeExecutorState#computeStackDepth()}. * {@link SymPcodeExecutorState#computeStackDepth()}.</li>
* <li>Search the registers for stack dereference symbols, creating an offset-register map. * <li>Search the registers for stack dereference symbols, creating an offset-register map.
* This intersected with the same from entry to program counter is the saved registers map. * This intersected with the same from entry to program counter is the saved registers map.
* See {@link UnwindInfo#saved()}, * See {@link UnwindInfo#saved()},
* {@link UnwindInfo#mapSavedRegisters(Address, SavedRegisterMap)}, and * {@link UnwindInfo#mapSavedRegisters(Address, SavedRegisterMap)}, and
* {@link SymPcodeExecutorState#computeMapUsingRegisters()}. * {@link SymPcodeExecutorState#computeMapUsingRegisters()}.</li>
* </ol> * </ol>
* *
* <p> * <p>

2
Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/stack/UnwoundFrame.java
View file

@ -115,7 +115,7 @@ public interface UnwoundFrame<T> {
* assuming the callee has not saved that register to the stack.</li> * assuming the callee has not saved that register to the stack.</li>
* <li>The return address cannot be recovered. This happens when the function appears to be non * <li>The return address cannot be recovered. This happens when the function appears to be non
* returning, or the analysis otherwise fails to recover the return address. In this case, this * returning, or the analysis otherwise fails to recover the return address. In this case, this
* method will throw an exception. * method will throw an exception.</li>
* </ol> * </ol>
* *
* @return the return address * @return the return address

3
Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/utils/MiscellaneousUtils.java
View file

@ -93,7 +93,8 @@ public enum MiscellaneousUtils {
} }
/** /**
* Parses a value from 1 to 1<<64. Any value outside the range is "clipped" into the range. * Parses a value from 1 to {@code 1<<64}. Any value outside the range is "clipped" into the
* range.
* *
* <p> * <p>
* Note that a returned value of 0 indicates 2 to the power 64, which is just 1 too high to fit * Note that a returned value of 0 indicates 2 to the power 64, which is just 1 too high to fit

11
Ghidra/Debug/Debugger/src/main/java/ghidra/pcode/exec/DebuggerPcodeUtils.java
View file

@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License. * you may not use this file except in compliance with the License.
* You may obtain a copy of the License at * You may obtain a copy of the License at
* *
* http://www.apache.org/licenses/LICENSE-2.0 * http://www.apache.org/licenses/LICENSE-2.0
* *
* Unless required by applicable law or agreed to in writing, software * Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, * distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@ -64,8 +64,7 @@ public enum DebuggerPcodeUtils {
* A p-code parser that can resolve labels from a trace or its mapped programs. * A p-code parser that can resolve labels from a trace or its mapped programs.
*/ */
public static class LabelBoundPcodeParser extends ErrorCollectingPcodeParser { public static class LabelBoundPcodeParser extends ErrorCollectingPcodeParser {
record ProgSym(String sourceName, String nm, Address address) { record ProgSym(String sourceName, String nm, Address address) {}
}
private final DebuggerStaticMappingService mappings; private final DebuggerStaticMappingService mappings;
private final DebuggerCoordinates coordinates; private final DebuggerCoordinates coordinates;
@ -447,8 +446,8 @@ public enum DebuggerPcodeUtils {
* A p-code arithmetic on watch values * A p-code arithmetic on watch values
* *
* <p> * <p>
* This is just a composition of four arithmetics. Using Pair<A,Pair<B,Pair<C,D>> would be * This is just a composition of four arithmetics. Using {@code Pair<A,Pair<B,Pair<C,D>>} would
* unwieldy. * be unwieldy.
*/ */
public enum WatchValuePcodeArithmetic implements PcodeArithmetic<WatchValue> { public enum WatchValuePcodeArithmetic implements PcodeArithmetic<WatchValue> {
BIG_ENDIAN(BytesPcodeArithmetic.BIG_ENDIAN, LocationPcodeArithmetic.BIG_ENDIAN), BIG_ENDIAN(BytesPcodeArithmetic.BIG_ENDIAN, LocationPcodeArithmetic.BIG_ENDIAN),

1
Ghidra/Debug/Framework-TraceModeling/build.gradle
View file

@ -17,6 +17,7 @@ apply from: "${rootProject.projectDir}/gradle/javaProject.gradle"
apply from: "${rootProject.projectDir}/gradle/jacocoProject.gradle" apply from: "${rootProject.projectDir}/gradle/jacocoProject.gradle"
apply from: "${rootProject.projectDir}/gradle/javaTestProject.gradle" apply from: "${rootProject.projectDir}/gradle/javaTestProject.gradle"
apply from: "${rootProject.projectDir}/gradle/distributableGhidraModule.gradle" apply from: "${rootProject.projectDir}/gradle/distributableGhidraModule.gradle"
apply from: "${rootProject.projectDir}/gradle/javadoc.gradle"
apply plugin: 'eclipse' apply plugin: 'eclipse'
eclipse.project.name = 'Debug Framework-TraceModeling' eclipse.project.name = 'Debug Framework-TraceModeling'

5
Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/pcode/exec/trace/AbstractCheckedTraceCachedWriteBytesPcodeExecutorStatePiece.java
View file

@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License. * you may not use this file except in compliance with the License.
* You may obtain a copy of the License at * You may obtain a copy of the License at
* *
* http://www.apache.org/licenses/LICENSE-2.0 * http://www.apache.org/licenses/LICENSE-2.0
* *
* Unless required by applicable law or agreed to in writing, software * Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, * distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@ -111,7 +111,6 @@ public abstract class AbstractCheckedTraceCachedWriteBytesPcodeExecutorStatePiec
* @param size the size of the requested read * @param size the size of the requested read
* @param uninitialized the portion of the read that is uninitialized * @param uninitialized the portion of the read that is uninitialized
* @return the adjusted size of the read * @return the adjusted size of the read
* @throws Exception to interrupt the emulator
*/ */
protected abstract int checkUninitialized(PcodeTraceDataAccess backing, Address start, protected abstract int checkUninitialized(PcodeTraceDataAccess backing, Address start,
int size, AddressSet uninitialized); int size, AddressSet uninitialized);

13
Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/pcode/exec/trace/data/PcodeTraceAccess.java
View file

@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License. * you may not use this file except in compliance with the License.
* You may obtain a copy of the License at * You may obtain a copy of the License at
* *
* http://www.apache.org/licenses/LICENSE-2.0 * http://www.apache.org/licenses/LICENSE-2.0
* *
* Unless required by applicable law or agreed to in writing, software * Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, * distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@ -54,23 +54,28 @@ import ghidra.trace.model.thread.TraceThread;
* new DefaultPcodeTraceAccess(trace.getPlatformManager().getHostPlatform(), 0, 0); * new DefaultPcodeTraceAccess(trace.getPlatformManager().getHostPlatform(), 0, 0);
* </pre> * </pre>
* *
* </li>
* <li>Typically invoked by a factory method for an emulator's shared executor state * <li>Typically invoked by a factory method for an emulator's shared executor state
* *
* <pre> * <pre>
* PcodeTraceMemoryAccess sharedData = access.getDataForSharedState(); * PcodeTraceMemoryAccess sharedData = access.getDataForSharedState();
* </pre> * </pre>
* *
* </li>
* <li>Typically invoked by a factory method for an emulator thread's local executor state * <li>Typically invoked by a factory method for an emulator thread's local executor state
* *
* <pre> * <pre>
* PcodeTraceRegisterAccess localData = access.getDataForLocalState(thread, 0); * PcodeTraceRegisterAccess localData = access.getDataForLocalState(thread, 0);
* </pre> * </pre>
* *
* </li>
* <li>Typically invoked by an auxiliary emulator state piece * <li>Typically invoked by an auxiliary emulator state piece
* *
* <pre> * <pre>{@code
* PcodeTracePropertyAccess<String> property = data.getPropertyAccess("MyProperty", String.class); * PcodeTracePropertyAccess<String> property = data.getPropertyAccess("MyProperty", String.class);
* </pre> * }</pre>
*
* </li>
* </ul> * </ul>
*/ */
public interface PcodeTraceAccess { public interface PcodeTraceAccess {

19
Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/listing/AbstractBaseDBTraceCodeUnitsView.java
View file

@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License. * you may not use this file except in compliance with the License.
* You may obtain a copy of the License at * You may obtain a copy of the License at
* *
* http://www.apache.org/licenses/LICENSE-2.0 * http://www.apache.org/licenses/LICENSE-2.0
* *
* Unless required by applicable law or agreed to in writing, software * Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, * distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@ -19,7 +19,6 @@ import generic.NestedIterator;
import ghidra.program.model.address.*; import ghidra.program.model.address.*;
import ghidra.trace.model.*; import ghidra.trace.model.*;
import ghidra.trace.model.listing.TraceBaseCodeUnitsView; import ghidra.trace.model.listing.TraceBaseCodeUnitsView;
import ghidra.trace.model.thread.TraceThread;
/** /**
* An abstract implementation of a {@link TraceBaseCodeUnitsView} for a specific address space * An abstract implementation of a {@link TraceBaseCodeUnitsView} for a specific address space
@ -64,20 +63,6 @@ public abstract class AbstractBaseDBTraceCodeUnitsView<T extends DBTraceCodeUnit
return space.manager.getTrace(); return space.manager.getTrace();
} }
/**
* @see TraceBaseCodeUnitsView#getThread()
*/
public TraceThread getThread() {
return space.getThread();
}
/**
* @see TraceBaseCodeUnitsView#getFrameLevel()
*/
public int getFrameLevel() {
return space.getFrameLevel();
}
/** /**
* @see TraceBaseCodeUnitsView#size() * @see TraceBaseCodeUnitsView#size()
*/ */

14
Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/listing/DBTraceCodeManager.java
View file

@ -115,30 +115,36 @@ import ghidra.util.task.TaskMonitor;
* Here is the type hierarchy presented with notes regarding structural interface implementations: * Here is the type hierarchy presented with notes regarding structural interface implementations:
* <ul> * <ul>
* <li>{@link AbstractBaseDBTraceCodeUnitsView} structurally implements * <li>{@link AbstractBaseDBTraceCodeUnitsView} structurally implements
* {@link TraceBaseCodeUnitsView}</li> * {@link TraceBaseCodeUnitsView}
* <ul> * <ul>
* <li>{@link AbstractComposedDBTraceCodeUnitsView}</li> * <li>{@link AbstractComposedDBTraceCodeUnitsView}
* <ul> * <ul>
* <li>{@link DBTraceCodeUnitsView} nominally implements {@link TraceCodeUnitsView}</li> * <li>{@link DBTraceCodeUnitsView} nominally implements {@link TraceCodeUnitsView}</li>
* <li>{@link DBTraceDataView} nominally implements {@link TraceDataView}</li> * <li>{@link DBTraceDataView} nominally implements {@link TraceDataView}</li>
* <li>{@link DBTraceDefinedUnitsView} nominally implements {@link TraceDefinedUnitsView}</li> * <li>{@link DBTraceDefinedUnitsView} nominally implements {@link TraceDefinedUnitsView}</li>
* </ul> * </ul>
* <li>{@link AbstractSingleDBTraceCodeUnitsView}</li> * </li>
* <li>{@link AbstractSingleDBTraceCodeUnitsView}
* <ul> * <ul>
* <li>{@link AbstractBaseDBTraceDefinedUnitsView} structurally implements * <li>{@link AbstractBaseDBTraceDefinedUnitsView} structurally implements
* {@link TraceBaseDefinedUnitsView}</li> * {@link TraceBaseDefinedUnitsView}
* <ul> * <ul>
* <li>{@link DBTraceDefinedDataView} nominally implements {@link TraceDefinedDataView}</li> * <li>{@link DBTraceDefinedDataView} nominally implements {@link TraceDefinedDataView}</li>
* <li>{@link DBTraceInstructionsView} nominally implements {@link TraceInstructionsView}</li> * <li>{@link DBTraceInstructionsView} nominally implements {@link TraceInstructionsView}</li>
* </ul> * </ul>
* </li>
* <li>{@link DBTraceUndefinedDataView} nominally implements {@link TraceUndefinedDataView}</li> * <li>{@link DBTraceUndefinedDataView} nominally implements {@link TraceUndefinedDataView}</li>
* </ul> * </ul>
* </li>
* </ul>
* </li>
* </ul> * </ul>
* *
* <p> * <p>
* The view composition is not hierarchical, as each may represent a different combination, and one * The view composition is not hierarchical, as each may represent a different combination, and one
* type may appear in several compositions. The single-type views are named first, then the composed * type may appear in several compositions. The single-type views are named first, then the composed
* views: * views:
*
* <ul> * <ul>
* <li>Instructions - single-type view</li> * <li>Instructions - single-type view</li>
* <li>Defined Data - single-type view</li> * <li>Defined Data - single-type view</li>

2
Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/listing/DBTraceData.java
View file

@ -119,7 +119,7 @@ public class DBTraceData extends AbstractDBTraceCodeUnit<DBTraceData>
* Set the fields of this record * Set the fields of this record
* *
* @param platform the platform * @param platform the platform
* @param dataType the data type * @param dataTypeID the data type id
*/ */
protected void set(InternalTracePlatform platform, long dataTypeID) { protected void set(InternalTracePlatform platform, long dataTypeID) {
this.platformKey = platform.getIntKey(); this.platformKey = platform.getIntKey();

6
Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/listing/DBTraceDefinedDataAdapter.java
View file

@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License. * you may not use this file except in compliance with the License.
* You may obtain a copy of the License at * You may obtain a copy of the License at
* *
* http://www.apache.org/licenses/LICENSE-2.0 * http://www.apache.org/licenses/LICENSE-2.0
* *
* Unless required by applicable law or agreed to in writing, software * Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, * distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@ -240,7 +240,7 @@ public interface DBTraceDefinedDataAdapter extends DBTraceDataAdapter {
* {@inheritDoc} * {@inheritDoc}
* *
* This implementation differs in that the path is relative to this unit, even if it is not the * This implementation differs in that the path is relative to this unit, even if it is not the
* root. In {@link DataDB}, it appears the behavior is undefined if you call this on a non-root * root. In {@code DataDB}, it appears the behavior is undefined if you call this on a non-root
* component. * component.
*/ */
@Override @Override

6
Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/listing/DBTraceInstructionsView.java
View file

@ -149,8 +149,8 @@ public class DBTraceInstructionsView extends AbstractBaseDBTraceDefinedUnitsView
* Check the preceding unit and see if it can be extended to "create" the desired one * Check the preceding unit and see if it can be extended to "create" the desired one
* *
* <p> * <p>
* For overwrite, the caller should first use * For overwrite, the caller should first use *
* {@link #doAdjustExisting(Address, InstructionPrototype, Instruction)}. * {@link #doAdjustExisting(Address, Instruction)}.
* *
* @param address the starting address of the instruction * @param address the starting address of the instruction
* @param protoInstr the prototype instruction * @param protoInstr the prototype instruction
@ -228,7 +228,7 @@ public class DBTraceInstructionsView extends AbstractBaseDBTraceDefinedUnitsView
* If it encounters a delay-slotted instruction, it will recurse on the group, iterating in * If it encounters a delay-slotted instruction, it will recurse on the group, iterating in
* reverse order. * reverse order.
* *
* @param instructions the instructions to add * @param it the iterator of instructions to add
* @param areDelaySlots true if the instructions are already reversed from being * @param areDelaySlots true if the instructions are already reversed from being
* delay-slotted * delay-slotted
* @return the last instruction added * @return the last instruction added

6
Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/model/DefaultTraceSpan.java
View file

@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License. * you may not use this file except in compliance with the License.
* You may obtain a copy of the License at * You may obtain a copy of the License at
* *
* http://www.apache.org/licenses/LICENSE-2.0 * http://www.apache.org/licenses/LICENSE-2.0
* *
* Unless required by applicable law or agreed to in writing, software * Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, * distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@ -18,7 +18,7 @@ package ghidra.trace.model;
import java.util.Objects; import java.util.Objects;
/** /**
* NOTE: This is used to mark <trace,snap>; regardless of whether that snapshot is actually in the * NOTE: This is used to mark (trace,snap) regardless of whether that snapshot is actually in the
* database.... Cannot just use TraceSnapshot here. * database.... Cannot just use TraceSnapshot here.
*/ */
public class DefaultTraceSpan implements TraceSpan { public class DefaultTraceSpan implements TraceSpan {

3
Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/model/listing/TraceBaseCodeUnitsView.java
View file

@ -239,8 +239,7 @@ public interface TraceBaseCodeUnitsView<T extends TraceCodeUnit> {
* This checks if any (snap, address) point within the given box is contained within some code * This checks if any (snap, address) point within the given box is contained within some code
* unit in this view. * unit in this view.
* *
* @param span the span of snaps * @param range the address-snap range
* @param range the address range
* @return true if intersecting, false otherwise * @return true if intersecting, false otherwise
*/ */
boolean intersectsRange(TraceAddressSnapRange range); boolean intersectsRange(TraceAddressSnapRange range);

1
Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/model/symbol/TraceSymbolWithLocationView.java
View file

@ -216,7 +216,6 @@ public interface TraceSymbolWithLocationView<T extends TraceSymbol> extends Trac
* Check if this view contains any symbols at the given point. * Check if this view contains any symbols at the given point.
* *
* @param snap the snapshot key * @param snap the snapshot key
* @param thread the thread, if in register space
* @param address the address of the symbols * @param address the address of the symbols
* @param includeDynamicSymbols true to include dynamically-generated symbols * @param includeDynamicSymbols true to include dynamically-generated symbols
* @return true if any symbols in this view satisfy the query * @return true if any symbols in this view satisfy the query

34
Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/model/target/TraceObject.java
View file

@ -72,9 +72,9 @@ import ghidra.trace.model.thread.TraceThread;
* <ol> * <ol>
* <li><b>The object itself:</b> Test if the context target object supports the desired interface. * <li><b>The object itself:</b> Test if the context target object supports the desired interface.
* If it does, take it.</li> * If it does, take it.</li>
* <li><b>Aggregate objects:</b> If the object is marked with {@link TraceAggregate}, collect * <li><b>Aggregate objects:</b> If the object is marked with {@link TraceAggregate}, collect all
* all attributes supporting the desired interface. If there are any, take them. This step is * attributes supporting the desired interface. If there are any, take them. This step is applied
* applied recursively if any child attribute is also marked with {@link TraceAggregate}.</li> * recursively if any child attribute is also marked with {@link TraceAggregate}.</li>
* <li><b>Ancestry:</b> Apply these same steps to the object's (canonical) parent, recursively.</li> * <li><b>Ancestry:</b> Apply these same steps to the object's (canonical) parent, recursively.</li>
* </ol> * </ol>
* *
@ -92,44 +92,52 @@ import ghidra.trace.model.thread.TraceThread;
* may be presented by a user-space debugger for a desktop operating system: * may be presented by a user-space debugger for a desktop operating system:
* *
* <ul> * <ul>
* <li>"Session" : {@link TraceObject}</li> * <li>"Session" : {@link TraceObject}
* <ul> * <ul>
* <li>"Process 789" : {@link TraceProcess}, {@link TraceAggregate}</li> * <li>"Process 789" : {@link TraceProcess}, {@link TraceAggregate}
* <ul> * <ul>
* <li>"Threads" : {@link TraceObject}</li> * <li>"Threads" : {@link TraceObject}
* <ul> * <ul>
* <li>"Thread 1" : {@link TraceThread}, {@link TraceExecutionStateful}, * <li>"Thread 1" : {@link TraceThread}, {@link TraceExecutionStateful}, {@link TraceAggregate}
* {@link TraceAggregate}</li>
* <ul> * <ul>
* <li>"Registers" : {@link TraceRegisterContainer}</li> * <li>"Registers" : {@link TraceRegisterContainer}
* <ul> * <ul>
* <li>"r1" : {@link TraceRegister}</li> * <li>"r1" : {@link TraceRegister}</li>
* <li>...</li> * <li>...</li>
* </ul> * </ul>
* </li>
* </ul> * </ul>
* </li>
* <li>...more threads</li> * <li>...more threads</li>
* </ul> * </ul>
* <li>"Memory" : {@link TraceMemory}</li> * </li>
* <li>"Memory" : {@link TraceMemory}
* <ul> * <ul>
* <li>"[0x00400000:0x00401234]" : {@link TraceMemoryRegion}</li> * <li>"[0x00400000:0x00401234]" : {@link TraceMemoryRegion}</li>
* <li>...more regions</li> * <li>...more regions</li>
* </ul> * </ul>
* <li>"Modules" : {@link TraceObject}</li> * </li>
* <li>"Modules" : {@link TraceObject}
* <ul> * <ul>
* <li>"/usr/bin/echo" : {@link TraceModule}</li> * <li>"/usr/bin/echo" : {@link TraceModule}
* <ul> * <ul>
* <li>".text" : {@link TraceSection}</li> * <li>".text" : {@link TraceSection}</li>
* <li>...more sections</li> * <li>...more sections</li>
* </ul> * </ul>
* </li>
* <li>...more modules</li> * <li>...more modules</li>
* </ul> * </ul>
* </li>
* </ul> * </ul>
* <li>"Environment": {@link TraceEnvironment}</li> * </li>
* <li>"Environment": {@link TraceEnvironment}
* <ul> * <ul>
* <li>"Process 321" : {@link TraceObject}</li> * <li>"Process 321" : {@link TraceObject}</li>
* <li>...more processes</li> * <li>...more processes</li>
* </ul> * </ul>
* </li>
* </ul> * </ul>
* </li>
* </ul> * </ul>
* *
* <p> * <p>

20
Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/model/target/schema/TraceObjectSchema.java
View file

@ -390,13 +390,13 @@ public interface TraceObjectSchema {
* path. Thus, for a path of length n, the resulting list has n+1 entries. This is useful for * path. Thus, for a path of length n, the resulting list has n+1 entries. This is useful for
* searches along the ancestry of a given path: * searches along the ancestry of a given path:
* *
* <pre> * <pre>{@code
* List<TargetObjectSchema> schemas = getSuccessorSchemas(path); * List<TargetObjectSchema> schemas = getSuccessorSchemas(path);
* for (; path != null; path = PathUtils.parent(path)) { * for (; path != null; path = PathUtils.parent(path)) {
* TargetObjectSchema schema = schemas.get(path.size()); * TargetObjectSchema schema = schemas.get(path.size());
* // ... * // ...
* } * }
* </pre> * }</pre>
* *
* <p> * <p>
* All entries are non-null, though they may be {@link PrimitiveTraceObjectSchema#VOID}. * All entries are non-null, though they may be {@link PrimitiveTraceObjectSchema#VOID}.
@ -1009,17 +1009,17 @@ public interface TraceObjectSchema {
* *
* <p> * <p>
* This places some conventional restrictions / expectations on models where registers are given * This places some conventional restrictions / expectations on models where registers are given
* on a frame-by-frame basis. The schema should present the {@link TraceRegisterContainer} * on a frame-by-frame basis. The schema should present the {@link TraceRegisterContainer} as
* as the same object or a successor to {@link TraceStackFrame}, which must in turn be a * the same object or a successor to {@link TraceStackFrame}, which must in turn be a successor
* successor to {@link TraceStack}. The frame level (an index) must be in the path from stack to * to {@link TraceStack}. The frame level (an index) must be in the path from stack to frame.
* frame. There can be no wildcards between the frame and the register container. For example, * There can be no wildcards between the frame and the register container. For example, the
* the container for {@code Threads[1]} may be {@code Threads[1].Stack[n].Registers}, where * container for {@code Threads[1]} may be {@code Threads[1].Stack[n].Registers}, where
* {@code n} is the frame level. {@code Threads[1].Stack} would have the {@link TraceStack} * {@code n} is the frame level. {@code Threads[1].Stack} would have the {@link TraceStack}
* interface, {@code Threads[1].Stack[0]} would have the {@link TraceStackFrame} interface, and * interface, {@code Threads[1].Stack[0]} would have the {@link TraceStackFrame} interface, and
* {@code Threads[1].Stack[0].Registers} would have the {@link TraceRegisterContainer} * {@code Threads[1].Stack[0].Registers} would have the {@link TraceRegisterContainer}
* interface. Note it is not sufficient for {@link TraceRegisterContainer} to be a * interface. Note it is not sufficient for {@link TraceRegisterContainer} to be a successor of
* successor of {@link TraceStack} with a single index between. There <em>must</em> be an * {@link TraceStack} with a single index between. There <em>must</em> be an intervening
* intervening {@link TraceStackFrame}, and the frame level (index) must precede it. * {@link TraceStackFrame}, and the frame level (index) must precede it.
* *
* @param frameLevel the frame level. May be ignored if not applicable * @param frameLevel the frame level. May be ignored if not applicable
* @param path the path of the seed object relative to the root * @param path the path of the seed object relative to the root

9
Ghidra/Debug/Framework-TraceModeling/src/test/java/ghidra/trace/database/listing/DBTraceCodeManagerTest.java
View file

@ -1418,12 +1418,7 @@ public class DBTraceCodeManagerTest extends AbstractGhidraHeadlessIntegrationTes
.create(Lifespan.nowOn(0), b.language.getRegister("r4"), LongDataType.dataType); .create(Lifespan.nowOn(0), b.language.getRegister("r4"), LongDataType.dataType);
} }
assertEquals(thread, regCode.codeUnits().getThread()); assertEquals(thread, regCode.getThread());
assertEquals(thread, regCode.data().getThread());
assertEquals(thread, regCode.definedUnits().getThread());
assertEquals(thread, regCode.instructions().getThread());
assertEquals(thread, regCode.definedData().getThread());
assertEquals(thread, regCode.undefinedData().getThread());
assertEquals(List.of(dR4), list(regCode.definedUnits().get(0, true))); assertEquals(List.of(dR4), list(regCode.definedUnits().get(0, true)));
@ -1441,7 +1436,7 @@ public class DBTraceCodeManagerTest extends AbstractGhidraHeadlessIntegrationTes
} }
assertEquals(1, frameCode.getFrameLevel()); assertEquals(1, frameCode.getFrameLevel());
assertEquals(thread, frameCode.codeUnits().getThread()); assertEquals(thread, frameCode.getThread());
assertEquals(List.of(dR5), list(frameCode.definedUnits().get(0, true))); assertEquals(List.of(dR5), list(frameCode.definedUnits().get(0, true)));
} }

1
Ghidra/Debug/ProposedUtils/build.gradle
View file

@ -17,6 +17,7 @@ apply from: "${rootProject.projectDir}/gradle/javaProject.gradle"
apply from: "${rootProject.projectDir}/gradle/jacocoProject.gradle" apply from: "${rootProject.projectDir}/gradle/jacocoProject.gradle"
apply from: "${rootProject.projectDir}/gradle/javaTestProject.gradle" apply from: "${rootProject.projectDir}/gradle/javaTestProject.gradle"
apply from: "${rootProject.projectDir}/gradle/distributableGhidraModule.gradle" apply from: "${rootProject.projectDir}/gradle/distributableGhidraModule.gradle"
apply from: "${rootProject.projectDir}/gradle/javadoc.gradle"
apply plugin: 'eclipse' apply plugin: 'eclipse'
eclipse.project.name = 'Debug ProposedUtils' eclipse.project.name = 'Debug ProposedUtils'

13
Ghidra/Debug/ProposedUtils/src/main/java/ghidra/graph/algo/TopologicalSorter.java
View file

@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License. * you may not use this file except in compliance with the License.
* You may obtain a copy of the License at * You may obtain a copy of the License at
* *
* http://www.apache.org/licenses/LICENSE-2.0 * http://www.apache.org/licenses/LICENSE-2.0
* *
* Unless required by applicable law or agreed to in writing, software * Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, * distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@ -40,7 +40,10 @@ import ghidra.graph.*;
* <p> * <p>
* A-->B-->D, A-->C-->D yields either [A, B, C, D] or [A, C, B, D] * A-->B-->D, A-->C-->D yields either [A, B, C, D] or [A, C, B, D]
* *
* @see {@link https://en.wikipedia.org/wiki/Topological_sorting} * @see <a href="https://en.wikipedia.org/wiki/Topological_sorting">Wikipedia: Topological
* Sorting</a>
* @param <V> the type of vector
* @param <E> the type of edge
*/ */
public class TopologicalSorter<V, E extends GEdge<V>> { public class TopologicalSorter<V, E extends GEdge<V>> {
private final GDirectedGraph<V, E> graph; private final GDirectedGraph<V, E> graph;
@ -53,8 +56,8 @@ public class TopologicalSorter<V, E extends GEdge<V>> {
* *
* @param graph the graph * @param graph the graph
* @param requireTotal true to require a unique solution * @param requireTotal true to require a unique solution
* @note if a unique solution is not requested, this algorithm will choose a solution * @implNote if a unique solution is not requested, this algorithm will choose a solution
* arbitrarily. It does not yield all possible solutions. * arbitrarily. It does not yield all possible solutions.
*/ */
public TopologicalSorter(GDirectedGraph<V, E> graph, boolean requireTotal) { public TopologicalSorter(GDirectedGraph<V, E> graph, boolean requireTotal) {
this.graph = graph; this.graph = graph;

6
Ghidra/Debug/ProposedUtils/src/main/java/ghidra/pcode/eval/AbstractVarnodeEvaluator.java
View file

@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License. * you may not use this file except in compliance with the License.
* You may obtain a copy of the License at * You may obtain a copy of the License at
* *
* http://www.apache.org/licenses/LICENSE-2.0 * http://www.apache.org/licenses/LICENSE-2.0
* *
* Unless required by applicable law or agreed to in writing, software * Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, * distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@ -271,7 +271,7 @@ public abstract class AbstractVarnodeEvaluator<T> implements VarnodeEvaluator<T>
* This is only invoked when trying to evaluate a leaf, which should never occur for a unique * This is only invoked when trying to evaluate a leaf, which should never occur for a unique
* variable. Thus, by default, this throws a {@link PcodeExecutionException}. * variable. Thus, by default, this throws a {@link PcodeExecutionException}.
* *
* @param long the offset of the variable * @param offset the offset of the variable
* @param size the size of the variable in bytes * @param size the size of the variable in bytes
* @return the value * @return the value
*/ */

6
Ghidra/Debug/ProposedUtils/src/main/java/ghidra/pcode/eval/VarnodeEvaluator.java
View file

@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License. * you may not use this file except in compliance with the License.
* You may obtain a copy of the License at * You may obtain a copy of the License at
* *
* http://www.apache.org/licenses/LICENSE-2.0 * http://www.apache.org/licenses/LICENSE-2.0
* *
* Unless required by applicable law or agreed to in writing, software * Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, * distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@ -46,7 +46,7 @@ public interface VarnodeEvaluator<T> {
* Evaluate variable storage * Evaluate variable storage
* *
* <p> * <p>
* Each varnode is evaluated as in {@link #evaluateStorage(VariableStorage)} and then * Each varnode is evaluated as in {@link #evaluateStorage(Program, VariableStorage)} and then
* concatenated. The lower-indexed varnodes in storage are the more significant pieces, similar * concatenated. The lower-indexed varnodes in storage are the more significant pieces, similar
* to big endian. * to big endian.
* *

20
Ghidra/Debug/ProposedUtils/src/main/java/ghidra/util/database/DBAnnotatedObject.java
View file

@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License. * you may not use this file except in compliance with the License.
* You may obtain a copy of the License at * You may obtain a copy of the License at
* *
* http://www.apache.org/licenses/LICENSE-2.0 * http://www.apache.org/licenses/LICENSE-2.0
* *
* Unless required by applicable law or agreed to in writing, software * Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, * distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@ -34,12 +34,12 @@ import ghidra.util.database.annot.DBAnnotatedObjectInfo;
* fields from the record. These objects are managed using a {@link DBCachedObjectStore}. An example * fields from the record. These objects are managed using a {@link DBCachedObjectStore}. An example
* object definition: * object definition:
* *
* <pre> * <pre>{@code
* interface Person { * interface Person {
* // ... * // ...
* } * }
* *
* &#64;DBAnnotatedObjectInfo(version = 1) * @DBAnnotatedObjectInfo(version = 1)
* public class DBPerson extends DBAnnotatedObject implements Person { * public class DBPerson extends DBAnnotatedObject implements Person {
* public static final String TABLE_NAME = "Person"; // Conventionally defined here * public static final String TABLE_NAME = "Person"; // Conventionally defined here
* *
@ -48,15 +48,15 @@ import ghidra.util.database.annot.DBAnnotatedObjectInfo;
* static final String ADDRESS_COLUMN_NAME = "Address"; * static final String ADDRESS_COLUMN_NAME = "Address";
* *
* // Column handles * // Column handles
* &#64;DBAnnotatedColumn(NAME_COLUMN_NAME) * @DBAnnotatedColumn(NAME_COLUMN_NAME)
* static DBObjectColumn NAME_COLUMN; * static DBObjectColumn NAME_COLUMN;
* &#64;DBAnnotatedColumn(ADDRESS_COLUMN_NAME) * @DBAnnotatedColumn(ADDRESS_COLUMN_NAME)
* static DBObjectColumn ADDRESS_COLUMN; * static DBObjectColumn ADDRESS_COLUMN;
* *
* // Column-backed fields * // Column-backed fields
* &#64;DBAnnotatedField(column = NAME_COLUMN_NAME, indexed = true) * @DBAnnotatedField(column = NAME_COLUMN_NAME, indexed = true)
* private String name; * private String name;
* &#64;DBAnnotatedField(column = ADDRESS_COLUMN_NAME) * @DBAnnotatedField(column = ADDRESS_COLUMN_NAME)
* private String address; * private String address;
* *
* DBPerson(DBCachedObjectStore<DBPerson> store, DBRecord record) { * DBPerson(DBCachedObjectStore<DBPerson> store, DBRecord record) {
@ -72,7 +72,7 @@ import ghidra.util.database.annot.DBAnnotatedObjectInfo;
* *
* // ... other methods, getters, setters * // ... other methods, getters, setters
* } * }
* </pre> * }</pre>
* *
* <p> * <p>
* See {@link DBCachedObjectStoreFactory} for example code that uses the example {@code DBPerson} * See {@link DBCachedObjectStoreFactory} for example code that uses the example {@code DBPerson}
@ -192,7 +192,7 @@ public class DBAnnotatedObject extends DatabaseObject {
} }
/** /**
* 2-arity version of {@link #update(DBObjectColumn...)} * 3-arity version of {@link #update(DBObjectColumn...)}
* *
* @param col1 a column * @param col1 a column
* @param col2 another column * @param col2 another column

6
Ghidra/Debug/ProposedUtils/src/main/java/ghidra/util/database/DBCachedDomainObjectAdapter.java
View file

@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License. * you may not use this file except in compliance with the License.
* You may obtain a copy of the License at * You may obtain a copy of the License at
* *
* http://www.apache.org/licenses/LICENSE-2.0 * http://www.apache.org/licenses/LICENSE-2.0
* *
* Unless required by applicable law or agreed to in writing, software * Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, * distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@ -162,7 +162,7 @@ public abstract class DBCachedDomainObjectAdapter extends DBDomainObjectSupport
protected ReadWriteLock rwLock; protected ReadWriteLock rwLock;
/** /**
* @see {@link DBDomainObjectSupport} * @see DBDomainObjectSupport
*/ */
protected DBCachedDomainObjectAdapter(DBHandle dbh, OpenMode openMode, TaskMonitor monitor, protected DBCachedDomainObjectAdapter(DBHandle dbh, OpenMode openMode, TaskMonitor monitor,
String name, int timeInterval, int bufSize, Object consumer) { String name, int timeInterval, int bufSize, Object consumer) {

30
Ghidra/Debug/ProposedUtils/src/main/java/ghidra/util/database/DBCachedObjectStoreFactory.java
View file

@ -41,7 +41,7 @@ import ghidra.util.exception.VersionException;
* See {@link DBAnnotatedObject} for more documentation, including an example object definition. To * See {@link DBAnnotatedObject} for more documentation, including an example object definition. To
* create a store, e.g., for {@code Person}: * create a store, e.g., for {@code Person}:
* *
* <pre> * <pre>{@code
* interface MyDomainObject { * interface MyDomainObject {
* Person createPerson(String name, String address); * Person createPerson(String name, String address);
* *
@ -71,7 +71,7 @@ import ghidra.util.exception.VersionException;
* } * }
* } * }
* *
* &#64;Override * @Override
* public Person createPerson(String name, String address) { * public Person createPerson(String name, String address) {
* // Locking details elided * // Locking details elided
* DBPerson person = people.create(); * DBPerson person = people.create();
@ -79,19 +79,19 @@ import ghidra.util.exception.VersionException;
* return person; * return person;
* } * }
* *
* &#64;Override * @Override
* public Person getPerson(int id) { * public Person getPerson(int id) {
* // Locking details elided * // Locking details elided
* return people.getAt(id); * return people.getAt(id);
* } * }
* *
* &#64;Override * @Override
* public Collection<Person> getPeopleNamed(String name) { * public Collection<Person> getPeopleNamed(String name) {
* // Locking details elided * // Locking details elided
* return peopleByName.get(name); * return peopleByName.get(name);
* } * }
* } * }
* </pre> * }</pre>
* *
* <p> * <p>
* The factory manages tables on behalf of the domain object, so it is typically the first thing * The factory manages tables on behalf of the domain object, so it is typically the first thing
@ -159,7 +159,7 @@ public class DBCachedObjectStoreFactory {
* {@link DBAnnotatedObject} is sufficient. If context is required, then additional interfaces * {@link DBAnnotatedObject} is sufficient. If context is required, then additional interfaces
* can be required via type intersection: * can be required via type intersection:
* *
* <pre> * <pre>{@code
* public interface MyContext { * public interface MyContext {
* // ... * // ...
* } * }
@ -175,14 +175,14 @@ public class DBCachedObjectStoreFactory {
* super(MyType.class, objectType, BinaryField.class, field, column); * super(MyType.class, objectType, BinaryField.class, field, column);
* } * }
* *
* &#64;Override * @Override
* protected void doStore(OT obj, DBRecord record) { * protected void doStore(OT obj, DBRecord record) {
* MyContext ctx = obj.getContext(); * MyContext ctx = obj.getContext();
* // ... * // ...
* } * }
* // ... * // ...
* } * }
* </pre> * }</pre>
* *
* <p> * <p>
* Note that this implementation uses {@link AbstractDBFieldCodec}, which is highly recommended. * Note that this implementation uses {@link AbstractDBFieldCodec}, which is highly recommended.
@ -194,25 +194,25 @@ public class DBCachedObjectStoreFactory {
* {@link BinaryField}. See {@link ByteDBFieldCodec} for the simplest example with actual * {@link BinaryField}. See {@link ByteDBFieldCodec} for the simplest example with actual
* encoding and decoding implementations. To use the example codec in an object: * encoding and decoding implementations. To use the example codec in an object:
* *
* <pre> * <pre>{@code
* &#64;DBAnnotatedObjectInfo(version = 1) * @DBAnnotatedObjectInfo(version = 1)
* public static class SomeObject extends DBAnnotatedObject implements ContextProvider { * public static class SomeObject extends DBAnnotatedObject implements ContextProvider {
* static final String MY_COLUMN_NAME = "My"; * static final String MY_COLUMN_NAME = "My";
* *
* &#64;DBAnnotatedColumn(MY_COLUMN_NAME) * @DBAnnotatedColumn(MY_COLUMN_NAME)
* static DBObjectColumn MY_COLUMN; * static DBObjectColumn MY_COLUMN;
* *
* &#64;DBAnnotatedField(column = MY_COLUMN_NAME, codec = MyDBFieldCodec.class) * @DBAnnotatedField(column = MY_COLUMN_NAME, codec = MyDBFieldCodec.class)
* private MyType my; * private MyType my;
* *
* // ... * // ...
* *
* &#64;Override * @Override
* public MyContext getContext() { * public MyContext getContext() {
* // ... * // ...
* } * }
* } * }
* </pre> * }</pre>
* *
* <p> * <p>
* Notice that {@code SomeObject} must implement {@code ContextProvider}. This restriction is * Notice that {@code SomeObject} must implement {@code ContextProvider}. This restriction is
@ -406,7 +406,7 @@ public class DBCachedObjectStoreFactory {
throws IllegalArgumentException, IllegalAccessException; throws IllegalArgumentException, IllegalAccessException;
/** /**
* Same as {@link #load(DBAnnotatedObject, DBRecord), but permits exceptions * Same as {@link #load(DBAnnotatedObject, DBRecord)}, but permits exceptions
*/ */
protected abstract void doLoad(OT obj, DBRecord record) protected abstract void doLoad(OT obj, DBRecord record)
throws IllegalArgumentException, IllegalAccessException; throws IllegalArgumentException, IllegalAccessException;

2
Ghidra/Debug/ProposedUtils/src/main/java/ghidra/util/database/spatial/AbstractConstraintsTree.java
View file

@ -119,7 +119,6 @@ public abstract class AbstractConstraintsTree< //
* {@link Collection#size()}. Filtering is performed by {@link TreeRecordVisitor}. * {@link Collection#size()}. Filtering is performed by {@link TreeRecordVisitor}.
* *
* @param parent the parent node * @param parent the parent node
* @param query a query to control the ordering of the children
* @return a collection of the children * @return a collection of the children
*/ */
protected Collection<DR> getDataChildrenOf(NR parent) { protected Collection<DR> getDataChildrenOf(NR parent) {
@ -137,7 +136,6 @@ public abstract class AbstractConstraintsTree< //
* {@link TreeRecordVisitor}. * {@link TreeRecordVisitor}.
* *
* @param parent the parent node * @param parent the parent node
* @param query a query to control the ordering of the children
* @return a collection of the children * @return a collection of the children
*/ */
protected Collection<? extends DBTreeRecord<?, ? extends NS>> getChildrenOf(NR parent) { protected Collection<? extends DBTreeRecord<?, ? extends NS>> getChildrenOf(NR parent) {

19
Ghidra/Debug/ProposedUtils/src/main/java/ghidra/util/database/spatial/SpatialMap.java
View file

@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License. * you may not use this file except in compliance with the License.
* You may obtain a copy of the License at * You may obtain a copy of the License at
* *
* http://www.apache.org/licenses/LICENSE-2.0 * http://www.apache.org/licenses/LICENSE-2.0
* *
* Unless required by applicable law or agreed to in writing, software * Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, * distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@ -113,12 +113,13 @@ public interface SpatialMap<DS extends BoundedShape<?>, T, Q> {
/** /**
* Put an entry into the map * Put an entry into the map
* *
* <p>
* Note that the map may copy, and possibly modify, the given value. The value returned is the * Note that the map may copy, and possibly modify, the given value. The value returned is the
* value actually stored by the map. This may be useful when the map's values are identical to * value actually stored by the map. This may be useful when the map's values are identical to
* its records. This allows the creation of a "blank" entry with a given shape. The entry is * its records. This allows the creation of a "blank" entry with a given shape. The entry is
* then populated by the user. * then populated by the user.
* *
* <pre> * <pre>{@code
* class MyDBDataRecord extends DBTreeDataRecord<MyShape, MyNodeShape, MyDBDataRecord> { * class MyDBDataRecord extends DBTreeDataRecord<MyShape, MyNodeShape, MyDBDataRecord> {
* &#64;Override * &#64;Override
* protected void setValue(MyDBDataRecord value) { * protected void setValue(MyDBDataRecord value) {
@ -129,18 +130,17 @@ public interface SpatialMap<DS extends BoundedShape<?>, T, Q> {
* return this; // The record is the value * return this; // The record is the value
* } * }
* } * }
* </pre>
* *
* <pre>
* MyDBDataRecord rec = map.put(MyShape.create(args), null); * MyDBDataRecord rec = map.put(MyShape.create(args), null);
* rec.setSomething(6); * rec.setSomething(6);
* rec.setAnother("My user data"); * rec.setAnother("My user data");
* </pre> * }</pre>
* *
* <p>
* This practice is preferred when the values are not simple, and/or when the shape is a * This practice is preferred when the values are not simple, and/or when the shape is a
* property of the value. In other cases, e.g., when the value is an enum or a {@link Color}, * property of the value. In other cases, e.g., when the value is an enum or a {@link Color},
* then {@link DBTreeDataRecord#setValue(Object)} and {@link DBTreeDataRecord#getValue()} should * then {@link DBTreeDataRecord#setRecordValue(Object)} and
* be implemented as field accessors. * {@link DBTreeDataRecord#getRecordValue()} should be implemented as field accessors.
* *
* @param shape the shape of the entry * @param shape the shape of the entry
* @param value the value for the entry * @param value the value for the entry
@ -151,6 +151,7 @@ public interface SpatialMap<DS extends BoundedShape<?>, T, Q> {
/** /**
* Remove an entry from the map * Remove an entry from the map
* *
* <p>
* Removes a single matching entry, if found, from the map. If you have a reference to an entry * Removes a single matching entry, if found, from the map. If you have a reference to an entry
* obtained from this map, use {@link #remove(Entry)} instead. Otherwise, this is the preferred * obtained from this map, use {@link #remove(Entry)} instead. Otherwise, this is the preferred
* method. * method.
@ -164,6 +165,7 @@ public interface SpatialMap<DS extends BoundedShape<?>, T, Q> {
/** /**
* Remove an entry from the map * Remove an entry from the map
* *
* <p>
* This method is preferred <em>only</em> when the given entry comes directly from this map. * This method is preferred <em>only</em> when the given entry comes directly from this map.
* This spares the implementation from having to search for a matching entry. If the entry does * This spares the implementation from having to search for a matching entry. If the entry does
* not come from this map, it will behave like {@link #remove(BoundedShape, Object)}. * not come from this map, it will behave like {@link #remove(BoundedShape, Object)}.
@ -176,6 +178,7 @@ public interface SpatialMap<DS extends BoundedShape<?>, T, Q> {
/** /**
* Get or compute the size of this map * Get or compute the size of this map
* *
* <p>
* Note that this may not necessarily be a quick operation, esp., if this map is the result of * Note that this may not necessarily be a quick operation, esp., if this map is the result of
* {@link #reduce(Object)}. In the worst case, all elements in the reduced map will be visited. * {@link #reduce(Object)}. In the worst case, all elements in the reduced map will be visited.
* *

12
Ghidra/Debug/ProposedUtils/src/main/java/utilities/util/SuppressableCallback.java
View file

@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License. * you may not use this file except in compliance with the License.
* You may obtain a copy of the License at * You may obtain a copy of the License at
* *
* http://www.apache.org/licenses/LICENSE-2.0 * http://www.apache.org/licenses/LICENSE-2.0
* *
* Unless required by applicable law or agreed to in writing, software * Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, * distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@ -35,7 +35,7 @@ import java.util.function.*;
* A common use case is for a method to suppress any recursive calls, i.e., it is self suppressing, * A common use case is for a method to suppress any recursive calls, i.e., it is self suppressing,
* e.g.: * e.g.:
* *
* <pre> * <pre>{@code
* private final SuppressableCallback<Void> cbDoSomething = new SuppressableCallback<>(); * private final SuppressableCallback<Void> cbDoSomething = new SuppressableCallback<>();
* *
* public boolean doSomething() { * public boolean doSomething() {
@ -51,7 +51,7 @@ import java.util.function.*;
* // do the other thing * // do the other thing
* return doSomething(); * return doSomething();
* } * }
* </pre> * }</pre>
* *
* <p> * <p>
* This example is very trivial, but this sort of thing can easily happen in event driven * This example is very trivial, but this sort of thing can easily happen in event driven
@ -62,6 +62,8 @@ import java.util.function.*;
* resulting in unending oscillation between the requested states. A more robust solution demands we * resulting in unending oscillation between the requested states. A more robust solution demands we
* know the cause(s) of events. For now, the solution is to suppress event firing whenever a state * know the cause(s) of events. For now, the solution is to suppress event firing whenever a state
* change is due to receiving an event. * change is due to receiving an event.
*
* @param <T> the type of return value, often {@link Void}
*/ */
public class SuppressableCallback<T> { public class SuppressableCallback<T> {
/** /**
@ -193,7 +195,7 @@ public class SuppressableCallback<T> {
* The callback is always invoked, allowing it to decide what actions to take (or not take) * The callback is always invoked, allowing it to decide what actions to take (or not take)
* based on the values present in the stack. * based on the values present in the stack.
* *
* @param callback * @param callback a method to receive the stack
*/ */
public void invokeWithStack(Consumer<List<T>> callback) { public void invokeWithStack(Consumer<List<T>> callback) {
callback.accept(stack.get().view); callback.accept(stack.get().view);

9
Ghidra/Debug/TaintAnalysis/build.gradle
View file

@ -13,10 +13,11 @@
* See the License for the specific language governing permissions and * See the License for the specific language governing permissions and
* limitations under the License. * limitations under the License.
*/ */
apply from: "$rootProject.projectDir/gradle/javaProject.gradle" apply from: "${rootProject.projectDir}/gradle/javaProject.gradle"
apply from: "$rootProject.projectDir/gradle/jacocoProject.gradle" apply from: "${rootProject.projectDir}/gradle/jacocoProject.gradle"
apply from: "$rootProject.projectDir/gradle/javaTestProject.gradle" apply from: "${rootProject.projectDir}/gradle/javaTestProject.gradle"
apply from: "$rootProject.projectDir/gradle/distributableGhidraModule.gradle" apply from: "${rootProject.projectDir}/gradle/distributableGhidraModule.gradle"
apply from: "${rootProject.projectDir}/gradle/javadoc.gradle"
apply plugin: 'eclipse' apply plugin: 'eclipse'
eclipse.project.name = 'Debug TaintAnalysis' eclipse.project.name = 'Debug TaintAnalysis'

7
Ghidra/Debug/TaintAnalysis/src/main/java/ghidra/pcode/emu/taint/TaintPartsFactory.java
View file

@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License. * you may not use this file except in compliance with the License.
* You may obtain a copy of the License at * You may obtain a copy of the License at
* *
* http://www.apache.org/licenses/LICENSE-2.0 * http://www.apache.org/licenses/LICENSE-2.0
* *
* Unless required by applicable law or agreed to in writing, software * Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, * distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@ -51,12 +51,13 @@ import ghidra.taint.model.TaintVec;
* <li>P-code Arithmetic: {@link TaintPcodeArithmetic}</li> * <li>P-code Arithmetic: {@link TaintPcodeArithmetic}</li>
* <li>Userop Library: {@link TaintPcodeUseropLibrary}</li> * <li>Userop Library: {@link TaintPcodeUseropLibrary}</li>
* <li>P-code Executor: {@link TaintPcodeThreadExecutor}</li> * <li>P-code Executor: {@link TaintPcodeThreadExecutor}</li>
* <li>Machine State</li> * <li>Machine State
* <ul> * <ul>
* <li>Stand alone: {@link TaintPcodeExecutorState}</li> * <li>Stand alone: {@link TaintPcodeExecutorState}</li>
* <li>Trace integrated: {@link TaintTracePcodeExecutorState}</li> * <li>Trace integrated: {@link TaintTracePcodeExecutorState}</li>
* <li>Debugger integrated: {@link TaintTracePcodeExecutorState} (same as Trace integrated)</li> * <li>Debugger integrated: {@link TaintTracePcodeExecutorState} (same as Trace integrated)</li>
* </ul> * </ul>
* </li>
* </ul> * </ul>
* *
* <p> * <p>

13
Ghidra/Debug/TaintAnalysis/src/main/java/ghidra/pcode/emu/taint/TaintPcodeThreadExecutor.java
View file

@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License. * you may not use this file except in compliance with the License.
* You may obtain a copy of the License at * You may obtain a copy of the License at
* *
* http://www.apache.org/licenses/LICENSE-2.0 * http://www.apache.org/licenses/LICENSE-2.0
* *
* Unless required by applicable law or agreed to in writing, software * Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, * distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@ -19,8 +19,8 @@ import org.apache.commons.lang3.tuple.Pair;
import ghidra.pcode.emu.DefaultPcodeThread; import ghidra.pcode.emu.DefaultPcodeThread;
import ghidra.pcode.emu.DefaultPcodeThread.PcodeThreadExecutor; import ghidra.pcode.emu.DefaultPcodeThread.PcodeThreadExecutor;
import ghidra.pcode.exec.PcodeExecutor; import ghidra.pcode.exec.*;
import ghidra.pcode.exec.PcodeFrame; import ghidra.pcode.exec.PcodeArithmetic.Purpose;
import ghidra.program.model.pcode.PcodeOp; import ghidra.program.model.pcode.PcodeOp;
import ghidra.taint.model.TaintVec; import ghidra.taint.model.TaintVec;
import ghidra.util.Msg; import ghidra.util.Msg;
@ -52,9 +52,8 @@ public class TaintPcodeThreadExecutor extends PcodeThreadExecutor<Pair<byte[], T
* This is invoked on every {@link PcodeOp#CBRANCH}, allowing us a decent place to instrument * This is invoked on every {@link PcodeOp#CBRANCH}, allowing us a decent place to instrument
* the emulator and add some diagnostics. Refer to * the emulator and add some diagnostics. Refer to
* {@link PcodeExecutor#executeConditionalBranch(PcodeOp, PcodeFrame)} to see the operations * {@link PcodeExecutor#executeConditionalBranch(PcodeOp, PcodeFrame)} to see the operations
* inputs. Alternatively, we could override * inputs. Alternatively, we could override {@link PcodeArithmetic#isTrue(Object, Purpose)};
* {@link TaintPcodeArithmetic#isTrue(TaintVec, Purpose)}; however, we'd have access to less * however, we'd have access to less contextual information at that position.
* contextual information at that position.
*/ */
@Override @Override
public void executeConditionalBranch(PcodeOp op, PcodeFrame frame) { public void executeConditionalBranch(PcodeOp op, PcodeFrame frame) {

3
Ghidra/Debug/TaintAnalysis/src/main/java/ghidra/pcode/emu/taint/full/TaintDebuggerPcodeEmulator.java
View file

@ -42,8 +42,7 @@ public class TaintDebuggerPcodeEmulator extends AuxDebuggerPcodeEmulator<TaintVe
* Here, we just return the singleton parts factory. This appears simple because all the * Here, we just return the singleton parts factory. This appears simple because all the
* complexity is encapsulated in the factory. See {@link TaintPartsFactory} to see everything * complexity is encapsulated in the factory. See {@link TaintPartsFactory} to see everything
* the implementation actually entails. Notice that this is the same parts factory used by * the implementation actually entails. Notice that this is the same parts factory used by
* {@link TaintPcodeEmulator}. The {@link AuxDebugggerPcodeEmulator} knows to use the more * {@link TaintPcodeEmulator}.
* capable state parts.
*/ */
@Override @Override
protected AuxDebuggerEmulatorPartsFactory<TaintVec> getPartsFactory() { protected AuxDebuggerEmulatorPartsFactory<TaintVec> getPartsFactory() {

8
Ghidra/Debug/TaintAnalysis/src/main/java/ghidra/pcode/emu/taint/plain/TaintPcodeExecutorStatePiece.java
View file

@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License. * you may not use this file except in compliance with the License.
* You may obtain a copy of the License at * You may obtain a copy of the License at
* *
* http://www.apache.org/licenses/LICENSE-2.0 * http://www.apache.org/licenses/LICENSE-2.0
* *
* Unless required by applicable law or agreed to in writing, software * Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, * distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@ -39,8 +39,8 @@ import ghidra.program.model.lang.Language;
* want to implement {@link TracePcodeExecutorState} directly, take the concrete piece provided, and * want to implement {@link TracePcodeExecutorState} directly, take the concrete piece provided, and
* wrap it as you see fit. You may still benefit by referring to the implementation of * wrap it as you see fit. You may still benefit by referring to the implementation of
* {@link PairedPcodeExecutorState}. When implementing your flavor of * {@link PairedPcodeExecutorState}. When implementing your flavor of
* {@link PairedPcodeExecutorState#getVar(AddressSpace, Pair, int, boolean)}, still consider that * {@link PairedPcodeExecutorState#getVar(AddressSpace, Pair, int, boolean, Reason)}, still consider
* you could benefit from the concrete element of the offset pair passed in. * that you could benefit from the concrete element of the offset pair passed in.
*/ */
public class TaintPcodeExecutorStatePiece extends AbstractTaintPcodeExecutorStatePiece<TaintSpace> { public class TaintPcodeExecutorStatePiece extends AbstractTaintPcodeExecutorStatePiece<TaintSpace> {
/** /**

6
Ghidra/Debug/TaintAnalysis/src/main/java/ghidra/pcode/emu/taint/trace/TaintTracePcodeExecutorStatePiece.java
View file

@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License. * you may not use this file except in compliance with the License.
* You may obtain a copy of the License at * You may obtain a copy of the License at
* *
* http://www.apache.org/licenses/LICENSE-2.0 * http://www.apache.org/licenses/LICENSE-2.0
* *
* Unless required by applicable law or agreed to in writing, software * Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, * distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@ -29,7 +29,7 @@ import ghidra.trace.model.property.TracePropertyMapSpace;
* The trace-integrated state piece for holding taint marks * The trace-integrated state piece for holding taint marks
* *
* <p> * <p>
* See {@link AbstractTaintTracePcodeExecutorStatePiece} for framing. We'll store taint sets in the * See {@link AbstractTaintPcodeExecutorStatePiece} for framing. We'll store taint sets in the
* trace's address property map, which is the recommended scheme for auxiliary state. * trace's address property map, which is the recommended scheme for auxiliary state.
*/ */
public class TaintTracePcodeExecutorStatePiece public class TaintTracePcodeExecutorStatePiece

3
Ghidra/Debug/TaintAnalysis/src/main/java/ghidra/pcode/emu/taint/trace/TaintTraceSpace.java
View file

@ -37,8 +37,7 @@ public class TaintTraceSpace extends TaintSpace {
* Create the space * Create the space
* *
* @param space the address space * @param space the address space
* @param backing if present, the backing object * @param property the trace property backing this space
* @param snap the source snap
*/ */
public TaintTraceSpace(AddressSpace space, PcodeTracePropertyAccess<String> property) { public TaintTraceSpace(AddressSpace space, PcodeTracePropertyAccess<String> property) {
this.space = space; this.space = space;

10
Ghidra/Debug/TaintAnalysis/src/main/java/ghidra/pcode/emu/taint/trace/package-info.java
View file

@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License. * you may not use this file except in compliance with the License.
* You may obtain a copy of the License at * You may obtain a copy of the License at
* *
* http://www.apache.org/licenses/LICENSE-2.0 * http://www.apache.org/licenses/LICENSE-2.0
* *
* Unless required by applicable law or agreed to in writing, software * Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, * distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@ -17,9 +17,9 @@
* The trace-integrated Taint Emulator * The trace-integrated Taint Emulator
* *
* <p> * <p>
* This package builds on {@link ghidra.pcode.emu.plain} to construct a trace-integrated emulator. * This package builds on the emulation framework to construct a trace-integrated emulator. The
* See that package for remarks about this "working solution." Those state components were factored * framework's state components were designed to accommodate the state components introduced by this
* to accommodate the state components introduced by this package. * package.
* *
* <p> * <p>
* For this package, I recommend a bottom-up approach, since you should already be familiar with the * For this package, I recommend a bottom-up approach, since you should already be familiar with the

22
Ghidra/Debug/TaintAnalysis/src/main/java/ghidra/taint/model/package-info.java
View file

@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License. * you may not use this file except in compliance with the License.
* You may obtain a copy of the License at * You may obtain a copy of the License at
* *
* http://www.apache.org/licenses/LICENSE-2.0 * http://www.apache.org/licenses/LICENSE-2.0
* *
* Unless required by applicable law or agreed to in writing, software * Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, * distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@ -17,12 +17,13 @@
* The Taint domain package * The Taint domain package
* *
* <p> * <p>
* This package implements the domain of taint analysis. {@link TaintVec} models an array of bytes, * This package implements the domain of taint analysis. {@link ghidra.taint.model.TaintVec} models
* each having a {@link TaintSet}. A {@link TaintSet} is in turn made of several {@link TaintMarks}. * an array of bytes, each having a {@link ghidra.taint.model.TaintSet}. A
* Each mark is a symbol with optional tags. We use the tags as a means of handling indirection, so * {@link ghidra.taint.model.TaintSet} is in turn made of several
* that we don't have to decide up front whether tainted offsets taint the values read and written * {@link ghidra.taint.model.TaintMark}s. Each mark is a symbol with optional tags. We use the tags
* from memory. We allow them to be tainted, but add a tag to the mark, so they can be examined * as a means of handling indirection, so that we don't have to decide up front whether tainted
* and/or filtered by the user. * offsets taint the values read and written from memory. We allow them to be tainted, but add a tag
* to the mark, so they can be examined and/or filtered by the user.
* *
* <p> * <p>
* To facilitate storage and presentation of taint, we will need to implement some * To facilitate storage and presentation of taint, we will need to implement some
@ -30,7 +31,8 @@
* parse method for sets and marks. * parse method for sets and marks.
* *
* <p> * <p>
* We recommend you read the documentation and source from the bottom up: {@link TaintMark}, * We recommend you read the documentation and source from the bottom up:
* {@link TaintSet}, {@link TaintVec}. * {@link ghidra.taint.model.TaintMark}, {@link ghidra.taint.model.TaintSet},
* {@link ghidra.taint.model.TaintVec}.
*/ */
package ghidra.taint.model; package ghidra.taint.model;