pub struct Evaluation<R: Reader, S: EvaluationStorage<R> = StoreOnHeap> { /* private fields */ }
Expand description

A DWARF expression evaluator.

Usage

A DWARF expression may require additional data to produce a final result, such as the value of a register or a memory location. Once initial setup is complete (i.e. set_initial_value(), set_object_address()) the consumer calls the evaluate() method. That returns an EvaluationResult, which is either EvaluationResult::Complete or a value indicating what data is needed to resume the Evaluation. The consumer is responsible for producing that data and resuming the computation with the correct method, as documented for EvaluationResult. Only once an EvaluationResult::Complete is returned can the consumer call result().

This design allows the consumer of Evaluation to decide how and when to produce the required data and resume the computation. The Evaluation can be driven synchronously (as shown below) or by some asynchronous mechanism such as futures.

Examples

use gimli::{EndianSlice, Evaluation, EvaluationResult, Format, LittleEndian, Value};

let mut eval = Evaluation::new(bytecode, encoding);
let mut result = eval.evaluate().unwrap();
while result != EvaluationResult::Complete {
  match result {
    EvaluationResult::RequiresRegister { register, base_type } => {
      let value = get_register_value(register, base_type);
      result = eval.resume_with_register(value).unwrap();
    },
    EvaluationResult::RequiresFrameBase => {
      let frame_base = get_frame_base();
      result = eval.resume_with_frame_base(frame_base).unwrap();
    },
    _ => unimplemented!(),
  };
}

let result = eval.result();
println!("{:?}", result);

Implementations

Create a new DWARF expression evaluator.

The new evaluator is created without an initial value, without an object address, and without a maximum number of iterations.

Get the result of this Evaluation.

Panics

Panics if this Evaluation has not been driven to completion.

Create a new DWARF expression evaluator.

The new evaluator is created without an initial value, without an object address, and without a maximum number of iterations.

Set an initial value to be pushed on the DWARF expression evaluator’s stack. This can be used in cases like DW_AT_vtable_elem_location, which require a value on the stack before evaluation commences. If no initial value is set, and the expression uses an opcode requiring the initial value, then evaluation will fail with an error.

Panics

Panics if set_initial_value() has already been called, or if evaluate() has already been called.

Set the enclosing object’s address, as used by DW_OP_push_object_address. If no object address is set, and the expression uses an opcode requiring the object address, then evaluation will fail with an error.

Set the maximum number of iterations to be allowed by the expression evaluator.

An iteration corresponds approximately to the evaluation of a single operation in an expression (“approximately” because the implementation may allow two such operations in some cases). The default is not to have a maximum; once set, it’s not possible to go back to this default state. This value can be set to avoid denial of service attacks by bad DWARF bytecode.

Get the result of this Evaluation.

Panics

Panics if this Evaluation has not been driven to completion.

Evaluate a DWARF expression. This method should only ever be called once. If the returned EvaluationResult is not EvaluationResult::Complete, the caller should provide the required value and resume the evaluation by calling the appropriate resume_with method on Evaluation.

Resume the Evaluation with the provided memory value. This will apply the provided memory value to the evaluation and continue evaluating opcodes until the evaluation is completed, reaches an error, or needs more information again.

Panics

Panics if this Evaluation did not previously stop with EvaluationResult::RequiresMemory.

Resume the Evaluation with the provided register value. This will apply the provided register value to the evaluation and continue evaluating opcodes until the evaluation is completed, reaches an error, or needs more information again.

Panics

Panics if this Evaluation did not previously stop with EvaluationResult::RequiresRegister.

Resume the Evaluation with the provided frame_base. This will apply the provided frame base value to the evaluation and continue evaluating opcodes until the evaluation is completed, reaches an error, or needs more information again.

Panics

Panics if this Evaluation did not previously stop with EvaluationResult::RequiresFrameBase.

Resume the Evaluation with the provided value. This will apply the provided TLS value to the evaluation and continue evaluating opcodes until the evaluation is completed, reaches an error, or needs more information again.

Panics

Panics if this Evaluation did not previously stop with EvaluationResult::RequiresTls.

Resume the Evaluation with the provided cfa. This will apply the provided CFA value to the evaluation and continue evaluating opcodes until the evaluation is completed, reaches an error, or needs more information again.

Panics

Panics if this Evaluation did not previously stop with EvaluationResult::RequiresCallFrameCfa.

Resume the Evaluation with the provided bytes. This will continue processing the evaluation with the new expression provided until the evaluation is completed, reaches an error, or needs more information again.

Panics

Panics if this Evaluation did not previously stop with EvaluationResult::RequiresAtLocation.

pub fn resume_with_entry_value(
    &mut self,
    entry_value: Value
) -> Result<EvaluationResult<R>>

Resume the Evaluation with the provided entry_value. This will apply the provided entry value to the evaluation and continue evaluating opcodes until the evaluation is completed, reaches an error, or needs more information again.

Panics

Panics if this Evaluation did not previously stop with EvaluationResult::RequiresEntryValue.

Resume the Evaluation with the provided parameter_value. This will apply the provided parameter value to the evaluation and continue evaluating opcodes until the evaluation is completed, reaches an error, or needs more information again.

Panics

Panics if this Evaluation did not previously stop with EvaluationResult::RequiresParameterRef.

Resume the Evaluation with the provided relocated address. This will use the provided relocated address for the operation that required it, and continue evaluating opcodes until the evaluation is completed, reaches an error, or needs more information again.

Panics

Panics if this Evaluation did not previously stop with EvaluationResult::RequiresRelocatedAddress.

Resume the Evaluation with the provided indexed address. This will use the provided indexed address for the operation that required it, and continue evaluating opcodes until the evaluation is completed, reaches an error, or needs more information again.

Panics

Panics if this Evaluation did not previously stop with EvaluationResult::RequiresIndexedAddress.

Resume the Evaluation with the provided base_type. This will use the provided base type for the operation that required it, and continue evaluating opcodes until the evaluation is completed, reaches an error, or needs more information again.

Panics

Panics if this Evaluation did not previously stop with EvaluationResult::RequiresBaseType.

Trait Implementations

Formats the value using the given formatter. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Performs the conversion.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.