diff --git a/Ghidra/Debug/Debugger-api/build.gradle b/Ghidra/Debug/Debugger-api/build.gradle index 9d53c355f6..6a5af1d6ac 100644 --- a/Ghidra/Debug/Debugger-api/build.gradle +++ b/Ghidra/Debug/Debugger-api/build.gradle @@ -4,9 +4,9 @@ * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at - * + * * http://www.apache.org/licenses/LICENSE-2.0 - * + * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -18,6 +18,7 @@ apply from: "${rootProject.projectDir}/gradle/javaProject.gradle" apply from: "${rootProject.projectDir}/gradle/jacocoProject.gradle" apply from: "${rootProject.projectDir}/gradle/javaTestProject.gradle" apply from: "${rootProject.projectDir}/gradle/distributableGhidraModule.gradle" +apply from: "${rootProject.projectDir}/gradle/javadoc.gradle" apply plugin: 'eclipse' eclipse.project.name = 'Debug Debugger-api' diff --git a/Ghidra/Debug/Debugger-api/src/main/java/ghidra/app/services/DebuggerPlatformService.java b/Ghidra/Debug/Debugger-api/src/main/java/ghidra/app/services/DebuggerPlatformService.java index 0cf60bc3e6..296e3a9e44 100644 --- a/Ghidra/Debug/Debugger-api/src/main/java/ghidra/app/services/DebuggerPlatformService.java +++ b/Ghidra/Debug/Debugger-api/src/main/java/ghidra/app/services/DebuggerPlatformService.java @@ -38,8 +38,8 @@ public interface DebuggerPlatformService { *

* 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 - * {@link #getNewMapper(TraceObject)} and set it as the current mapper before returning. If a - * new mapper is set, the trace is also initialized for that mapper. + * {@link #getNewMapper(Trace, TraceObject, long)} and set it as the current mapper before + * returning. If a new mapper is set, the trace is also initialized for that mapper. * * @param trace the trace * @param object the object for which a mapper is desired diff --git a/Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/emulation/DebuggerPcodeEmulatorFactory.java b/Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/emulation/DebuggerPcodeEmulatorFactory.java index 026acaccce..6a825ffee6 100644 --- a/Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/emulation/DebuggerPcodeEmulatorFactory.java +++ b/Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/emulation/DebuggerPcodeEmulatorFactory.java @@ -4,9 +4,9 @@ * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at - * + * * http://www.apache.org/licenses/LICENSE-2.0 - * + * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -22,10 +22,6 @@ import ghidra.util.classfinder.ExtensionPoint; /** * A factory for configuring and creating a Debugger-integrated emulator - * - *

- * See {@link BytesDebuggerPcodeEmulatorFactory} for the default implementation. See the Taint - * Analyzer for the archetype of alternative implementations. */ public interface DebuggerPcodeEmulatorFactory extends ExtensionPoint { // TODO: Config options, use ModelFactory as a model diff --git a/Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/emulation/DebuggerPcodeMachine.java b/Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/emulation/DebuggerPcodeMachine.java index 5526ae0125..6fdc418491 100644 --- a/Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/emulation/DebuggerPcodeMachine.java +++ b/Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/emulation/DebuggerPcodeMachine.java @@ -4,9 +4,9 @@ * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at - * + * * http://www.apache.org/licenses/LICENSE-2.0 - * + * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -20,10 +20,6 @@ import ghidra.pcode.exec.trace.TracePcodeMachine; /** * A Debugger-integrated emulator (or p-code machine) * - *

- * 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 the type of values in the machine's memory and registers */ public interface DebuggerPcodeMachine extends TracePcodeMachine { diff --git a/Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/emulation/PcodeDebuggerAccess.java b/Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/emulation/PcodeDebuggerAccess.java index fb865c4fc8..266aabbe8f 100644 --- a/Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/emulation/PcodeDebuggerAccess.java +++ b/Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/emulation/PcodeDebuggerAccess.java @@ -4,9 +4,9 @@ * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at - * + * * http://www.apache.org/licenses/LICENSE-2.0 - * + * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -26,8 +26,7 @@ import ghidra.trace.model.thread.TraceThread; * 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 * 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 - * starting with {@link DefaultPcodeDebuggerAccess}. + * static images. It supports the same method chain pattern as {@link PcodeTraceAccess}. */ public interface PcodeDebuggerAccess extends PcodeTraceAccess { @Override diff --git a/Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/target/Target.java b/Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/target/Target.java index 2c47b9d11d..b73df1886d 100644 --- a/Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/target/Target.java +++ b/Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/target/Target.java @@ -519,8 +519,10 @@ public interface Target { * be recorded into the trace before this method returns. If the request is * unsuccessful, this method throw an exception. * - * @param address the starting address - * @param data the bytes to write + * @param platform the platform whose language defines the registers + * @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); @@ -548,7 +550,7 @@ public interface Target { * @param thread if a register, the thread whose registers to examine * @param frame the frame level, usually 0. * @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 */ boolean isVariableExists(TracePlatform platform, TraceThread thread, int frame, Address address, @@ -558,8 +560,7 @@ public interface Target { * @see #writeVariable(TracePlatform, TraceThread, int, Address, byte[]) */ CompletableFuture writeVariableAsync(TracePlatform platform, TraceThread thread, - int frame, - Address address, byte[] data); + int frame, Address address, byte[] data); /** * Write a variable (memory or register) of the given thread or the process @@ -571,7 +572,7 @@ public interface Target { * {@link #writeMemory(Address, byte[])}. * * @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 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 * 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 - * {@link #collectActions(ActionName, ActionContext)} with {@link ActionName#KILL}. + * {@link #collectActions(ActionName, ActionContext, ObjectArgumentPolicy)} with + * {@link ActionName#KILL}. */ void forceTerminate(); diff --git a/Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/tracermi/RemoteMethod.java b/Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/tracermi/RemoteMethod.java index e4325badd7..5f37869782 100644 --- a/Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/tracermi/RemoteMethod.java +++ b/Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/tracermi/RemoteMethod.java @@ -117,7 +117,7 @@ public interface RemoteMethod { * Check the type of an argument. * *

- * 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 * trace stuff is not in its dependencies. * diff --git a/Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/tracermi/TraceRmiAcceptor.java b/Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/tracermi/TraceRmiAcceptor.java index ece13a58cf..12f6fbc8b4 100644 --- a/Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/tracermi/TraceRmiAcceptor.java +++ b/Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/tracermi/TraceRmiAcceptor.java @@ -4,9 +4,9 @@ * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at - * + * * http://www.apache.org/licenses/LICENSE-2.0 - * + * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -34,6 +34,7 @@ public interface TraceRmiAcceptor { * * @return the connection, if successful * @throws IOException if there was an error + * @throws CancelledException if {@link #cancel()} is called, usually from the user canceling */ TraceRmiConnection accept() throws IOException, CancelledException; @@ -64,8 +65,8 @@ public interface TraceRmiAcceptor { * *

* If a different thread has called {@link #accept()}, it will fail. In this case, both - * {@linkplain TraceRmiServiceListener#acceptCancelled(TraceRmiAcceptor)} and - * {@linkplain TraceRmiServiceListener#acceptFailed(Exception)} may be invoked. + * {@link TraceRmiServiceListener#acceptCancelled(TraceRmiAcceptor)} and + * {@link TraceRmiServiceListener#acceptFailed(TraceRmiAcceptor, Exception)} may be invoked. */ void cancel(); } diff --git a/Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/tracermi/TraceRmiServiceListener.java b/Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/tracermi/TraceRmiServiceListener.java index 24034ded05..ed5bafc826 100644 --- a/Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/tracermi/TraceRmiServiceListener.java +++ b/Ghidra/Debug/Debugger-api/src/main/java/ghidra/debug/api/tracermi/TraceRmiServiceListener.java @@ -86,8 +86,9 @@ public interface TraceRmiServiceListener { * *

* The acceptor remains valid until one of three events occurs: - * {@linkplain} #connected(TraceRmiConnection, ConnectMode, TraceRmiAcceptor)}, - * {@linkplain} #acceptCancelled(TraceRmiAcceptor)}, or {@linkplain} #acceptFailed(Exception)}. + * {@link #connected(TraceRmiConnection, ConnectMode, TraceRmiAcceptor)}, + * {@link #acceptCancelled(TraceRmiAcceptor)}, or + * {@link #acceptFailed(TraceRmiAcceptor, Exception)}. * * @param acceptor the acceptor waiting */ diff --git a/Ghidra/Debug/Debugger-rmi-trace/build.gradle b/Ghidra/Debug/Debugger-rmi-trace/build.gradle index 8fa654b6c5..8fda8790eb 100644 --- a/Ghidra/Debug/Debugger-rmi-trace/build.gradle +++ b/Ghidra/Debug/Debugger-rmi-trace/build.gradle @@ -19,6 +19,7 @@ apply from: "${rootProject.projectDir}/gradle/helpProject.gradle" apply from: "${rootProject.projectDir}/gradle/jacocoProject.gradle" apply from: "${rootProject.projectDir}/gradle/javaTestProject.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/hasPythonPackage.gradle" diff --git a/Ghidra/Debug/Debugger-rmi-trace/src/main/java/ghidra/debug/spi/tracermi/TraceRmiLaunchOpinion.java b/Ghidra/Debug/Debugger-rmi-trace/src/main/java/ghidra/debug/spi/tracermi/TraceRmiLaunchOpinion.java index 6d9388d074..cb9a308e5e 100644 --- a/Ghidra/Debug/Debugger-rmi-trace/src/main/java/ghidra/debug/spi/tracermi/TraceRmiLaunchOpinion.java +++ b/Ghidra/Debug/Debugger-rmi-trace/src/main/java/ghidra/debug/spi/tracermi/TraceRmiLaunchOpinion.java @@ -4,9 +4,9 @@ * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at - * + * * http://www.apache.org/licenses/LICENSE-2.0 - * + * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -22,7 +22,6 @@ import ghidra.app.plugin.core.debug.service.tracermi.TraceRmiHandler; import ghidra.app.services.InternalTraceRmiService; import ghidra.debug.api.tracermi.TraceRmiLaunchOffer; import ghidra.framework.options.Options; -import ghidra.framework.plugintool.PluginTool; import ghidra.program.model.listing.Program; import ghidra.util.classfinder.ExtensionPoint; @@ -30,15 +29,14 @@ import ghidra.util.classfinder.ExtensionPoint; * A factory of launch offers * *

- * Each factory 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 - * tool. + * Each opinion is instantiated only once for the entire application, even when multiple tools are + * open. */ public interface TraceRmiLaunchOpinion extends ExtensionPoint { /** * Register any options * - * @param tool the tool + * @param options the tool options */ default void registerOptions(Options options) { } @@ -75,7 +73,7 @@ public interface TraceRmiLaunchOpinion extends ExtensionPoint { * @param plugin the Trace RMI launcher service plugin. NOTE: to get access to the Trace * RMI (connection) service, use the {@link InternalTraceRmiService}, so that the * 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. * @param program the current program. While this is not always used by the launcher, * it is implied that the user expects the debugger to do something with the current diff --git a/Ghidra/Debug/Debugger/build.gradle b/Ghidra/Debug/Debugger/build.gradle index 2cd52327a8..0117ab919c 100644 --- a/Ghidra/Debug/Debugger/build.gradle +++ b/Ghidra/Debug/Debugger/build.gradle @@ -18,6 +18,7 @@ apply from: "${rootProject.projectDir}/gradle/helpProject.gradle" apply from: "${rootProject.projectDir}/gradle/jacocoProject.gradle" apply from: "${rootProject.projectDir}/gradle/javaTestProject.gradle" apply from: "${rootProject.projectDir}/gradle/distributableGhidraModule.gradle" +apply from: "${rootProject.projectDir}/gradle/javadoc.gradle" apply plugin: 'eclipse' eclipse.project.name = 'Debug Debugger' diff --git a/Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/stack/StackUnwinder.java b/Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/stack/StackUnwinder.java index 486359a7e8..fd8ffb8e33 100644 --- a/Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/stack/StackUnwinder.java +++ b/Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/stack/StackUnwinder.java @@ -58,12 +58,12 @@ import ghidra.util.task.TaskMonitor; *

* The usage pattern is typically: * - * 

+ * 
{@code
  * StackUnwinder unwinder = new StackUnwinder(tool, coordinates.getPlatform());
  * for (AnalysisUnwoundFrame frame : unwinder.frames(coordinates.frame(0), monitor)) {
  * 	// check and/or cache the frame
  * }
- * 

+ * }
* *

* Typically, a frame is sought either by its level or by its function. Once found, several diff --git a/Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/stack/SymPcodeExecutorState.java b/Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/stack/SymPcodeExecutorState.java index dc7297774a..dc8e49edef 100644 --- a/Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/stack/SymPcodeExecutorState.java +++ b/Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/stack/SymPcodeExecutorState.java @@ -214,8 +214,8 @@ public class SymPcodeExecutorState implements PcodeExecutorState { *

* There are two cases: *

* * @return the address (stack offset or register) of the return address diff --git a/Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/stack/UnwindAnalysis.java b/Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/stack/UnwindAnalysis.java index 5c91d186e7..f23fd84242 100644 --- a/Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/stack/UnwindAnalysis.java +++ b/Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/stack/UnwindAnalysis.java @@ -419,16 +419,16 @@ public class UnwindAnalysis { * function return. *
  • 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 - * register is involved. See {@link SymPcodeExecutorState#computeAddressOfReturn()}. + * register is involved. See {@link SymPcodeExecutorState#computeAddressOfReturn()}.
    • *
  • 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()}, * {@link UnwindInfo#computeNextSp(Address)}, and - * {@link SymPcodeExecutorState#computeStackDepth()}. + * {@link SymPcodeExecutorState#computeStackDepth()}.
    • *
  • 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. * See {@link UnwindInfo#saved()}, * {@link UnwindInfo#mapSavedRegisters(Address, SavedRegisterMap)}, and - * {@link SymPcodeExecutorState#computeMapUsingRegisters()}. + * {@link SymPcodeExecutorState#computeMapUsingRegisters()}.
    • * * *

    diff --git a/Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/stack/UnwoundFrame.java b/Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/stack/UnwoundFrame.java index f638ca878c..f8d265d609 100644 --- a/Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/stack/UnwoundFrame.java +++ b/Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/stack/UnwoundFrame.java @@ -115,7 +115,7 @@ public interface UnwoundFrame { * assuming the callee has not saved that register to the stack. *

  • 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 - * method will throw an exception. + * method will throw an exception.
    • * * * @return the return address diff --git a/Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/utils/MiscellaneousUtils.java b/Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/utils/MiscellaneousUtils.java index f54933bee4..2638e7df3b 100644 --- a/Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/utils/MiscellaneousUtils.java +++ b/Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/utils/MiscellaneousUtils.java @@ -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. * *

    * Note that a returned value of 0 indicates 2 to the power 64, which is just 1 too high to fit diff --git a/Ghidra/Debug/Debugger/src/main/java/ghidra/pcode/exec/DebuggerPcodeUtils.java b/Ghidra/Debug/Debugger/src/main/java/ghidra/pcode/exec/DebuggerPcodeUtils.java index 1fd25ce6a1..20992e9fc4 100644 --- a/Ghidra/Debug/Debugger/src/main/java/ghidra/pcode/exec/DebuggerPcodeUtils.java +++ b/Ghidra/Debug/Debugger/src/main/java/ghidra/pcode/exec/DebuggerPcodeUtils.java @@ -4,9 +4,9 @@ * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at - * + * * http://www.apache.org/licenses/LICENSE-2.0 - * + * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -64,8 +64,7 @@ public enum DebuggerPcodeUtils { * A p-code parser that can resolve labels from a trace or its mapped programs. */ 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 DebuggerCoordinates coordinates; @@ -447,8 +446,8 @@ public enum DebuggerPcodeUtils { * A p-code arithmetic on watch values * *

    - * This is just a composition of four arithmetics. Using Pair> would be - * unwieldy. + * This is just a composition of four arithmetics. Using {@code Pair>} would + * be unwieldy. */ public enum WatchValuePcodeArithmetic implements PcodeArithmetic { BIG_ENDIAN(BytesPcodeArithmetic.BIG_ENDIAN, LocationPcodeArithmetic.BIG_ENDIAN), diff --git a/Ghidra/Debug/Framework-TraceModeling/build.gradle b/Ghidra/Debug/Framework-TraceModeling/build.gradle index 88ac65a4d6..c96d296ec8 100644 --- a/Ghidra/Debug/Framework-TraceModeling/build.gradle +++ b/Ghidra/Debug/Framework-TraceModeling/build.gradle @@ -17,6 +17,7 @@ apply from: "${rootProject.projectDir}/gradle/javaProject.gradle" apply from: "${rootProject.projectDir}/gradle/jacocoProject.gradle" apply from: "${rootProject.projectDir}/gradle/javaTestProject.gradle" apply from: "${rootProject.projectDir}/gradle/distributableGhidraModule.gradle" +apply from: "${rootProject.projectDir}/gradle/javadoc.gradle" apply plugin: 'eclipse' eclipse.project.name = 'Debug Framework-TraceModeling' diff --git a/Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/pcode/exec/trace/AbstractCheckedTraceCachedWriteBytesPcodeExecutorStatePiece.java b/Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/pcode/exec/trace/AbstractCheckedTraceCachedWriteBytesPcodeExecutorStatePiece.java index 37432fa331..a71d8e8dfa 100644 --- a/Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/pcode/exec/trace/AbstractCheckedTraceCachedWriteBytesPcodeExecutorStatePiece.java +++ b/Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/pcode/exec/trace/AbstractCheckedTraceCachedWriteBytesPcodeExecutorStatePiece.java @@ -4,9 +4,9 @@ * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at - * + * * http://www.apache.org/licenses/LICENSE-2.0 - * + * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -111,7 +111,6 @@ public abstract class AbstractCheckedTraceCachedWriteBytesPcodeExecutorStatePiec * @param size the size of the requested read * @param uninitialized the portion of the read that is uninitialized * @return the adjusted size of the read - * @throws Exception to interrupt the emulator */ protected abstract int checkUninitialized(PcodeTraceDataAccess backing, Address start, int size, AddressSet uninitialized); diff --git a/Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/pcode/exec/trace/data/PcodeTraceAccess.java b/Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/pcode/exec/trace/data/PcodeTraceAccess.java index d0c59b5917..db4b30a331 100644 --- a/Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/pcode/exec/trace/data/PcodeTraceAccess.java +++ b/Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/pcode/exec/trace/data/PcodeTraceAccess.java @@ -4,9 +4,9 @@ * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at - * + * * http://www.apache.org/licenses/LICENSE-2.0 - * + * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -54,23 +54,28 @@ import ghidra.trace.model.thread.TraceThread; * new DefaultPcodeTraceAccess(trace.getPlatformManager().getHostPlatform(), 0, 0); * * + * *

  • Typically invoked by a factory method for an emulator's shared executor state * * 
      * PcodeTraceMemoryAccess sharedData = access.getDataForSharedState();
  *
    * + *
    • *
  • Typically invoked by a factory method for an emulator thread's local executor state * * 
      * PcodeTraceRegisterAccess localData = access.getDataForLocalState(thread, 0);
  *
    * + *
    • *
  • Typically invoked by an auxiliary emulator state piece * - * 
    + * 
    {@code
  * PcodeTracePropertyAccess property = data.getPropertyAccess("MyProperty", String.class);
- * 
    
+ * }
    + * + *
    • * */ public interface PcodeTraceAccess { diff --git a/Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/listing/AbstractBaseDBTraceCodeUnitsView.java b/Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/listing/AbstractBaseDBTraceCodeUnitsView.java index 6aed1fcf75..4cad7ec97c 100644 --- a/Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/listing/AbstractBaseDBTraceCodeUnitsView.java +++ b/Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/listing/AbstractBaseDBTraceCodeUnitsView.java @@ -4,9 +4,9 @@ * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at - * + * * http://www.apache.org/licenses/LICENSE-2.0 - * + * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -19,7 +19,6 @@ import generic.NestedIterator; import ghidra.program.model.address.*; import ghidra.trace.model.*; import ghidra.trace.model.listing.TraceBaseCodeUnitsView; -import ghidra.trace.model.thread.TraceThread; /** * An abstract implementation of a {@link TraceBaseCodeUnitsView} for a specific address space @@ -64,20 +63,6 @@ public abstract class AbstractBaseDBTraceCodeUnitsView *
  • {@link AbstractBaseDBTraceCodeUnitsView} structurally implements - * {@link TraceBaseCodeUnitsView}
    • + * {@link TraceBaseCodeUnitsView} * + * * * *

    * 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 * views: + * *

    * *

    diff --git a/Ghidra/Debug/TaintAnalysis/src/main/java/ghidra/pcode/emu/taint/TaintPcodeThreadExecutor.java b/Ghidra/Debug/TaintAnalysis/src/main/java/ghidra/pcode/emu/taint/TaintPcodeThreadExecutor.java index c3f9cc294c..653460d61b 100644 --- a/Ghidra/Debug/TaintAnalysis/src/main/java/ghidra/pcode/emu/taint/TaintPcodeThreadExecutor.java +++ b/Ghidra/Debug/TaintAnalysis/src/main/java/ghidra/pcode/emu/taint/TaintPcodeThreadExecutor.java @@ -4,9 +4,9 @@ * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at - * + * * http://www.apache.org/licenses/LICENSE-2.0 - * + * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -19,8 +19,8 @@ import org.apache.commons.lang3.tuple.Pair; import ghidra.pcode.emu.DefaultPcodeThread; import ghidra.pcode.emu.DefaultPcodeThread.PcodeThreadExecutor; -import ghidra.pcode.exec.PcodeExecutor; -import ghidra.pcode.exec.PcodeFrame; +import ghidra.pcode.exec.*; +import ghidra.pcode.exec.PcodeArithmetic.Purpose; import ghidra.program.model.pcode.PcodeOp; import ghidra.taint.model.TaintVec; import ghidra.util.Msg; @@ -52,9 +52,8 @@ public class TaintPcodeThreadExecutor extends PcodeThreadExecutor getPartsFactory() { diff --git a/Ghidra/Debug/TaintAnalysis/src/main/java/ghidra/pcode/emu/taint/plain/TaintPcodeExecutorStatePiece.java b/Ghidra/Debug/TaintAnalysis/src/main/java/ghidra/pcode/emu/taint/plain/TaintPcodeExecutorStatePiece.java index 89824771f0..228da37bba 100644 --- a/Ghidra/Debug/TaintAnalysis/src/main/java/ghidra/pcode/emu/taint/plain/TaintPcodeExecutorStatePiece.java +++ b/Ghidra/Debug/TaintAnalysis/src/main/java/ghidra/pcode/emu/taint/plain/TaintPcodeExecutorStatePiece.java @@ -4,9 +4,9 @@ * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at - * + * * http://www.apache.org/licenses/LICENSE-2.0 - * + * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -39,8 +39,8 @@ import ghidra.program.model.lang.Language; * 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 * {@link PairedPcodeExecutorState}. When implementing your flavor of - * {@link PairedPcodeExecutorState#getVar(AddressSpace, Pair, int, boolean)}, still consider that - * you could benefit from the concrete element of the offset pair passed in. + * {@link PairedPcodeExecutorState#getVar(AddressSpace, Pair, int, boolean, Reason)}, still consider + * that you could benefit from the concrete element of the offset pair passed in. */ public class TaintPcodeExecutorStatePiece extends AbstractTaintPcodeExecutorStatePiece { /** diff --git a/Ghidra/Debug/TaintAnalysis/src/main/java/ghidra/pcode/emu/taint/trace/TaintTracePcodeExecutorStatePiece.java b/Ghidra/Debug/TaintAnalysis/src/main/java/ghidra/pcode/emu/taint/trace/TaintTracePcodeExecutorStatePiece.java index 44c126d26a..8ac03935c9 100644 --- a/Ghidra/Debug/TaintAnalysis/src/main/java/ghidra/pcode/emu/taint/trace/TaintTracePcodeExecutorStatePiece.java +++ b/Ghidra/Debug/TaintAnalysis/src/main/java/ghidra/pcode/emu/taint/trace/TaintTracePcodeExecutorStatePiece.java @@ -4,9 +4,9 @@ * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at - * + * * http://www.apache.org/licenses/LICENSE-2.0 - * + * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -29,7 +29,7 @@ import ghidra.trace.model.property.TracePropertyMapSpace; * The trace-integrated state piece for holding taint marks * *

    - * 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. */ public class TaintTracePcodeExecutorStatePiece diff --git a/Ghidra/Debug/TaintAnalysis/src/main/java/ghidra/pcode/emu/taint/trace/TaintTraceSpace.java b/Ghidra/Debug/TaintAnalysis/src/main/java/ghidra/pcode/emu/taint/trace/TaintTraceSpace.java index 14ac6fea75..3a87b2a840 100644 --- a/Ghidra/Debug/TaintAnalysis/src/main/java/ghidra/pcode/emu/taint/trace/TaintTraceSpace.java +++ b/Ghidra/Debug/TaintAnalysis/src/main/java/ghidra/pcode/emu/taint/trace/TaintTraceSpace.java @@ -37,8 +37,7 @@ public class TaintTraceSpace extends TaintSpace { * Create the space * * @param space the address space - * @param backing if present, the backing object - * @param snap the source snap + * @param property the trace property backing this space */ public TaintTraceSpace(AddressSpace space, PcodeTracePropertyAccess property) { this.space = space; diff --git a/Ghidra/Debug/TaintAnalysis/src/main/java/ghidra/pcode/emu/taint/trace/package-info.java b/Ghidra/Debug/TaintAnalysis/src/main/java/ghidra/pcode/emu/taint/trace/package-info.java index f588b3abcd..990d0bc1a9 100644 --- a/Ghidra/Debug/TaintAnalysis/src/main/java/ghidra/pcode/emu/taint/trace/package-info.java +++ b/Ghidra/Debug/TaintAnalysis/src/main/java/ghidra/pcode/emu/taint/trace/package-info.java @@ -4,9 +4,9 @@ * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at - * + * * http://www.apache.org/licenses/LICENSE-2.0 - * + * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -17,9 +17,9 @@ * The trace-integrated Taint Emulator * *

    - * This package builds on {@link ghidra.pcode.emu.plain} to construct a trace-integrated emulator. - * See that package for remarks about this "working solution." Those state components were factored - * to accommodate the state components introduced by this package. + * This package builds on the emulation framework to construct a trace-integrated emulator. The + * framework's state components were designed to accommodate the state components introduced by this + * package. * *

    * For this package, I recommend a bottom-up approach, since you should already be familiar with the diff --git a/Ghidra/Debug/TaintAnalysis/src/main/java/ghidra/taint/model/package-info.java b/Ghidra/Debug/TaintAnalysis/src/main/java/ghidra/taint/model/package-info.java index c64313fdff..b622281054 100644 --- a/Ghidra/Debug/TaintAnalysis/src/main/java/ghidra/taint/model/package-info.java +++ b/Ghidra/Debug/TaintAnalysis/src/main/java/ghidra/taint/model/package-info.java @@ -4,9 +4,9 @@ * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at - * + * * http://www.apache.org/licenses/LICENSE-2.0 - * + * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -17,12 +17,13 @@ * The Taint domain package * *

    - * This package implements the domain of taint analysis. {@link TaintVec} models an array of bytes, - * each having a {@link TaintSet}. A {@link TaintSet} is in turn made of several {@link TaintMarks}. - * Each mark is a symbol with optional tags. We use the tags as a means of handling indirection, so - * that we don't have to decide up front whether tainted 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. + * This package implements the domain of taint analysis. {@link ghidra.taint.model.TaintVec} models + * an array of bytes, each having a {@link ghidra.taint.model.TaintSet}. A + * {@link ghidra.taint.model.TaintSet} is in turn made of several + * {@link ghidra.taint.model.TaintMark}s. Each mark is a symbol with optional tags. We use the tags + * as a means of handling indirection, so that we don't have to decide up front whether tainted + * 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. * *

    * To facilitate storage and presentation of taint, we will need to implement some @@ -30,7 +31,8 @@ * parse method for sets and marks. * *

    - * We recommend you read the documentation and source from the bottom up: {@link TaintMark}, - * {@link TaintSet}, {@link TaintVec}. + * We recommend you read the documentation and source from the bottom up: + * {@link ghidra.taint.model.TaintMark}, {@link ghidra.taint.model.TaintSet}, + * {@link ghidra.taint.model.TaintVec}. */ package ghidra.taint.model;