================ @@ -0,0 +1,165 @@ +# A bytecode for (LLDB) data formatters + +## Background + +LLDB provides very rich customization options to display data types (see https://lldb.llvm.org/use/variable.html ). To use custom data formatters, developers typically need to edit the global `~/.lldbinit` file to make sure they are found and loaded. An example for this workflow is the `llvm/utils/lldbDataFormatters.py` script. Because of the manual configuration that is involved, this workflow doesn't scale very well. What would be nice is if developers or library authors could ship ship data formatters with their code and LLDB automatically finds them. + +In Swift we added the `DebugDescription` macro (see https://www.swift.org/blog/announcing-swift-6/#debugging ) that translates Swift string interpolation into LLDB summary strings, and puts them into a `.lldbsummaries` section, where LLDB can find them. This works well for simple summaries, but doesn't scale to synthetic child providers or summaries that need to perform some kind of conditional logic or computation. The logical next step would be to store full Python formatters instead of summary strings, but Python code is larger and more importantly it is potentially dangerous to just load an execute untrusted Python code in LLDB. + +This document describes a minimal bytecode tailored to running LLDB formatters. It defines a human-readable assembler representation for the language, an efficient binary encoding, a virtual machine for evaluating it, and format for embedding formatters into binary containers. + +### Goals + +Provide an efficient and secure encoding for data formatters that can be used as a compilation target from user-friendly representations (such as DIL, Swift DebugDescription, or NatVis). + +### Non-goals + +While humans could write the assembler syntax, making it user-friendly is not a goal. + +## Design of the virtual machine + +The LLDB formatter virtual machine uses a stack-based bytecode, comparable with DWARF expressions, but with higher-level data types and functions. + +The virtual machine has two stacks, a data and a control stack. The control stack is kept separate to make it easier to reason about the security aspects of the VM. + +### Data types +These data types are "host" data types, in LLDB parlance. +- _String_ (UTF-8) +- _Int_ (64 bit) +- _UInt_ (64 bit) +- _Object_ (Basically an `SBValue`) +- _Type_ (Basically an `SBType`) +- _Selector_ (One of the predefine functions) + +_Object_ and _Type_ are opaque, they can only be used as a parameters of `call`. + +## Instruction set + +### Stack operations + +These manipulate the data stack directly. + +- `dup (x -> x x)` +- `drop (x y -> x)` +- `pick (x ... UInt -> x ... x)` +- `over (x y -> y)` ---------------- kastiglione wrote:
```suggestion - `over (x y -> x y x)` ``` https://github.com/llvm/llvm-project/pull/113398 _______________________________________________ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
