yurydelendik/x-scopes.md

## x-scopes.md

      
    Raw
  

              x-scopes.md
            
          
    Experimental "x-scopes" source maps extension

This is crude attempt to add DWARF-like information to the existing wasm source maps. It is not intendent to be used as a final solution, but provides overview of the information that can be used by a consumer/debugger of
wasm code.
The source maps JSON is extended to add the x-scopes field at the top level that will contains all information generated by LLVM's llvm-dwarfdump command. To reduce burden of parsing at the consumer side, the dump will be converted to the JSON using following rules:

DW_TAG_xxx entity will be converted to a JS object with tag field with xxx value.
If the above entry has nested level of children, the children field will be added and will contain JS array.
DW_AT_yyy attributes will be assigned at fields to the enclosing object with yyy name. Theirs values will be:
a) The string values will be JS strings,
b) The true/false values will be corresponding JS booleans,
c) The decimal and hex values will be JS numbers,
d) The enumeration values, such as DW_ZZZ_vvv, will become strings e.g. vvv,
e) The array-like values, e.g. ranges or locations, will be parsed and converted to arrays (TBD examples)
f) The filename specific values are replaced by the source id from the sources field of the main source map JSON.

The root object/array will be assigned to the debug_info field of the x-scopes object.
The binary offest of the code section will be stored at the code_section_offset field for informational purpose.
wasm-sourcemap.py

The prototype of the code that converts LLVM DWARF section to the source map and adds x-scopes allows to do the described above conversion. It requires the llvm-dwarfdump tool to understand WebAssembly target.
llvm-dwarfdump conversion examaple

llvm-dwarfdump output

.debug_info contents:
0x00000000: Compile Unit: length = 0x0000003d version = 0x0004 abbr_offset = 0x0000 addr_size = 0x04 (next unit at 0x00000041)

0x0000000b: DW_TAG_compile_unit
              DW_AT_producer	("clang version 7.0.0 (trunk 337293)")
              DW_AT_language	(DW_LANG_C99)
              DW_AT_name	("link2.c")
              DW_AT_stmt_list	(0x00000000)
              DW_AT_comp_dir	("/Users/yury/llvmwasm")
              DW_AT_GNU_pubnames	(true)
              DW_AT_low_pc	(0x0000000000000002)
              DW_AT_high_pc	(0x000000000000000d)

0x00000026:   DW_TAG_subprogram
                DW_AT_low_pc	(0x0000000000000002)
                DW_AT_high_pc	(0x000000000000000d)
                DW_AT_name	("foo")
                DW_AT_decl_file	("/Users/yury/llvmwasm/link2.c")
                DW_AT_decl_line	(1)
                DW_AT_type	(0x00000039 "int")
                DW_AT_external	(true)

0x00000039:   DW_TAG_base_type
                DW_AT_name	("int")
                DW_AT_encoding	(DW_ATE_signed)
                DW_AT_byte_size	(0x04)

0x00000040:   NULL

wasm-sourcemap.py --scopeinfo result

{
    "version":3,
    "names":[],
    "sources":["link2.c"],
    "sourcesContent":null,
    "mappings":"mGAAA,OACE,IAAA",
    "x-scopes":{
        "debug_info":[
            {
                "tag":"compile_unit",
                "producer":"clang version 7.0.0 (trunk 337293)",
                "language":"C99",
                "name":"link2.c",
                "stmt_list":0,
                "GNU_pubnames":true,
                "low_pc":2,
                "high_pc":13,
                "children":[
                    {
                        "tag":"subprogram",
                        "low_pc":2,
                        "high_pc":13,
                        "name":"foo",
                        "decl_file":0,
                        "decl_line":1,
                        "type":"int",
                        "external":true
                    },
                    {
                        "tag":"base_type",
                        "name":"int",
                        "encoding":"signed",
                        "byte_size":4
                    }
                ]
            }
        ],
        "code_section_offset":97
    }
}