Add a disassembly command to CLI

* bdx/cli.py (search): Improve help message.
(disass): New command.
* bdx/index.py (SearchResult.dynamic_fields): Add `endaddress' field.
* README.md: Mention new feature.

Author: mkcms

README.md

@@ -10,6 +10,7 @@ Features:
 - Parallel, incremental indexing using sharded Xapian database
 - Indexes cross-references by analyzing ELF relocations
 - Query the database with a simple query language and custom output formats
+- Disassemble symbols matching a query
 - Generate symbol reference graphs in DOT format
 
 ## Installation ##
@@ -74,26 +75,36 @@ Available options:
   available, to find the source file for a compiled file, if it can't be found
   in any other way.
 
-### Graph generation ###
+### Disassembling ###
 
-Generate an SVG image showing at most 20 routes from symbol `main` in
-`main.o` to all symbols in section `.text` in files matching wildcard
-`Algorithms_*`:
+After a directory is indexed, you can disassemble symbols matching a search
+query.
 
-    bdx graph 'main path:main.o' 'section:".text" AND path:Algorithms*' -n 20 | dot -Tsvg > graph.svg
+You can set the command to disassemble with the `-D`, `--disassembler` option,
+which can contain `{}` placeholders for replacement.
 
-Example graphs: ![ASTAR](./examples/astar.svg) ![BFS](./examples/bfs.svg) ![DFS](./examples/dfs.svg)
+```
+$ bdx disass tree node defp source:./gcc/cp/parser* section:.text
 
-By default this generates paths by using the ASTAR algorithm, the `--algorithm
-BFS` or `--algorithm DFS` options will use
-breadth-first-search/depth-first-search algorithms which can generate different
-graphs and can be slower/faster depending on the index and the queries
-provided.
+/src/gcc-12/build/gcc/cp/parser.o:     file format elf64-x86-64
+
+
+Disassembly of section .text:
+
+000000000000a1d0 <defparse_location(tree_node*)>:
+    a1d0:	48 8b 47 08          	mov    0x8(%rdi),%rax
+    a1d4:	48 8b 10             	mov    (%rax),%rdx
+    a1d7:	48 8b 40 08          	mov    0x8(%rax),%rax
+    a1db:	8b 7a 04             	mov    0x4(%rdx),%edi
+    a1de:	8b 50 04             	mov    0x4(%rax),%edx
+    a1e1:	89 fe                	mov    %edi,%esi
+    a1e3:	e9 00 00 00 00       	jmp    a1e8 <defparse_location(tree_node*)+0x18>
+```
 
 ### Searching ###
 
-`bdx search` command accepts a query string.  A simple query language is
-recognized.
+`bdx search` and other commands accepts a query string.  A simple query
+language is recognized.
 
 ```
 $ bdx search -n 5 tree
@@ -183,6 +194,22 @@ $ bdx search -n 5 -f '0x{address:0>10x}|{section:<10}|{type:8}|{demangled}' tree
         bdx search section:.rodata AND size:1000..
 
 
+### Graph generation ###
+
+Generate an SVG image showing at most 20 routes from symbol `main` in
+`main.o` to all symbols in section `.text` in files matching wildcard
+`Algorithms_*`:
+
+    bdx graph 'main path:main.o' 'section:".text" AND path:Algorithms*' -n 20 | dot -Tsvg > graph.svg
+
+Example graphs: ![ASTAR](./examples/astar.svg) ![BFS](./examples/bfs.svg) ![DFS](./examples/dfs.svg)
+
+By default this generates paths by using the ASTAR algorithm, the `--algorithm
+BFS` or `--algorithm DFS` options will use
+breadth-first-search/depth-first-search algorithms which can generate different
+graphs and can be slower/faster depending on the index and the queries
+provided.
+
 ## License ##
 
 ```

bdx/cli.py

@@ -2,6 +2,7 @@
 
 import json
 import os
+import subprocess
 import sys
 import time
 from functools import wraps
@@ -14,7 +15,7 @@
 from click.types import BoolParamType, IntRange
 
 import bdx
-from bdx import debug, error, info, log, make_progress_bar
+from bdx import debug, error, info, log, make_progress_bar, trace
 # fmt: off
 from bdx.binary import BinaryDirectory, find_compilation_database
 from bdx.index import (IndexingOptions, SymbolIndex, index_binary_directory,
@@ -311,7 +312,10 @@ def convert(self, value, param, ctx):
 @click.option(
     "-f",
     "--format",
-    help="Output format (json, sexp, or Python string format)",
+    help=(
+        "Output format (json, sexp, or Python string format). "
+        "'{}'-placeholders are replaced with symbol fields."
+    ),
     type=SearchOutputFormatParamType(),
     nargs=1,
     default=None,
@@ -357,6 +361,69 @@ def search(_directory, index_path, query, num, format):
                 exit(1)
 
 
+@cli.command()
+@_common_options(index_must_exist=True)
+@click.argument(
+    "query",
+    nargs=-1,
+)
+@click.option(
+    "-n",
+    "--num",
+    help="Limit the number of results",
+    type=click.IntRange(1),
+    metavar="LIMIT",
+    default=None,
+)
+@click.option(
+    "-D",
+    "--disassembler",
+    help=(
+        "The command to run to disassemble a symbol. "
+        "'{}'-placeholders are replaced with search keys."
+    ),
+    nargs=1,
+    default=(
+        "objdump -dC "
+        "'{path}' "
+        "--section '{section}' "
+        "--start-address 0x{address:x} --stop-address 0x{endaddress:x}"
+    ),
+)
+def disass(_directory, index_path, query, num, disassembler):
+    """Search binary directory for symbols."""
+    results = search_index(
+        index_path=index_path, query=" ".join(query), limit=num
+    )
+
+    while True:
+        try:
+            res = next(results)
+        except QueryParser.Error as e:
+            error(f"Invalid query: {str(e)}")
+            exit(1)
+        except StopIteration:
+            break
+
+        data = res.asdict()
+        data.update(res.dynamic_fields())
+
+        try:
+            cmd = disassembler.format(**data)
+        except (KeyError, ValueError, TypeError) as e:
+            error(
+                "Invalid format: {} in '{}'\nAvailable keys: {}",
+                str(e),
+                disassembler,
+                list(data.keys()),
+            )
+            exit(1)
+
+        trace("Symbol: {}", res)
+        debug("Running command: {}", cmd)
+        subprocess.check_call(cmd, shell=True)
+
+
 @cli.command()
 @_common_options(index_must_exist=True)
 def files(_directory, index_path):

bdx/index.py

@@ -1093,6 +1093,7 @@ def dynamic_fields(self) -> dict[str, Any]:
         """Return useful additional fields that are set dynamically."""
         return {
             "basename": self.symbol.path.name,
+            "endaddress": self.symbol.address + self.symbol.size,
         }