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`, `TaintFileReadsLinuxAmd64SyscallLibrary`

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.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static interface`
  `EmuSyscallLibrary.EmuSyscallDefinition<T>`
  The definition of a system call
  `static final class`
  `EmuSyscallLibrary.SyscallPcodeUseropDefinition<T>`
  The `syscall(PcodeExecutor, PcodeUseropLibrary)` method wrapped as a userop definition

  ## Nested classes/interfaces inherited from interface ghidra.pcode.exec.PcodeUseropLibrary

  `PcodeUseropLibrary.EmptyPcodeUseropLibrary, PcodeUseropLibrary.PcodeUseropDefinition<T>`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `SYSCALL_CONVENTION_NAME`
  `static final String`
  `SYSCALL_SPACE_NAME`

  ### Fields inherited from interface ghidra.pcode.exec.PcodeUseropLibrary

  `NIL`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Map<Long,EmuSyscallLibrary.EmuSyscallDefinition<T>>`
  `getSyscalls()`
  Get the map of syscalls by number
  `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`.
  `boolean`
  `handleError(PcodeExecutor<T> executor, PcodeExecutionException err)`
  Try to handle an error, usually by returning it to the user program
  `static Map<Long,PrototypeModel>`
  `loadSyscallConventionMap(Program program)`
  Derive a syscall number to calling convention map by scraping functions in the program's "syscall" space.
  `static Map<Long,Function>`
  `loadSyscallFunctionMap(Program program)`
  Scrape functions from the given program's "syscall" space.
  `static Map<Long,String>`
  `loadSyscallNumberMap(Program program)`
  Derive a syscall number to name map by scraping functions in the program's "syscall" space.
  `static Map<Long,String>`
  `loadSyscallNumberMap(String dataFileName)`
  Derive a syscall number to name map from the specification in a given file.
  `long`
  `readSyscallNumber(PcodeExecutorState<T> state, PcodeExecutorStatePiece.Reason reason)`
  Retrieve the desired system call number according to the emulated system's conventions
  `default void`
  `syscall(PcodeExecutor<T> executor, PcodeUseropLibrary<T> library)`
  The entry point for executing a system call on the given executor

  ### Methods inherited from interface ghidra.pcode.exec.PcodeUseropLibrary

  `compose, getSymbols, getUserops`

- ## Field Details

  - ### SYSCALL_SPACE_NAME

    static final String SYSCALL_SPACE_NAME
    See Also:
      - Constant Field Values

  - ### SYSCALL_CONVENTION_NAME

    static final String SYSCALL_CONVENTION_NAME
    See Also:
      - Constant Field Values

- ## 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` - the program whose "syscall" space to scrape
    Returns:
      the map of syscall number to calling convention

  - ### 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