Disassembly

Trigger Intents

Use this skill when user asks for:

• Function/segment/instruction inspection
• Call-site or control-flow analysis from disassembly
• Operand formatting and low-level code structure
• Raw byte/instruction-level evidence

Route to:

• decompiler for AST/pseudocode semantics
• xrefs for relationship-heavy caller/callee workflows
• debugger for patching/breakpoint actions

Do This First (Warm-Start Sequence)

-- 1) Orientation
SELECT * FROM binary;

-- 2) Segment map
SELECT name, printf('0x%X', start_addr) AS start_addr, printf('0x%X', end_addr) AS end_addr, perm
FROM segments
ORDER BY start_addr;

-- 3) Largest functions (triage anchors)
SELECT name, printf('0x%X', addr) AS addr, size
FROM funcs
ORDER BY size DESC
LIMIT 20;

Interpretation guidance:

• Start from executable segments and largest/highly connected functions.
• Use func_addr constraints early when querying instruction-heavy surfaces.

Failure and Recovery

• Slow queries on instructions/heads:
  • Add WHERE func_addr = X or tight EA ranges.
• Missing expected symbol names:
  • Pivot to address-based workflows and enrich via names updates later.
• Ambiguous control-flow behavior:
  • Cross-check with disasm_calls and then escalate to decompiler.

Handoff Patterns

1. disassembly -> xrefs for relation expansion.
2. disassembly -> decompiler for semantic interpretation.
3. disassembly -> debugger for patch/breakpoint execution.

Entity Tables

funcs

All detected functions in the binary with prototype information.

Prototype columns (populated when type info available):

-- 10 largest functions
SELECT name, size FROM funcs ORDER BY size DESC LIMIT 10;

-- Functions starting with "sub_" (auto-named, not analyzed)
SELECT name, printf('0x%X', addr) as addr FROM funcs WHERE name LIKE 'sub_%';

-- Functions returning integers with 3+ arguments
SELECT name, return_type, arg_count FROM funcs
WHERE return_is_integral = 1 AND arg_count >= 3;

-- Functions organized by IDASQL annotation folders
SELECT addr, name, folder_path
FROM funcs
WHERE folder_path LIKE 'idasql/%'
ORDER BY folder_path, name;

Write operations:

-- Create a function
INSERT INTO funcs (addr) VALUES (0x401000);

-- Rename a function
UPDATE funcs SET name = 'my_func' WHERE addr = 0x401000;

-- Move a function into an IDA Function window folder
INSERT INTO dirtree_folders(tree, path) VALUES ('funcs', 'idasql/triage/network');
UPDATE funcs SET folder_path = 'idasql/triage/network' WHERE addr = 0x401000;

-- Move it back to root
UPDATE funcs SET folder_path = NULL WHERE addr = 0x401000;

-- Delete a function
DELETE FROM funcs WHERE addr = 0x401000;

Folder paths are relative / paths. IDASQL rejects ./.., duplicate separators, backslashes, non-empty folder deletes, and folder renames whose destination already exists.

segments

Memory segments. Full CRUD: INSERT a region, DELETE it, and UPDATE start_addr (rebase/move), end_addr (resize), name, class, perm.

-- Find executable segments
SELECT name, printf('0x%X', start_addr) as start FROM segments WHERE perm & 1 = 1;

-- Rename a segment
UPDATE segments SET name = '.mytext' WHERE start_addr = 0x401000;

-- Add a region (e.g. SRAM for a raw firmware image), then rebase it
INSERT INTO segments(start_addr, end_addr, name, class, perm)
  VALUES (0x20000000, 0x20005000, 'SRAM', 'DATA', 6);
UPDATE segments SET start_addr = 0x08000000 WHERE name = '.text';  -- rebase

names

All named locations (functions, labels, data). Supports INSERT, UPDATE, and DELETE.

-- Create/set a name
INSERT INTO names (addr, name) VALUES (0x401000, 'my_symbol');

-- Rename
UPDATE names SET name = 'my_symbol_renamed' WHERE addr = 0x401000;

-- Organize globals/labels into IDA name folders
UPDATE names SET folder_path = 'idasql/names/globals' WHERE name LIKE 'g_%';
UPDATE names SET folder_path = NULL WHERE addr = 0x401000;

entries

Entry points (exports, program entry, tls callbacks, etc.).

Instruction Tables

instructions

instructions is the disassembly table. For scalar disassembly text at a specific EA, use disasm_at(addr[, context]). Use disasm_func() or disasm_range() when you explicitly need a function/range listing. Decoded instructions support DELETE (converts instruction to unexplored bytes) and operand representation updates via operand*_format_spec.

WHERE func_addr = X is the fast path (function-item iterator). Without it, the table scans all code heads.

-- Instruction profile of a function (FAST)
SELECT mnemonic, COUNT(*) as count
FROM instructions WHERE func_addr = 0x401330
GROUP BY mnemonic ORDER BY count DESC;

-- Find all call instructions in a function
SELECT addr, disasm FROM instructions
WHERE func_addr = 0x401000 AND mnemonic = 'call';

-- Apply enum representation to operand 1
UPDATE instructions
SET operand1_format_spec = 'enum:MY_ENUM'
WHERE addr = 0x401020;

-- Apply struct-offset representation to operand 0
-- e.g. makes `[rax+10h]` display as `[rax+command_t.field_name]`
UPDATE instructions
SET operand0_format_spec = 'stroff:command_t'
WHERE addr = 0x140001BE8;

-- Struct-offset with a base delta (subtracted before member resolution)
UPDATE instructions
SET operand0_format_spec = 'stroff:command_t,delta=16'
WHERE addr = 0x140001BE8;

-- Nested member path: separate type names with '/'
UPDATE instructions
SET operand0_format_spec = 'stroff:outer_t/inner_t'
WHERE addr = 0x140001BE8;

-- Clear representation back to plain
UPDATE instructions
SET operand1_format_spec = 'clear'
WHERE addr = 0x401020;

The format-spec is verified after apply: the UPDATE re-reads the operand and fails (as a SQL error) if the resulting repr_kind, type path, or delta don't match what was requested. Read back operandN_repr_kind / operandN_repr_type_name to confirm.

Full operandN_format_spec vocabulary (all disassembly-level, no IDAPython needed):

Combinable modifiers (suffix on any base, or standalone to modify the current representation): ,signed / ,unsigned (toggle negative display) and ,bnot / ,nobnot (toggle bitwise-not display). Example: dec,signed, hex,bnot, or just signed.

-- Number base, character, and sign/bitwise-not modifiers
UPDATE instructions SET operand1_format_spec = 'hex'        WHERE addr = 0x401020;
UPDATE instructions SET operand1_format_spec = 'dec,signed' WHERE addr = 0x401020;
UPDATE instructions SET operand1_format_spec = 'char'       WHERE addr = 0x401020;

-- Offsets (plain and user-defined base)
UPDATE instructions SET operand1_format_spec = 'offset'            WHERE addr = 0x401020;
UPDATE instructions SET operand1_format_spec = 'offset:tbl_start'  WHERE addr = 0x401020;

-- sizeof: an immediate equal to sizeof(STRUCT) renders as `size STRUCT`
UPDATE instructions SET operand1_format_spec = 'sizeof:FILEDEF' WHERE addr = 0x4015EB;

-- Forced operand text
UPDATE instructions SET operand1_format_spec = 'forced:5 shl 3' WHERE addr = 0x401020;

instruction_operands

One row per decoded non-void operand. Use this table for operand type/value details and for joinable replacements of old operand/decode helper functions.

Note (addr vs op_addr): addr is the instruction address; the operand's referenced address is op_addr. If you want the target an operand points at (e.g. a jump/call/data reference), select op_addr — addr identifies the instruction the operand belongs to, not what it references.

SELECT opnum, text, type_name, value
FROM instruction_operands
WHERE addr = 0x401000
ORDER BY opnum;

SELECT i.addr, i.itype, i.mnemonic, o.opnum, o.text, o.type_name, o.value
FROM instructions i
LEFT JOIN instruction_operands o
  ON o.addr = i.addr AND o.func_addr = 0x401000
WHERE i.func_addr = 0x401000
ORDER BY i.addr, o.opnum;

Performance: WHERE addr = X decodes one instruction; WHERE func_addr = X uses O(function_size) iteration. Without one of these constraints, it scans the entire database.

disasm_calls

All call instructions with resolved targets and optional call-site prototype overrides.

-- Functions that call malloc
SELECT DISTINCT (SELECT name FROM funcs WHERE func_addr >= addr AND func_addr < end_addr LIMIT 1) as caller
FROM disasm_calls WHERE callee_name LIKE '%malloc%';

-- Apply/replace a call-site prototype, then clear it
UPDATE disasm_calls
SET callee_type = 'int (__fastcall *)(const char *path)'
WHERE addr = 0x401234;
UPDATE disasm_calls SET callee_type = NULL WHERE addr = 0x401234;

Applying callee_type on a direct call preserves the real callee symbol, so re-decompiling the caller afterward is safe (no microcode INTERR); on an indirect call it types that site. Empty/NULL clears the override.

blocks

Basic blocks within functions. Use func_addr constraint for performance.

-- Blocks in a specific function (FAST - uses constraint pushdown)
SELECT * FROM blocks WHERE func_addr = 0x401000;

-- Functions with most basic blocks
SELECT (SELECT name FROM funcs WHERE func_addr >= addr AND func_addr < end_addr LIMIT 1) as name, COUNT(*) as blocks
FROM blocks GROUP BY func_addr ORDER BY blocks DESC LIMIT 10;

cfg_edges

Control flow graph edges between basic blocks. Always use WHERE func_addr = X (filter_eq pushdown, O(blocks in function)).

-- Get CFG structure
SELECT * FROM cfg_edges WHERE func_addr = 0x401000;

-- Find branch points (conditional blocks)
SELECT from_block, COUNT(*) as succ_count
FROM cfg_edges WHERE func_addr = 0x401000
GROUP BY from_block HAVING succ_count > 1;

-- Find merge points (blocks with multiple predecessors)
SELECT to_block, COUNT(*) as pred_count
FROM cfg_edges WHERE func_addr = 0x401000
GROUP BY to_block HAVING pred_count > 1;

-- Function complexity ranking: combine CFG, loops, and call metrics
SELECT f.name, f.size,
       (SELECT COUNT(*)
        FROM (
            SELECT ce.from_block
            FROM cfg_edges ce
            WHERE ce.func_addr = f.addr
            GROUP BY ce.from_block
            HAVING COUNT(*) > 1
        ) branch_blocks) as branch_sites,
       (SELECT COUNT(*) FROM disasm_loops dl WHERE dl.func_addr = f.addr) as loops,
       (SELECT COUNT(*) FROM disasm_calls dc WHERE dc.func_addr = f.addr) as calls_made
FROM funcs f
WHERE f.size > 32
ORDER BY branch_sites DESC
LIMIT 20;

function_chunks

Cached table with one row per function chunk. Aggregate by func_addr when you need function-level span or density metrics.

SELECT * FROM function_chunks WHERE func_addr = 0x401000;

SQL Functions -- Disassembly

Disassembly Examples

-- Canonical single-EA disassembly (safe for code or data)
SELECT disasm_at(0x401000);

-- Canonical context window (+/- 2 heads)
SELECT disasm_at(0x401000, 2);

-- Full function disassembly (resolves boundaries via get_func)
SELECT disasm_func(addr) FROM funcs WHERE name = '_main';

-- Disassemble a specific address range
SELECT disasm_range(0x401000, 0x401100);

-- Sliding window: next 5 instructions from an address
SELECT disasm(0x401000, 5);

SQL Functions -- Names & Functions

Use table lookups for address and containing-function metadata. Resolve symbol names to integer EAs before using these patterns.

Function count and index lookup are table-driven:

SELECT COUNT(*) AS function_count FROM funcs;
SELECT addr FROM funcs WHERE rowid = 0;

SQL Functions -- Navigation

Use heads ordering for defined-item navigation and SQLite formatting functions for display strings. Address equality/range filters are optimized; ORDER BY addr or ORDER BY addr DESC is consumed for next/previous-item lookups.

SELECT addr
FROM heads
WHERE addr > 0x401000
ORDER BY addr
LIMIT 1;

SELECT addr
FROM heads
WHERE addr < 0x401000
ORDER BY addr DESC
LIMIT 1;

SELECT printf('0x%llx', addr) AS address_hex
FROM heads
LIMIT 10;

Segment lookup is table-driven:

SELECT name
FROM segments
WHERE 0x401000 >= start_addr
  AND 0x401000 < end_addr
LIMIT 1;

SQL Functions -- Item Analysis

Use heads for item classification, size, and raw flags:

SELECT addr, size, type, flags, disasm
FROM heads
WHERE addr = 0x401000;

SQL Functions -- Instruction Details

Use instructions and instruction_operands for decoded instruction facts:

SELECT addr, itype, mnemonic
FROM instructions
WHERE func_addr = 0x401000
LIMIT 10;

SELECT opnum, text, type_code, type_name, value
FROM instruction_operands
WHERE addr = 0x401000
ORDER BY opnum;

SELECT i.addr, i.itype, i.mnemonic, i.size, o.opnum, o.text, o.type_name, o.value
FROM instructions i
LEFT JOIN instruction_operands o
  ON o.addr = i.addr AND o.addr = 0x401000
WHERE i.addr = 0x401000
ORDER BY o.opnum;

SQL Functions -- File Generation

SQL Functions -- Graph Generation

-- Get CFG for a function as DOT format
SELECT gen_cfg_dot(0x401000);

Performance Rules

Key rules:

• funcs is always fast -- no constraint needed.
• instructions without func_addr scans every code head -- use func_addr for per-function queries.
• blocks without func_addr iterates all functions' flowcharts -- always constrain.
• heads is often large. Use addr = X for item facts and address range plus ORDER BY addr [DESC] LIMIT 1 for navigation.

Cost model:

funcs (full scan)            -> O(number of functions), typically ~1000s, fast
instructions WHERE func_addr -> O(function_size / avg_insn_size)
instructions (no constraint) -> O(total_code_heads), potentially 100K+
blocks WHERE func_addr         -> O(block_count_in_func), fast
cfg_edges WHERE func_addr      -> O(block_count_in_func), fast
disasm_calls WHERE func_addr -> O(instructions_in_func), streaming
disasm_calls UPDATE callee_type WHERE addr -> O(1) call-site lookup
heads WHERE addr          -> O(1) IDA head check
heads next/prev LIMIT 1      -> O(distance to next/previous defined head)
instruction_operands addr    -> O(operands in one instruction)
instruction_operands func    -> O(operands in one function)

Additional Resources

• For advanced CTE patterns and instruction lifecycle playbooks: references/disassembly-examples.md
• For additional table schemas (fchunks, heads, bytes, signatures, problems, fixups, etc.): references/disassembly-tables.md

See Also

• decompiler — pseudocode and ctree on the same function; pivot when disassembly is too noisy.
• xrefs — call graph and data references centered on a function or call site.
• data — operand-targeted bytes/strings; bytes table for per-byte reads and bounded windows via WHERE start_addr = X AND n = N composed with hex(blob_concat(value)) for bulk hex.