Package ghidra.pcode.emu.sys

Interface EmuSyscallLibrary<T>

Type Parameters:
T - the type of data processed by the system calls, typically byte[]
All Superinterfaces:
PcodeUseropLibrary<T>
All Known Implementing Classes:
AbstractEmuLinuxSyscallUseropLibrary, AbstractEmuUnixSyscallUseropLibrary, AnnotatedEmuSyscallUseropLibrary, EmuLinuxAmd64SyscallUseropLibrary, EmuLinuxX86SyscallUseropLibrary
public interface EmuSyscallLibrary<T> extends PcodeUseropLibrary<T>
A library of system calls

A system call library is a collection of p-code executable routines, invoked by a system call dispatcher. That dispatcher is represented by syscall(PcodeExecutor, PcodeUseropLibrary), and is exported as a sleigh userop. If this interface is "mixed in" with AnnotatedPcodeUseropLibrary, that userop is automatically included in the userop library. The simplest means of implementing a syscall library is probably via AnnotatedEmuSyscallUseropLibrary. It implements this interface and extends AnnotatedPcodeUseropLibrary. In addition, it provides its own annotation system for exporting userops as system calls.

  • Field Details

  • Method Details

    • loadSyscallNumberMap

      static Map<Long,String> loadSyscallNumberMap(String dataFileName) throws IOException
      Derive a syscall number to name map from the specification in a given file.
      Parameters:
      dataFileName - the file name to be found in a modules data directory
      Returns:
      the map
      Throws:
      IOException - if the file could not be read

    • loadSyscallFunctionMap

      static Map<Long,Function> loadSyscallFunctionMap(Program program)
      Scrape functions from the given program's "syscall" space.
      Parameters:
      program - the program
      Returns:
      a map of syscall number to function

    • loadSyscallNumberMap

      static Map<Long,String> loadSyscallNumberMap(Program program)
      Derive a syscall number to name map by scraping functions in the program's "syscall" space.
      Parameters:
      program - the program, likely analyzed for system calls already
      Returns:
      the map

    • loadSyscallConventionMap

      static Map<Long,PrototypeModel> loadSyscallConventionMap(Program program)
      Derive a syscall number to calling convention map by scraping functions in the program's "syscall" space.
      Parameters:
      program -
      Returns:

    • getSyscallUserop

      default PcodeUseropLibrary.PcodeUseropDefinition<T> getSyscallUserop()
      In case this is not an AnnotatedEmuSyscallUseropLibrary or AnnotatedPcodeUseropLibrary, get the definition of the "syscall" userop for inclusion in the PcodeUseropLibrary.

      Implementors may wish to override this to use a pre-constructed definition. That definition can be easily constructed using EmuSyscallLibrary.SyscallPcodeUseropDefinition.

      Returns:
      the syscall userop definition

    • readSyscallNumber

      long readSyscallNumber(PcodeExecutorState<T> state, PcodeExecutorStatePiece.Reason reason)
      Retrieve the desired system call number according to the emulated system's conventions

      TODO: This should go away in favor of some specification stored in the emulated program database. Until then, we require system-specific implementations.

      Parameters:
      state - the executor's state
      reason - the reason for reading state, probably PcodeExecutorStatePiece.Reason.EXECUTE_READ, but should be taken from the executor
      Returns:
      the system call number

    • handleError

      boolean handleError(PcodeExecutor<T> executor, PcodeExecutionException err)
      Try to handle an error, usually by returning it to the user program

      If the particular error was not expected, it is best practice to return false, causing the emulator to interrupt. Otherwise, some state is set in the machine that, by convention, communicates the error back to the user program.

      Parameters:
      executor - the executor for the thread that caused the error
      err - the error
      Returns:
      true if execution can continue uninterrupted

    • syscall

      default void syscall(PcodeExecutor<T> executor, PcodeUseropLibrary<T> library)
      The entry point for executing a system call on the given executor

      The executor's state must already be prepared according to the relevant system calling conventions. This will determine the system call number, according to readSyscallNumber(PcodeExecutorState, Reason), retrieve the relevant system call definition, and invoke it.

      Parameters:
      executor - the executor
      library - the library

    • getSyscalls

      Map<Long,EmuSyscallLibrary.EmuSyscallDefinition<T>> getSyscalls()
      Get the map of syscalls by number

      Note this method will be invoked for every emulated syscall, so it should be a simple accessor. Any computations needed to create the map should be done ahead of time.

      Returns:
      the system call map