https://github.com/JDevlieghere updated
https://github.com/llvm/llvm-project/pull/112938
>From ea45421b4c4e7973abf0461bec75988800babe77 Mon Sep 17 00:00:00 2001
From: Jonas Devlieghere <jo...@devlieghere.com>
Date: Fri, 18 Oct 2024 10:18:54 -0700
Subject: [PATCH 1/2] [lldb] Document SymbolFileJSON
I've had multiple request for documentation about the JSON symbol file
format that LLDB supports. This patch documents the structure and
fields, shows a handful of examples and explains how to use it in LLDB.
---
lldb/docs/resources/symbolfilejson.rst | 201 +++++++++++++++++++++++++
1 file changed, 201 insertions(+)
create mode 100644 lldb/docs/resources/symbolfilejson.rst
diff --git a/lldb/docs/resources/symbolfilejson.rst
b/lldb/docs/resources/symbolfilejson.rst
new file mode 100644
index 00000000000000..54f606ce1ffd58
--- /dev/null
+++ b/lldb/docs/resources/symbolfilejson.rst
@@ -0,0 +1,201 @@
+JSON Symbol File Format
+=======================
+
+The JSON symbol file format encodes symbols in a text based, human readable
+format. JSON symbol files can be used to symbolicate programs that miss symbol
+information, for example because they have been stripped.
+
+Format
+------
+
+The symbol file contains of a single JSON object with the following top level
+keys:
+
+* ``triple``
+* ``uuid``
+* ``type``
+* ``sections``
+* ``symbols``
+
+The ``triple``, ``uuid`` and ``type`` form the header and should therefore come
+first. The ``type`` field is optional. The body consists ``sections`` and
+``symbols``, each represented as a JSON array. Both arrays are optional, and
+can be omitted and are allowed to be empty.
+
+triple
+``````
+
+The triple is a string with the triple of the object file it corresponds to.
+The triple follows the same format as used by LLVM:
+``<arch><sub>-<vendor>-<sys>-<env>``.
+
+.. code-block:: JSON
+
+ { "triple": "arm64-apple-darwin22.0.0" }
+
+uuid
+````
+
+The UUID is a string with the textual representation of the UUID of the object
+file it corresponds to. The UUID is represented as outlined in RFC 4122: with
+32 hexadecimal digits, displayed in five groups separated by hyphens, in the
+form 8-4-4-4-12 for a total of 36 characters (32 alphanumeric characters and
+four hyphens).
+
+.. code-block:: JSON
+
+ { "uuid": "2107157B-6D7E-39F6-806D-AECDC15FC533" }
+
+type
+````
+The optional ``type`` field allows you to specify the type of object file the
+JSON file represent. This is often unnecessary, and can be omitted, in which
+case the file is considered of the type ``DebugInfo``.
+
+Valid values for the ``type`` field are:
+
+* ``CoreFile``: A core file that has a checkpoint of a program's execution
state.
+* ``Executable``: A normal executable.
+* ``DebugInfo``: An object file that contains only debug information.
+* ``DynamicLinker``: The platform's dynamic linker executable.
+* ``ObjectFile``: An intermediate object file.
+* ``SharedLibrary``: A shared library that can be used during execution.
+* ``StubLibrary``: A library that can be linked against but not used for
execution.
+* ``JIT``: JIT code that has symbols, sections and possibly debug info.
+
+
+sections
+````````
+
+* ``name``: a string representing the section name.
+* ``type``: a string representing the section type (see below).
+* ``address``: a number representing the section file address.
+* ``size``: a number representing the section size in bytes.
+
+.. code-block:: JSON
+
+ {
+ "name": "__TEXT",
+ "type": "code",
+ "address": 0,
+ "size": 546,
+ }
+
+The ``type`` field accepts the following values: ``code``, ``container``,
+``data``, ``debug``.
+
+symbols
+```````
+
+Symbols are JSON objects with the following keys:
+
+* ``name``: a string representing the string name.
+* ``value``: a number representing the symbol value.
+* ``address``: a number representing the symbol address in a section.
+* ``size``: a number representing the symbol size.
+* ``type``: an optional string representing the symbol type (see below).
+
+A symbol must contain either a ``value`` or an ``address``. The ``type`` is
+optional.
+
+.. code-block:: JSON
+
+ {
+ "name": "foo",
+ "type": "code",
+ "size": 10,
+ "address": 4294983544,
+ }
+
+The ``type`` field accepts any type in the ``lldb::SymbolType`` enum in
+`lldb-enumerations.h
<https://lldb.llvm.org/cpp_reference/lldb-enumerations_8h.html>`_
+, without the ``eSymbolType``. For example ``code`` maps to ``eSymbolTypeCode``
+and ``variableType`` to ``eSymbolTypeVariableType``.
+
+Usage
+-----
+
+Symbol files can be added with the ``target symbol add`` command. The triple
+and UUID will be used to match it to the correct module.
+
+.. code-block:: shell
+
+ (lldb) target symbol add /path/to/symbol.json
+ symbol file '/path/to/symbol.json' has been added to '/path/to/executable'
+
+You can use ``image list`` to confirm that the symbol file has been associated
+with the module.
+
+.. code-block:: shell
+
+ (lldb) image list
+ [ 0] A711AB38-1FB1-38B1-B38B-859352ED2A20 0x0000000100000000
/path/to/executable
+ /path/to/symbol.json
+ [ 1] 4BF76A72-53CC-3E42-8945-4E314C101535 0x00000001800c6000 /usr/lib/dyld
+
+
+Example
+-------
+
+The simplest valid JSON symbol file consists of just a triple and UUID:
+
+.. code-block:: JSON
+
+ {
+ "triple": "arm64-apple-macosx15.0.0",
+ "uuid": "A711AB38-1FB1-38B1-B38B-859352ED2A20"
+ }
+
+A JSON symbol file with symbols for ``main``, ``foo``, and ``bar``.
+
+.. code-block:: JSON
+
+ {
+ "triple": "arm64-apple-macosx15.0.0",
+ "uuid": "321C6225-2378-3E6D-B6C1-6374DEC6D81A",
+ "symbols": [
+ {
+ "name": "main",
+ "type": "code",
+ "size": 32,
+ "address": 4294983552
+ },
+ {
+ "name": "foo",
+ "type": "code",
+ "size": 8,
+ "address": 4294983544
+ },
+ {
+ "name": "bar",
+ "type": "code",
+ "size": 0,
+ "value": 255
+ }
+ ]
+ }
+
+A symbol file with a symbol ``foo`` belonging to the ``__TEXT`` section.
+
+.. code-block:: JSON
+
+ {
+ "triple": "arm64-apple-macosx15.0.0",
+ "uuid": "58489DB0-F9FF-4E62-ABD1-A7CCE5DFB879",
+ "type": "sharedlibrary",
+ "sections": [
+ {
+ "name": "__TEXT",
+ "type": "code",
+ "address": 0,
+ "size": 546
+ }
+ ],
+ "symbols": [
+ {
+ "name": "foo",
+ "address": 256,
+ "size": 17
+ }
+ ]
+ }
>From 522a4a9f5f9a65407c36c32feea4ec35ab9c2ddc Mon Sep 17 00:00:00 2001
From: Jonas Devlieghere <jo...@devlieghere.com>
Date: Fri, 18 Oct 2024 10:23:35 -0700
Subject: [PATCH 2/2] types are lowercase
---
lldb/docs/resources/symbolfilejson.rst | 16 ++++++++--------
1 file changed, 8 insertions(+), 8 deletions(-)
diff --git a/lldb/docs/resources/symbolfilejson.rst
b/lldb/docs/resources/symbolfilejson.rst
index 54f606ce1ffd58..99ef935476902a 100644
--- a/lldb/docs/resources/symbolfilejson.rst
+++ b/lldb/docs/resources/symbolfilejson.rst
@@ -54,14 +54,14 @@ case the file is considered of the type ``DebugInfo``.
Valid values for the ``type`` field are:
-* ``CoreFile``: A core file that has a checkpoint of a program's execution
state.
-* ``Executable``: A normal executable.
-* ``DebugInfo``: An object file that contains only debug information.
-* ``DynamicLinker``: The platform's dynamic linker executable.
-* ``ObjectFile``: An intermediate object file.
-* ``SharedLibrary``: A shared library that can be used during execution.
-* ``StubLibrary``: A library that can be linked against but not used for
execution.
-* ``JIT``: JIT code that has symbols, sections and possibly debug info.
+* ``corefile``: A core file that has a checkpoint of a program's execution
state.
+* ``executable``: A normal executable.
+* ``debuginfo``: An object file that contains only debug information.
+* ``dynamicuinker``: The platform's dynamic linker executable.
+* ``objectfile``: An intermediate object file.
+* ``sharedlibrary``: A shared library that can be used during execution.
+* ``stublibrary``: A library that can be linked against but not used for
execution.
+* ``jit``: JIT code that has symbols, sections and possibly debug info.
sections
_______________________________________________
lldb-commits mailing list
lldb-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
