Skip to content

Commit

Permalink
Coredump: switch format to Wasm module
Browse files Browse the repository at this point in the history
Reuse the Wasm module container to store a coredump. Debugging
informations are stored in custom sections and the main memory in the
data section.
  • Loading branch information
xtuc committed Jan 30, 2023
1 parent f1645f6 commit 1d495fa
Showing 1 changed file with 30 additions and 21 deletions.
51 changes: 30 additions & 21 deletions Coredump.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,41 +70,46 @@ app's state) are in JS rather than Wasm.

# Coredump file format

The generated coredump is a binary file containing:
The coredump file is encoded using the [Wasm binary format], containing:
- general information about the process.
- the threads and stack frames.
- a snapshot of the WebAssembly linear memory or relevant regions.
- the `coredump` struct.

The placement of the `coredump` struct within the coredump file is not defined
yet. However, for the sake of argument we assume it's at offset 0.
The order in which they appear in the file is not important.

# `coredump` struct
## Process information

The coredump struct starts with the number of frames recorded and the combined
size of all frames, followed by the frames themself.
General information about the process is stored in a [Custom section], called
`core`.

```
coredump ::= size:u32 cont:vec(frame)
core ::= customsec(process-info)
process-info ::= 0x0 executable-name:name
```

> implementer note: since the `frame` struct doesn't have a fixed size, the
> `size` value can be used to append new frames because it's pointing at the end
> of the `coredump`.
## Thread(s) and stack frames

For each thread a [Custom section], called `corestack`, is used to store the
debugging information.

```
frame ::= codeoffset:u32
locals:vec(local)
stack:vec(stack)
reserved:u32
corestack ::= customsec(thread-info vec(frame))
thread-info ::= 0x0 thread-name:name
frame ::= codeoffset:u32
locals:vec(u32)
stack:vec(u32)
reserved:u32
```

The `reserved` bytes are decoded as an empty vector and reserved for future use.
The `reserved` byte is decoded as an empty vector and reserved for future use.

`vec` (same encoding as [Wasm Vectors]):
```
vec(B) ::= n:u32 cont:B
```
## Memory

The process memory is captured in the [Data Section], either entirely as one
active data segment or as multiple active data segments (used to represent
partial coredumps).

`u32` are encoding using LEB128, like [Wasm u32].
One or multiple memories are written in the [Memory Section].

# Demo

Expand All @@ -128,3 +133,7 @@ tooling: [demo].
[Wasm u32]: https://webassembly.github.io/spec/core/binary/values.html#binary-int
[demo]: https://github.com/xtuc/wasmgdb/wiki/Demo
[multi-memory]: https://github.com/WebAssembly/multi-memory
[Wasm binary format]: https://webassembly.github.io/spec/core/binary/index.html
[Data Section]: https://webassembly.github.io/spec/core/binary/modules.html#data-section
[Custom section]: https://webassembly.github.io/spec/core/binary/modules.html#binary-customsec
[Memory Section]: https://webassembly.github.io/spec/core/binary/modules.html#binary-memsec

0 comments on commit 1d495fa

Please sign in to comment.