External Models

External Models

The analyzer supports external model files that define API behavior without hardcoding library-specific rules. Two types of models are available:

---

Resource Lifetime Model (--resource-model=<path>)

Defines acquire/release pairs for resource lifecycle analysis. Used by the ResourceLifetime.* diagnostic family.

Format

acquire_out <function-pattern> <out-arg-index> <resource-kind>
acquire_ret <function-pattern> <resource-kind>
release_arg <function-pattern> <arg-index> <resource-kind>

Directive	Description
acquire_out	Function writes a new resource handle to an out-parameter at <out-arg-index>
acquire_ret	Function returns a new resource handle
release_arg	Function releases the resource passed at <arg-index>

<function-pattern> supports exact names and glob patterns (*, ?, [...]). Matching is applied to both symbol names and demangled names.

<resource-kind> is a user-defined string (e.g., HeapAlloc, VkBuffer) used to pair acquires with releases.

Example Model

# C heap allocation
acquire_ret malloc HeapAlloc
release_arg free 0 HeapAlloc

# C++ heap allocation (demangled names contain spaces, use glob)
acquire_ret operator*new* CppHeap
release_arg operator*delete* 0 CppHeap

# Custom API
acquire_out acquire_handle 0 GenericHandle
release_arg release_handle 0 GenericHandle

# Vulkan
acquire_out vkCreateBuffer 3 VkBuffer
release_arg vkDestroyBuffer 1 VkBuffer

Bundled Model

The project includes a comprehensive model at models/resource-lifetime/generic.txt covering:

• C malloc/free
• C++ new/delete
• 20+ Vulkan resource types (Instance, Device, Buffer, Image, Pipeline, etc.)

Usage

# Use bundled model
./build/stack_usage_analyzer main.c \
  --resource-model=models/resource-lifetime/generic.txt \
  --warnings-only

# Cross-TU analysis (auto-enabled with 2+ input files)
./build/stack_usage_analyzer a.c b.c \
  --resource-model=models/resource-lifetime/generic.txt \
  --resource-summary-cache-memory-only

Cross-TU Summaries

When analyzing multiple files with a resource model, the analyzer builds cross-TU summaries to propagate ownership effects across translation units. This uses a fixed-point iteration algorithm (max 12 iterations).

Options:

• --resource-cross-tu (default: on) -- enable cross-TU propagation
• --no-resource-cross-tu -- force local-only analysis
• --resource-summary-cache-dir=<path> -- filesystem cache for summaries (default: .cache/resource-lifetime)
• --resource-summary-cache-memory-only -- no filesystem writes, in-process cache only

---

Stack Escape Model (--escape-model=<path>)

Defines which function arguments are consumed synchronously (not captured). Suppresses false positive stack pointer escape warnings for APIs that use pointer arguments immediately.

Format

noescape_arg <function-pattern> <arg-index>

<function-pattern> supports exact names and glob patterns.

Example Model

# Vulkan descriptor updates consume pointer arrays immediately
noescape_arg vkUpdateDescriptorSets 2
noescape_arg vkUpdateDescriptorSets 4

Resolution Order

The analyzer uses this resolution order for escape analysis:

1. LLVM attributes: nocapture, byval, byref on call-site
2. Inter-procedural summary: for analyzed function definitions
3. External escape model: noescape_arg rules
4. Opaque external call: no strong escape diagnostic emitted

Bundled Model

Available at models/stack-escape/generic.txt with Vulkan-specific suppressions.

Usage

./build/stack_usage_analyzer main.c \
  --escape-model=models/stack-escape/generic.txt

---

Writing Your Own Models

Tips

1. Start with the bundled models and extend them
2. Use glob patterns for C++ overloaded functions: operator*new*
3. Resource kinds must match between acquire_* and release_arg directives
4. Lines starting with # are comments
5. Empty lines are ignored
6. Arg indices are 0-based

Testing Models

For regression tests, models can be specified per-file with a source comment:

// resource-model: models/resource-lifetime/generic.txt
// escape-model: models/stack-escape/generic.txt