Interface INativeCodeUnit<InsnType extends IInstruction>

All Superinterfaces:
IAddressableUnit, ICodeUnit, IEventSource, IInteractiveUnit, IMethodManager, INativeContext, IUnit, IUnitCreator, IUserDataSupport

@Ser public interface INativeCodeUnit<InsnType extends IInstruction> extends ICodeUnit, IMethodManager, INativeContext
Specialized code unit that manages a native code processor and uses a virtual memory.

Code units own and work closely with the following objects:

Note: if a debugger is attached, a temporary physical image base can be set.

  • Field Details

  • Method Details

    • getLock

      IUnitLock getLock()
      Retrieve the model lock, used to request a full-access model lock or a partial, read-only, transactional lock. All plugin code accessing the native units and units relying on native units should use those locks to perform operations safely in a concurrent environment.
      Specified by:
      getLock in interface IUnit
      Returns:
    • getItemObject

      INativeItem getItemObject(long id)
      Description copied from interface: IAddressableUnit
      Optionally provide an object associated with the given item. This method may return null, an opaque object, or an object defined by the contract of the implementing object or sub-interface. The SPI of sub-interfaces should specify the item id formats, if any, as well as types and semantics associated with the objects returned by this method.
      Specified by:
      getItemObject in interface IAddressableUnit
      Parameters:
      id - the item id
      Returns:
      an object, whose type is defined by contract, potentially null
    • getAddressFromCodeCoordinates

      String getAddressFromCodeCoordinates(ICodeCoordinates cc, AddressConversionPrecision precision)
    • getStrings

      List<? extends INativeStringItem> getStrings()
      Description copied from interface: ICodeUnit
      Get the list of code strings.
      Specified by:
      getStrings in interface ICodeUnit
      Returns:
    • getStringByIndex

      INativeStringItem getStringByIndex(int index)
      Retrieve a string by index. Careful, this is not the same as getStrings().get(index).
      Parameters:
      index -
      Returns:
    • getPackages

      List<? extends IPackage> getPackages()
      Description copied from interface: ICodeUnit
      Get the list of code packages.
      Specified by:
      getPackages in interface ICodeUnit
      Returns:
    • getTypes

      List<? extends INativeType> getTypes()
      Description copied from interface: ICodeUnit
      Get the list of types.
      Specified by:
      getTypes in interface ICodeUnit
      Returns:
    • getClasses

      List<? extends INativeClassItem> getClasses()
      Description copied from interface: ICodeUnit
      Get the list of classes.
      Specified by:
      getClasses in interface ICodeUnit
      Returns:
    • getFields

      List<INativeFieldItem> getFields()
      Description copied from interface: ICodeUnit
      Get the list of fields.
      Specified by:
      getFields in interface ICodeUnit
      Specified by:
      getFields in interface INativeContext
    • getMethods

      List<? extends INativeMethodItem> getMethods()
      Description copied from interface: ICodeUnit
      Get the list of methods.
      Specified by:
      getMethods in interface ICodeUnit
      Returns:
    • getClass

      INativeClassItem getClass(String fqname)
      Description copied from interface: ICodeUnit
      Convenience method used to retrieve a class by name.
      Specified by:
      getClass in interface ICodeUnit
      Returns:
    • getField

      INativeFieldItem getField(String fqname)
      Description copied from interface: ICodeUnit
      Convenience method used to retrieve a field by name.
      Specified by:
      getField in interface ICodeUnit
      Returns:
    • getMethod

      INativeMethodItem getMethod(String fqname)
      Description copied from interface: ICodeUnit
      Convenience method used to retrieve a method by name.
      Specified by:
      getMethod in interface ICodeUnit
      Returns:
    • getClassByIndex

      INativeClassItem getClassByIndex(int index)
      Get a class by its internal index. Class indices are monotonously increasing, and gaps may exist as classes get destroyed and created. The caller should not assume that getClassByIndex(i)==getClasses().get(i).
      Parameters:
      index - an opaque class index, eg one present in ICodeCoordinates
      Returns:
      a class object or null
    • getFieldByIndex

      INativeFieldItem getFieldByIndex(int index)
      Get a field by its internal index. Field indices are monotonously increasing, and gaps may exist as fields get destroyed and created. The caller should not assume that getFieldByIndex(i)==getFields().get(i).
      Parameters:
      index - an opaque field index, eg one present in ICodeCoordinates
      Returns:
      a field object or null
    • getMethodByIndex

      INativeMethodItem getMethodByIndex(int index)
      Get a method by its internal index. Method indices are monotonously increasing, and gaps may exist as methods get destroyed and created. The caller should not assume that getMethodByIndex(i)==getMethods().get(i).
      Parameters:
      index - an opaque method index, eg one present in ICodeCoordinates
      Returns:
      a method object or null
    • getDisassemblyDocument

      INativeDisassemblyDocument getDisassemblyDocument()
      Description copied from interface: ICodeUnit
      Convenience method to retrieve the text document representing the disassembly of this code unit.

      The caller is responsible for disposing the returned document after usage.

      Specified by:
      getDisassemblyDocument in interface ICodeUnit
      Returns:
    • getCodeObjectContainer

      ICodeObjectUnit getCodeObjectContainer()
      Provide the parent code object container, if there is one. Typically, that would be an ELF, PE-COFF, or Mach-O unit accessible through the generic interface ICodeObjectUnit or any of the derived specialized interfaces.
      Returns:
      a unit or null
    • getInternalMethods

      List<? extends INativeMethodItem> getInternalMethods()
      Retrieve all internal methods. An internal method has an associated data item associated to it.
      Returns:
      a list of internal methods
    • getInternalMethodsLeafFirst

      List<? extends INativeMethodItem> getInternalMethodsLeafFirst()
      Retrieve all internal methods, ordered from the leaves to the roots. An internal method has an associated data item associated to it.
      Returns:
    • getInternalMethodsSizeFirst

      List<? extends INativeMethodItem> getInternalMethodsSizeFirst()
      Retrieve all internal methods, ordered from their ascending byte size. An internal method has an associated data item associated to it.
      Returns:
    • getInternalMethod

      INativeMethodItem getInternalMethod(long memoryAddress)
      Retrieve an internal method by its entry-point address. An internal method has an associated data item associated to it. If multiple methods share the provided entry-point address, the first one is returned.
      Parameters:
      memoryAddress -
      Returns:
      a routine item or null
    • getInternalMethod

      INativeMethodItem getInternalMethod(long memoryAddress, boolean addressIsEntryPoint)
      Retrieve an internal method by address (any address within the method). An internal method has an associated data item associated to it. If multiple methods share the provided address, the one with the lowest entry-point address is returned.
      Parameters:
      memoryAddress -
      addressIsEntryPoint - true if the provided address is the method entry-point; false if the address is just part of the routine. In the latter case, if the address belongs to several routines, any one is returned
      Returns:
      a routine item or null
    • getInternalMethods

      List<? extends INativeMethodItem> getInternalMethods(long memoryAddress)
      Retrieve the internal methods spanning over the provided address
      Parameters:
      memoryAddress -
      Returns:
    • setProcessor

      void setProcessor(IProcessor<InsnType> proc)
      Set the code parser (processor) used by this unit. This method should be called at most once (typically done in the unit's identifier), before processing the unit.
      Parameters:
      proc - mandatory processor
    • setCallingConvention

      void setCallingConvention(ICallingConvention cc)
      Parameters:
      cc -
    • getProcessor

      IProcessor<InsnType> getProcessor()
      Retrieve the machine code parser (pseudo-processor) managed by this unit.
      Specified by:
      getProcessor in interface INativeContext
      Returns:
    • getProcessorName

      String getProcessorName()
      Convenience method used to retrieve the processor's name. The processor value specifies, among other things, the underlying instruction set used by the instructions of this code unit.
      Returns:
      a lower-case string, never null (if the processor is unknown or not set, 'unknown' is retrieved)
    • getEndianness

      Endianness getEndianness()
      Retrieve the endianness. This method is for convenience only; byte ordering can always be retrieved through the IProcessor.
      Returns:
      byte ordering for the target
    • setMemory

      void setMemory(IVirtualMemory mem)
      Optionally set the current optional virtual memory (VM) used by this unit. This method should be called at most once (typically done in the unit's identifier), before processing the unit. It is optional; the VM object set may be overridden during unit processing if it is deemed inappropriate to handle the code object. Therefore, after processing, client code should always retrieve the actual VM object via getMemory().
      Parameters:
      mem - optional VM
    • getMemory

      IVirtualMemory getMemory()
      Retrieve the virtual memory managed used by this unit.
      Specified by:
      getMemory in interface INativeContext
      Returns:
    • setSubsystemType

      void setSubsystemType(SubsystemType subsystemType)
      Set a hint. This method may be called optionally, before process(). The hint may be disregarded.
      Parameters:
      subsystemType -
    • setCompilerType

      void setCompilerType(CompilerType compilerType)
      Set a hint. This method may be called optionally, before process(). The hint may be disregarded.
      Parameters:
      compilerType -
    • setCodeFormatter

      void setCodeFormatter(GenericCodeFormatter<InsnType> codeFormatter)
      Parameters:
      codeFormatter -
    • getCodeFormatter

      GenericCodeFormatter<InsnType> getCodeFormatter()
      Get the helper object used to format instructions into a sink.

      Do not confuse the code formatter with the unit's formatter.

      Returns:
    • getAnalyzerExtension

      INativeCodeAnalyzerExtension<InsnType> getAnalyzerExtension()
      Get the principal code analyzer extension attached to this unit.
      Returns:
    • setAnalyzerExtension

      void setAnalyzerExtension(INativeCodeAnalyzerExtension<InsnType> ext)
      Set the principal code analyzer extension for this unit.
      Parameters:
      ext -
    • getCodeModel

      INativeCodeModel<InsnType> getCodeModel()
      Get the code model.
      Returns:
    • getCodeAnalyzer

      INativeCodeAnalyzer<InsnType> getCodeAnalyzer()
      Get the code analyzer.

      Life-cycle information: this method will return null until the unit is processed.

      Returns:
    • getCodeAnalyzerExtensionsManager

      INativeCodeAnalyzerExtensionsManager<InsnType> getCodeAnalyzerExtensionsManager()
      Retrieve the currently-set analyzer extensions manager. Life-cycle information: this method will return null until the unit is processed.

      Note: third-party code should not use this for now.

      Returns:
    • process

      boolean process()
      Quickly process the unit. Be careful that the IUnit is not analyzed while performInitialAnalysis() was not called.
      Specified by:
      process in interface IUnit
      Returns:
      true if IUnit was processed (may then check isInitialAnalysisDone() to check that unit is fully usable)
    • isInitialAnalysisDone

      boolean isInitialAnalysisDone()
      Determine whether or not an initial analysis pass has been done.
      Returns:
    • performInitialAnalysis

      boolean performInitialAnalysis()
      Perform the initial analysis pass. This method should be called once, after successful unit processing. The initial analysis pass parameters, such as synchronicity, the inclusion of global or advanced analysis, etc. are determined automatically.
      Returns:
    • performInitialAnalysis

      boolean performInitialAnalysis(Boolean blocking)
    • performAnalysis

      boolean performAnalysis(boolean async, Boolean includeAdvancedAnalysis, Runnable onCompletion)
      Start an analysis.
      Parameters:
      async - if true, this method is executed asynchronously and returns immediately; use INativeCodeAnalyzer.isAnalyzing() to determine whether the analysis has completed.
      includeAdvancedAnalysis - if null, use the unit's settings; if non-null, bypass the unit's configuration and force-enable or force-disable the advanced analysis
      onCompletion - optional runnable to be executed on completion (always)
      Returns:
    • isAnalysisCompleted

      boolean isAnalysisCompleted()
      Determine whether a code analysis pass is ongoing.
      Returns:
      false if a code analysis is currently taking place, true otherwise
    • getCanonicalMemoryAddress

      long getCanonicalMemoryAddress(String address)
      Convert a flexible native code unit address to a canonical memory address.

      Unit addresses can be code labels, pseudo labels, string representations of physical addresses, etc.

      Parameters:
      address - an address
      Returns:
      the memory address, or -1 (0xFFFFFFFF_FFFFFFFFL) on failure
    • getCanonicalMemoryAddress

      long getCanonicalMemoryAddress(String address, AddressConversionPrecision precision)
      Convert a flexible native code unit address to a canonical memory address.

      Unit addresses can be code labels, pseudo labels, string representations of physical addresses, etc.

      Parameters:
      address - an address
      precision - use COARSE to bypass early name resolution, and attempt a simple number conversion first (e.g., with coarse address "aabb" will be resolved to 0xAABB before looking if an item is named "aabb"); with FINE (or DEFAULT), item name resolution is attempted first; therefore, for quick and unreliable conversions, use COARSE; else, use the DEFAULT setting
      Returns:
      the memory address, or -1 (0xFFFFFFFF_FFFFFFFFL) on failure
    • getSymbolicStringAddress

      String getSymbolicStringAddress(long address)
      Retrieve the simplest symbol address that corresponds to the given physical address. Same as getSymbolicStringAddress(address, 0).
      Parameters:
      address -
      Returns:
    • getSymbolicStringAddress

      String getSymbolicStringAddress(long address, int sspref)
      Retrieve a symbol address that corresponds to the given physical address.

      Example: if address if at offset 10h inside method foo() (at address 401000h), querying this method with sspref=2 will return a label "foo+10h"; however, querying with sspref=0 would simply return "401010h".

      Parameters:
      address - a memory address
      sspref - resolution type: (in the examples a below, a routine exists at address 0x401000)
      0= will resolve to a standard hex-formatted address, e.g. 0x402000 to 402000h
      1= will first resolve to any existing label, routine address, e.g. 0x401000 to sub_401000 etc.
      2= will first resolve to a routine-based address, e.g. sub_401010 to sub_401000+10h
      Returns:
    • setVirtualImageBase

      void setVirtualImageBase(long virtualImageBase)
      Set preferred image base
      Parameters:
      virtualImageBase -
    • setPhysicalImageBase

      void setPhysicalImageBase(long physicalImageBase)
      Set the real (physical) image base for this piece of code. That address is the real address of the first loaded byte on a target device. The existence of this method implies that at most one physical address can be used at any time. (Typically, debuggers use this method to let code units know of where they are currently mapped, which in turn is used to better render assembly output.) Generally, the physical image address changes across different launches.
      Parameters:
      physicalImageBase - the physical image base of this code unit; the value 0 means that the physical address is unknown
    • getPhysicalImageDelta

      long getPhysicalImageDelta()
      Retrieve the difference between Physical Image base as set by setPhysicalImageBase(long) and Virtual Image Base as retrieved by INativeContext.getVirtualImageBase(). This value should only be used for rendering.
      Returns:
    • getEntryPointAddress

      long getEntryPointAddress()
      Get the address of the entry-point of this unit, if any.
      Returns:
    • getHighLevelEntryPointAddress

      long getHighLevelEntryPointAddress()
      Get the address of the high-level entry-point of this unit, if any.

      The high-level entry-point corresponds to a main() (or similar) routine. It is the routine executed after the compiler-generated initialization code is executed. Note that it might be set as a result of the initial analysis.

      Returns:
      real entry point address, -1L if none
    • getSignatureManager

      NativeSignatureDBManager getSignatureManager()
      Get the global signature manager used by this unit.
      Returns:
    • getTypeManager

      ITypeManager getTypeManager()
      Get the global type manager used by this unit.
      Specified by:
      getTypeManager in interface INativeContext
      Returns:
    • getPackageManager

      IPackageManager getPackageManager()
      Get the package/namespace manager used by this unit.
      Returns:
    • getClassManager

      IClassManager getClassManager()
      Returns:
    • getFieldManager

      IFieldManager getFieldManager()
      Returns:
    • getMethodManager

      IMethodManager getMethodManager()
      Returns:
    • getTypeLibraryService

      TypeLibraryService getTypeLibraryService()
      Get the global type library service.
      Returns:
    • setRoutinePrototype

      boolean setRoutinePrototype(INativeMethodItem routine, String prototypeString)
      Set a routine prototype. This method uses non-standard prototype declarations and should be avoided. Use setRoutineSignature(INativeMethodItem, String, boolean) instead.
      Parameters:
      routine - target routine
      prototypeString - a prototype string having the following style:
       <calling-convention> returnType(paramType1 _)
       <calling-convention> returnType(paramType1, paramType2)
       <calling-convention> returnType(paramType1, paramType2, ...)
                  
      Returns:
      success indicator
    • setRoutineSignature

      boolean setRoutineSignature(INativeMethodItem routine, String signatureString, boolean prototypeOnly)
      Set a routine signature or protytpe.
      Parameters:
      routine - target routine
      signatureString - a C-like signature; some C++ features such as namespaces (::) or templates (<...>) are allowed but disregarded
      prototypeOnly - if true, only the prototype will be applied; method and parameter names, if provided, will not be applied
      Returns:
      success indicator
    • getDataTypeAt

      INativeType getDataTypeAt(long address)
      Get the native type of the data item located at the provided address.
      Parameters:
      address -
      Returns:
    • setDataTypeAt

      boolean setDataTypeAt(long address, INativeType type)
      Convenience method to set the native type of a data item located at the provided address. If no item exists at the provided address, one will be created. Overlapping items may be deleted.

      Note: to create String items, see setStringAt(long, long, StringEncoding, int, int).

      Parameters:
      address -
      type -
      Returns:
      success indicator
    • setDataAt

      boolean setDataAt(long address, INativeType type, String name)
      Create or update a data item at the provided address. Overlapping items may be deleted.

      Note: to create String items, see setStringAt(long, long, StringEncoding, int, int).

      Parameters:
      address - item address
      type - item type
      name - optional name
      Returns:
      success indicator
    • setDataAt

      boolean setDataAt(long address, INativeType type, String name, boolean undefineOverlappingItems)
      Create or update a data item at the provided address.

      Note: to create String items, see setStringAt(long, long, StringEncoding, int, int).

      Parameters:
      address - item address
      type - item type
      name - optional name
      undefineOverlappingItems - if false, the method will fail if existing items overlap with the memory range needed to accommodate a newly-created item
      Returns:
      success indicator
    • setStringAt

      boolean setStringAt(long address, long addressMax, StringEncoding stringType, int minChars, int maxChars)
      Create a string data item. Overlapping items may be deleted.
      Parameters:
      address - mandatory start address
      addressMax - optional maximum (final) address for the string; use -1 for no limit
      stringType - the string type hint; null to let this method determine the best string type heuristically
      minChars - minimum number of characters to be found in the string for it to be considered valid; set to -1 for default (currently: 3)
      maxChars - maximum number of characters (not bytes) to be parsed; set to -1 for default (currently: 100_000)
      Returns:
      success indicator
    • setStringAt

      boolean setStringAt(long address, long addressMax, StringEncoding stringType, int minChars, int maxChars, boolean undefineOverlappingItems)
      Create a string data item.
      Parameters:
      address - mandatory start address
      addressMax - optional maximum (final) address for the string; use -1 for no limit
      stringType - the string type hint; null to let this method determine the best string type heuristically
      minChars - minimum number of characters to be found in the string for it to be considered valid; set to -1 for default (currently: 3)
      maxChars - maximum number of characters (not bytes) to be parsed; set to -1 for default (currently: 100_000)
      undefineOverlappingItems - if false, the method will fail if existing items overlap with the memory range needed to accommodate a newly-created item
      Returns:
      success indicator
    • setCodeAt

      boolean setCodeAt(long address, int procmode, boolean undefineOverlappingItems)
      Parse and create an instruction at the provided address.
      Parameters:
      address - instruction address
      procmode - processor mode (refer to MODE_xxx constants in IProcessor)
      undefineOverlappingItems - if false, the method will fail if existing items overlap with the memory range needed to accommodate a newly-created item
      Returns:
      success indicator
    • setRoutineReferenceAt

      boolean setRoutineReferenceAt(long address, INativeMethodItem routine)
      Create a special data item representing a reference to a method. Those items are similar to function pointer items (pointer to prototypes), except that they refer specifically to routine objects managed by this unit.
      Parameters:
      address -
      routine -
      Returns:
    • setRoutineAt

      boolean setRoutineAt(long address)
      Parse and attempt to create a routine at the provided address. The processor mode used will be the default one, and the analysis will be done forcefully.
      Parameters:
      address - routine start address
      Returns:
      success indicator: if true, a routine was created (or existed) at the provided address
    • setRoutineAt

      boolean setRoutineAt(long address, int procmode)
      Parse and attempt to create a routine at the provided address. The analysis is done forcefully.
      Parameters:
      address - routine start address
      procmode - processor mode
      Returns:
      success indicator: if true, a routine was created (or existed) at the provided address
    • setRoutineAt

      boolean setRoutineAt(long address, int procmode, int permission)
      Parse and attempt to create a routine at the provided address.
      Parameters:
      address - routine start address
      procmode - processor mode
      permission - one of the PERMISSION_xxx constants of INativeCodeAnalyzer (refer to enqueuePointerForAnalysis for details)
      Returns:
      success indicator: if true, a routine was created (or existed) at the provided address
    • getNativeItemAt

      INativeContinuousItem getNativeItemAt(long address)
      Get the item located at the exact address.
      Specified by:
      getNativeItemAt in interface INativeContext
      Parameters:
      address - item start address
      Returns:
    • getNativeItemOver

      INativeContinuousItem getNativeItemOver(long address)
      Get the item spanning over the provided address.
      Specified by:
      getNativeItemOver in interface INativeContext
      Parameters:
      address - an address
      Returns:
    • getNativeItemsOver

      SortedMap<Long,INativeContinuousItem> getNativeItemsOver(long address, int size)
      Retrieve a read-only map of the native items located within the provided memory range.
      Parameters:
      address -
      size -
      Returns:
    • undefineItem

      boolean undefineItem(long address)
      Undefine the memory item starting at the provided address. Careful, this method may have unintended side effects. Example: deleting an instruction item that's part of a routine body will also discard that routine, which in turn may discard other items or references, within this unit or other units.
      Parameters:
      address - item address
      Returns:
      success indicator
    • getCommentManager

      NativeCommentManager getCommentManager()
      Description copied from interface: IInteractiveUnit
      Get the comment manager. This method is optional. When the unit is disposed, this method must return null. The default implementation returns null.
      Specified by:
      getCommentManager in interface ICodeUnit
      Specified by:
      getCommentManager in interface IInteractiveUnit
      Returns:
      a comment manager, or null if the unit does not have one
    • setInlineComment

      boolean setInlineComment(long address, String comment)
      Convenience method used to set the inline comment at the provided virtual address.
      Parameters:
      address - VA
      comment - a comment
      Returns:
      success indicator
    • getInlineComment

      String getInlineComment(long address)
      Convenience method used to retrieve the inline comment at the provided virtual address.
      Parameters:
      address - VA
      Returns:
      a comment or null
    • getDecompiler

      Retrieve or create a decompiler for this unit. If a corresponding gendec plugin is not available with your JEB license, null is returned.
      Returns: