Optimization Tools

This section documents the optimization-related command-line tools under tools/optimization/.

The front ends in this directory cover three areas:

  • lotus-opt-ipo drives inter-procedural optimization passes in lib/Optimization/IPO/ via tools/optimization/lotus-opt-ipo.cpp

  • lotus-opt-prefetch drives software prefetching in lib/Optimization/Prefetch/ via tools/optimization/lotus-opt-prefetch.cpp

  • lotus-opt-purity drives function purity inference in lib/Analysis/Purity/ via tools/optimization/lotus-opt-purity.cpp

Other optimization libraries, such as Scalar/, PassOrdering/, and PartialEvaluation/, exist in the source tree but are not documented here as standalone tools because they do not expose separate front-end binaries.

Location: tools/optimization/ Experimental frontends: tools/optimization/lotus-opt-lif.cpp (source retained; target disabled in CMake)

lotus-opt-purity — Purity Inference Driver

Purity inference tool that classifies LLVM functions into one of four purity levels using a MemorySSA-based pipeline (SeaDsa/ShadowMem):

  • Const (readnone) — function does not access memory at all

  • Pure (readonly) — function only reads memory, no writes

  • Impure — function writes to memory

  • Unknown — could not be determined

Source: tools/optimization/lotus-opt-purity.cpp. See lib/Analysis/Purity/ for the underlying analysis framework.

Key options:

-o <file>

Output bitcode with optional applied attributes.

-S

Emit assembly instead of bitcode.

--purity-summary-file <file>

External JSON summary store (load + save back).

--report-json <file>

Write purity report as JSON.

--apply-attrs

Materialize readnone/readonly LLVM attributes on function declarations.

--include-suggested

Use suggested (non-validated) external summaries.

--invalidate-summary <name>

Reject a summary and recompute dependents.

--disable-memoryssa-prep

Skip the SeaDsa/ShadowMem pipeline.

--purity-log

Verbose diagnostics to stderr.

--sea-dsa=<mode>

SeaDsa mode (defaults to ci for purity analysis).

Usage examples:

# Basic purity analysis, output bitcode with attributes
lotus-opt-purity input.bc -o output.bc --apply-attrs

# Generate JSON report
lotus-opt-purity input.ll -S --report-json purity.json

# Use external summary store with validation
lotus-opt-purity input.bc -o output.bc \
  --purity-summary-file summaries.json --apply-attrs