TITLE: Installing CKB Debugger CLI Tool (Shell)
DESCRIPTION: This command installs the `ckb-debugger` command-line tool directly from the Git repository. It allows users to develop CKB scripts offline and is a core component of the CKB standalone debugger suite.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/README.md#_snippet_0

LANGUAGE: sh
CODE:
```
cargo install --git https://github.com/nervosnetwork/ckb-standalone-debugger ckb-debugger
```

----------------------------------------

TITLE: Displaying CKB Debugger Command Line Help (Text)
DESCRIPTION: This snippet illustrates the command-line interface (CLI) usage for the `ckb-debugger` tool. It outlines the various flags, options, and arguments available, providing comprehensive details on how to configure and control the debugger's execution, including modes, cycle limits, and GDB remote debugging. This information is crucial for users to effectively invoke and customize the debugger from the terminal.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/README.md#_snippet_0

LANGUAGE: text
CODE:
```
ckb-debugger 0.119.0

USAGE:
    ckb-debugger [FLAGS] [OPTIONS] --mode <mode> [args]...

FLAGS:
        --enable-overlapping-detection    Set to true to enable overlapping detection between stack and heap
        --enable-steplog                  Set to true to enable step mode, where we print PC address for each
                                          instruction
    -h, --help                            Prints help information
        --prompt                          Set to true to prompt for stdin input before executing
    -V, --version                         Prints version information

OPTIONS:
        --bin <bin>                                File used to replace the binary denoted in the script
    -i, --cell-index <cell-index>                  Index of cell to run
    -t, --cell-type <cell-type>                    Type of cell to run [possible values: input, output]
        --dump-file <dump-file>                    Dump file name
        --gdb-listen <gdb-listen>
            Address to listen for GDB remote debugging server [default: 127.0.0.1:9999]

        --max-cycles <max-cycles>                  Max cycles [default: 3500000000]
        --mode <mode>
            Execution mode of debugger [default: full]  [possible values: decode-instruction, fast, full, gdb, probe]

        --pid <pid>                                Process ID [default: 0]
        --pprof <pprof>                            Performance profiling, specify output file for further use
        --read-file <read-file>
            Read content from local file or stdin. Then feed the content to syscall in scripts

    -s, --script-group-type <script-group-type>    Script group type [possible values: lock, type]
        --script-hash <script-hash>                Script hash
        --script-version <script-version>          Script version [default: 2]
    -f, --tx-file <tx-file>                        Filename containing JSON formatted transaction dump

ARGS:
    <args>...
```

----------------------------------------

TITLE: Downloading CKB Transaction with ckb-cli
DESCRIPTION: This command uses `ckb-cli` to download a specific transaction from the CKB mainnet by its hash and saves it to a local JSON file named `mock_tx.json`. This prepares the transaction for subsequent local debugging.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/examples/mock_tx.md#_snippet_0

LANGUAGE: sh
CODE:
```
ckb-cli --url https://mainnet.ckbapp.dev/rpc mock-tx dump --tx-hash 0x5f0a4162622daa0e50b2cf8f49bc6ece22d1458d96fc12a094d6f074d6adbb55 --output-file mock_tx.json
```

----------------------------------------

TITLE: GDB Commands for Debugging CKB Exec Scripts (GDB Commands)
DESCRIPTION: This sequence of GDB commands is used to debug CKB 'exec' scripts. It imports symbols from both caller and callee executables, sets breakpoints at internal syscalls and the `_start` function, and continues execution to hit these breakpoints for inspection.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/examples/exec.md#_snippet_2

LANGUAGE: gdb-commands
CODE:
```
file exec_caller                   # Import symbols from exec_caller
target remote 127.0.0.1:9999       # Link to ckb-debugger
b __internal_syscall               # Set a breakpoint at __internal_syscall
c                                  # Fetch the 1st breakpoint: ckb_debug
c                                  # Fetch the 2nd breakpoint: ckb_exec
file exec_callee                   # Import symbols from exec_callee
b _start                           # Set a breakpoint at exec_callee's _start
c                                  # Continue
l                                  # List raw codes
```

----------------------------------------

TITLE: Debugging Out-of-Memory with ckb-debugger (Shell)
DESCRIPTION: This snippet demonstrates how to compile and run an example CKB contract that triggers an out-of-memory error using `make` and `ckb-debugger`. It shows the debugger's output, which includes the function call stack leading to the OOM, the state of the registers at the point of failure, and the 'MemOutOfBound' error message. This output is crucial for diagnosing memory-related issues in CKB contract development.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/examples/out_of_memory.md#_snippet_0

LANGUAGE: sh
CODE:
```
$ make out_of_memory
$ ckb-debugger --bin out_of_memory

??:??:??
/home/ubuntu/src/ckb-standalone-debugger/ckb-debugger/examples/ckb-c-stdlib/libc/entry.h:9:_start
/home/ubuntu/src/ckb-standalone-debugger/ckb-debugger/examples/out_of_memory.c:25:main
/home/ubuntu/src/ckb-standalone-debugger/ckb-debugger/examples/out_of_memory.c:21:c
/home/ubuntu/src/ckb-standalone-debugger/ckb-debugger/examples/out_of_memory.c:17:b
/home/ubuntu/src/ckb-standalone-debugger/ckb-debugger/examples/out_of_memory.c:7:a

pc  : 0x           12D28
zero: 0x               0 ra  : 0x           12D3E sp  : 0x          3FFFA0 gp  : 0x           146E8
tp  : 0x               0 t0  : 0x               0 t1  : 0x               0 t2  : 0x               0
s0  : 0x          3FFFB0 s1  : 0x               0 a0  : 0x               0 a1  : 0x          400000
a2  : 0x               0 a3  : 0x               0 a4  : 0x               0 a5  : 0x               0
a6  : 0x               0 a7  : 0x               0 s2  : 0x               0 s3  : 0x               0
s4  : 0x               0 s5  : 0x               0 s6  : 0x               0 s7  : 0x               0
s8  : 0x               0 s9  : 0x               0 s10 : 0x               0 s11 : 0x               0
t3  : 0x               0 t4  : 0x               0 t5  : 0x               0 t6  : 0x               0

Error: MemOutOfBound
```

----------------------------------------

TITLE: Interactive GDB Debugging Session with CKB VM
DESCRIPTION: An interactive GDB session demonstrating how to connect to the CKB VM debugger, set a breakpoint at `main`, continue execution, step through the code, and print the value of a variable `i`.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-vm-debug-utils/README.md#_snippet_2

LANGUAGE: bash
CODE:
```
$ cd ckb-vm-debug-utils
$ gdb program
(gdb) target remote localhost:2000
Remote debugging using localhost:2000
0x00000000000100c8 in _start ()
(gdb) b main
Breakpoint 1 at 0x101ba: file program.c, line 6.
(gdb) c
Continuing.

Breakpoint 1, main () at program.c:6
6         for (i = 0; i < 10; i++) {
(gdb) s
7           result += power(2, i);
(gdb) print i
$1 = 0
(gdb)
```

----------------------------------------

TITLE: Extracting Transaction Data for Debugger - Rust
DESCRIPTION: This Rust code snippet, intended for unit tests, uses `context.dump_tx` to extract transaction information and then writes it to a `tx.json` file. This file is crucial for `ckb-debugger` when the contract requires transaction context.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/docs/debugging_contract_with_vscode.md#_snippet_2

LANGUAGE: rust
CODE:
```
let tx_data = context.dump_tx(&tx).expect("dump tx info");
std::fs::write(
    "tx.json",
    serde_json::to_string_pretty(&tx_data).expect("json"),
).expect("write tx");
```

----------------------------------------

TITLE: Executing CKB Script with ckb-debugger (Shell)
DESCRIPTION: This command executes a CKB script using the `ckb-debugger` tool. It specifies the transaction file (`exec.json`), the cell index, cell type, and script group type for the execution, demonstrating a standard script run.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/examples/exec.md#_snippet_0

LANGUAGE: sh
CODE:
```
ckb-debugger --tx-file exec.json --cell-index 0 --cell-type input --script-group-type lock
```

----------------------------------------

TITLE: Dumping Uncommitted Transaction with ckb-cli
DESCRIPTION: This `ckb-cli` command dumps an uncommitted transaction, provided as a raw JSON file (`mock_raw_tx.json`), into a debug-ready `mock_tx.json` file. This allows for local debugging of transactions that have not yet been sent or have failed to commit to the chain, enabling pre-submission validation.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/examples/mock_tx.md#_snippet_4

LANGUAGE: sh
CODE:
```
ckb-cli --url https://mainnet.ckbapp.dev/rpc mock-tx dump --tx-file mock_raw_tx.json --output-file mock_tx.json
```

----------------------------------------

TITLE: Generating SVG Flamegraph from CKB VM Profile Data
DESCRIPTION: This shell command executes the `ckb-vm-pprof` tool (via `cargo run`) with the compiled binary `res/fib`. The output, which is raw profiling data, is then piped to `inferno-flamegraph` to generate an SVG visualization, saved as `res/fib.svg`.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-vm-pprof/README.md#_snippet_3

LANGUAGE: Shell
CODE:
```
$ cargo run -- --bin res/fib | inferno-flamegraph > res/fib.svg
```

----------------------------------------

TITLE: Example C Program for CKB VM Debugging
DESCRIPTION: A simple C program defining `main` and `power` functions, used as an example target for CKB VM debugging. It calculates the sum of powers of 2, demonstrating basic control flow and function calls.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-vm-debug-utils/README.md#_snippet_0

LANGUAGE: C
CODE:
```
int power(int, int);

int main() {
  int i, result;

  for (i = 0; i < 10; i++) {
    result += power(2, i);
  }
  return result;
}

int power(int base, int n) {
  int i, p;
  p = 1;
  for (i = 1; i <= n; i++) p = p * base;
  return p;
}
```

----------------------------------------

TITLE: Configuring VSCode Task for Debug Build - JSON
DESCRIPTION: This VSCode `tasks.json` configuration defines a shell task named 'Build Debug' that compiles the contract, copies it to a `.debug` version, and then strips the original binary using `llvm-objcopy` for release, ensuring a debug-ready binary is available.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/docs/debugging_contract_with_vscode.md#_snippet_1

LANGUAGE: json
CODE:
```
{
    "label": "Build Debug",
    "type": "shell",
    "command": "make build && cp build/ckb-debug/c1 build/ckb-debug/c1.debug && llvm-objcopy --strip-debug --strip-all build/ckb-debug/c1"
}
```

----------------------------------------

TITLE: Replacing and Executing Script with ckb-debugger
DESCRIPTION: This command uses `ckb-debugger` to execute the lock script of the input cell at index 0 from `mock_tx.json`, but replaces the original script with the compiled `always_failure` binary. This demonstrates how to debug a transaction with a modified or new script version, allowing for rapid iteration and testing.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/examples/mock_tx.md#_snippet_3

LANGUAGE: sh
CODE:
```
ckb-debugger --tx-file mock_tx.json --cell-index 0 --cell-type input --script-group-type lock --bin always_failure
```

----------------------------------------

TITLE: Configuring VSCode Task to Launch CKB Debugger - JSON
DESCRIPTION: This VSCode `tasks.json` configuration defines a background process task to automatically start `ckb-debugger` with specified arguments, including the binary path, GDB listen address, and transaction file. The `isBackground` setting ensures the debugger remains active during the VSCode debugging session.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/docs/debugging_contract_with_vscode.md#_snippet_4

LANGUAGE: json
CODE:
```
{
    "label": "Debug c1",
    "isBackground": true,
    "type": "process",
    "command": "ckb-debugger",
    "args": [
        "--bin=build/ckb-debug/c1",
        "--mode=gdb_gdbstub",
        "--gdb-listen=0.0.0.0:8000",
        "--tx-file=tests/tx.json",
        "-s=lock",
        "-i=0"
    ],
    "options": {
        "cwd": "${workspaceRoot}"
    }
}
```

----------------------------------------

TITLE: Compiling RISC-V Program with Debugging Information
DESCRIPTION: This command compiles the `fib.c` source file into an executable `fib` for a RISC-V target, including debugging information (`-g` option) necessary for tools like GDB and flamegraph generation.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/examples/fib.md#_snippet_1

LANGUAGE: Shell
CODE:
```
$ riscv64-unknown-elf-gcc -g -o fib fib.c
```

----------------------------------------

TITLE: Debugging CKB Program with ckb-debugger (sh)
DESCRIPTION: This command executes the compiled `print_log` program using the `ckb-debugger`. The `RUST_LOG=debug` environment variable enables detailed debug logging, showing the execution flow and values of `n` as printed by the C program.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/examples/print_log.md#_snippet_2

LANGUAGE: sh
CODE:
```
$ RUST_LOG=debug ckb-debugger --bin print_log

DEBUG:<unknown>: SCRIPT>n = 5
DEBUG:<unknown>: SCRIPT>n = 4
DEBUG:<unknown>: SCRIPT>n = 3
DEBUG:<unknown>: SCRIPT>n = 2
DEBUG:<unknown>: SCRIPT>n = 1
DEBUG:<unknown>: SCRIPT>n = 0
DEBUG:<unknown>: SCRIPT>n = 1
DEBUG:<unknown>: SCRIPT>n = 2
DEBUG:<unknown>: SCRIPT>n = 1
DEBUG:<unknown>: SCRIPT>n = 0
DEBUG:<unknown>: SCRIPT>n = 3
DEBUG:<unknown>: SCRIPT>n = 2
DEBUG:<unknown>: SCRIPT>n = 1
DEBUG:<unknown>: SCRIPT>n = 0
DEBUG:<unknown>: SCRIPT>n = 1
```

----------------------------------------

TITLE: Printing Traced Memory Contents in Python
DESCRIPTION: This Python snippet iterates over the memory_contents BPF table, which was populated by the C BPF program. It sorts the items by memory address (k.value) and then prints each memory address and its corresponding content in a formatted hexadecimal string. This allows userspace programs to view the extracted function parameters or return values.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/docs/probes.md#_snippet_7

LANGUAGE: Python
CODE:
```
for k, v in sorted(b.get_table("memory_contents").items(), key=lambda kv: kv[0].value):
    print(f"memory addr: {k.value:016x}, content: {v.value:016x}")
```

----------------------------------------

TITLE: Example C Program for CKB-VM Function Tracing
DESCRIPTION: This C program defines `test_func` which allocates memory and stores two integer parameters, returning a pointer to the allocated memory. The `main` function calls `test_func` and frees the returned memory. This program serves as a target for demonstrating advanced function call and return tracing techniques using tools like bcc.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/docs/probes.md#_snippet_2

LANGUAGE: C
CODE:
```
int* test_func(int parameter1, int parameter2) {
    int *mem = (int *)malloc(sizeof(parameter1) + sizeof(parameter2));
    mem[0] = parameter1;
    mem[1] = parameter2;
    return mem;
}

int main(int argc, char **argv) {
    free((void *) test_func(42, 43));
    return 0;
}
```

----------------------------------------

TITLE: Debugging CKB Spawn Syscall with ckb-debugger (Shell)
DESCRIPTION: This shell command executes the `ckb-debugger` in 'fast' mode to debug a transaction defined in `spawn.json`. It targets the input cell at index 0 and specifies that the debugging should focus on the lock script group, demonstrating the usage of the `spawn` syscall.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/examples/spawn.md#_snippet_0

LANGUAGE: sh
CODE:
```
$ ckb-debugger --mode fast --tx-file spawn.json --cell-index 0 --cell-type input --script-group-type lock
```

----------------------------------------

TITLE: Setting Up and Running CKB VM Bare Metal Debugger
DESCRIPTION: Commands to display the example C program, clone the `ckb-vm-debug-utils` repository, build the debugger, compile the C program for RISC-V, and start the bare metal debugger server on a specified address and port.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-vm-debug-utils/README.md#_snippet_1

LANGUAGE: bash
CODE:
```
$ cat program.c
int power(int, int);

int main() {
  int i, result;

  for (i = 0; i < 10; i++) {
    result += power(2, i);
  }
  return result;
}

int power(int base, int n) {
  int i, p;
  p = 1;
  for (i = 1; i <= n; i++) p = p * base;
  return p;
}
$ git clone https://github.com/nervosnetwork/ckb-vm-debug-utils
$ cd ckb-vm-debug-utils
$ cargo build
$ riscv64-unknown-elf-gcc -g ../program.c -o program
$ ./target/debug/baremetal 0.0.0.0:2000 program
```

----------------------------------------

TITLE: Extracting Function Parameters/Return Values in C
DESCRIPTION: This C snippet demonstrates how to extract function parameters or return values using BPF helper functions. It first reads a memory address using bpf_usdt_readarg, then reads a return value from a register (A0) using bpf_probe_read_user. Finally, it reads the content from the calculated memory address (mem_addr + ret) and updates a BPF table named memory_contents with the extracted data.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/docs/probes.md#_snippet_6

LANGUAGE: C
CODE:
```
    uint64_t mem_addr = 0;
    bpf_usdt_readarg(5, ctx, &mem_addr);

    uint64_t ret = 0;
    bpf_probe_read_user(&ret, sizeof(uint64_t), (void *)(regs_addr + 8 * A0));

    uint64_t content = 0;
    bpf_probe_read_user(&content, sizeof(uint64_t), (void *)(mem_addr + ret));
    memory_contents.update(&ret, &content);
```

----------------------------------------

TITLE: Executing Lock Script with ckb-debugger
DESCRIPTION: This command executes the lock script of the input cell at index 0 from the `mock_tx.json` file using `ckb-debugger`. It demonstrates how to run a specific script group within a downloaded transaction locally to observe its behavior and cycle consumption.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/examples/mock_tx.md#_snippet_1

LANGUAGE: sh
CODE:
```
ckb-debugger --tx-file mock_tx.json --cell-index 0 --cell-type input --script-group-type lock
```

----------------------------------------

TITLE: Cloning CKB C Standard Library (sh)
DESCRIPTION: This command clones the `ckb-c-stdlib` repository from GitHub, which provides the necessary standard library functions for C programs running on the CKB VM.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/examples/print_log.md#_snippet_0

LANGUAGE: sh
CODE:
```
$ git clone https://github.com/nervosnetwork/ckb-c-stdlib
```

----------------------------------------

TITLE: Compiling C Code with Debugging Information using GCC
DESCRIPTION: This shell command compiles the `res/fib.c` source file into an executable `res/fib` using `riscv64-unknown-elf-gcc`. The `-g` option is crucial for including debugging information, which is necessary for profiling tools like `ckb-vm-pprof`.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-vm-pprof/README.md#_snippet_1

LANGUAGE: Shell
CODE:
```
$ riscv64-unknown-elf-gcc -g -o res/fib res/fib.c
```

----------------------------------------

TITLE: Installing CKB Debugger WASM Package in Node.js
DESCRIPTION: After building the WebAssembly package with `wasm-pack`, this command demonstrates how to install the generated `pkg` directory into a Node.js project using `npm install`. This makes the WASM module available for import.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/docs/wasm.md#_snippet_1

LANGUAGE: Shell
CODE:
```
$ npm install path/to/pkg
```

----------------------------------------

TITLE: Debugging Callee Entry Point - Debugger Commands
DESCRIPTION: These commands are designed to load the 'exec_callee' executable, set a breakpoint at its `_start` entry point, continue execution until that breakpoint is hit, and then list the source code around the current execution point. This is useful for inspecting the initial execution flow and setup of the callee program.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/examples/exec_gdb_cmd.txt#_snippet_1

LANGUAGE: Debugger Commands
CODE:
```
file exec_callee
b _start
c
l
```

----------------------------------------

TITLE: Configuring VSCode Launch for GDB Debugging - JSON
DESCRIPTION: This VSCode `launch.json` configuration sets up a GDB attach debugger. It specifies the executable with debug symbols, the remote target address, and defines `preLaunchTask` and `postDebugTask` to automatically start and stop `ckb-debugger` during the debugging session.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/docs/debugging_contract_with_vscode.md#_snippet_10

LANGUAGE: json
CODE:
```
{
    "name": "GDB",
    "type": "gdb",
    "request": "attach",
    "executable": "build/ckb-debug/c1.debug",
    "debugger_args": [],
    "cwd": "${workspaceRoot}",
    "remote": true,
    "target": "127.0.0.1:8000",
    "preLaunchTask": "Debug c1",
    "postDebugTask": "stop-ckb-debugger"
}
```

----------------------------------------

TITLE: Running CKB Debugger WASM for Transaction Verification in Node.js
DESCRIPTION: This JavaScript snippet demonstrates how to use the `ckb-debugger` WASM module to perform basic transaction verification. It reads a `tx.json` file, calls `run_json` with the transaction data, a script type ('lock'), a script hash, and a capacity, then logs the result. It requires the `ckb-debugger` WASM package to be installed.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/docs/wasm.md#_snippet_2

LANGUAGE: JavaScript
CODE:
```
import * as wasm from 'ckb-debugger';

const tx_file = fs.readFileSync('tx.json', 'utf8');
const result = wasm.run_json(tx_file, 'lock', '0x494e57d09aa7d17ad9559046fdab6a455811f6f86c5f6594b76de934d47e2553', '1000000000')
console.log(result)
```

----------------------------------------

TITLE: Processing Compiled Contracts for Debugging - Shell
DESCRIPTION: This shell command copies the compiled contract to a `.debug` version and then strips debug symbols and all symbols from the original binary using `llvm-objcopy` to reduce its size, while keeping the debug version for debugging.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/docs/debugging_contract_with_vscode.md#_snippet_0

LANGUAGE: shell
CODE:
```
cp build/ckb-debug/<Contract-Name> build/ckb-debug/<Contract-Name>.debug
llvm-objcopy --strip-debug --strip-all build/ckb-debug/<Contract-Name>
```

----------------------------------------

TITLE: C Program for Always Failing Script
DESCRIPTION: This C code defines a simple program named `always_failure.c` that always returns an exit code of `1`. It is intended to be compiled and used with `ckb-debugger` to replace an existing script, demonstrating how to test script failures or specific error conditions.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/examples/mock_tx.md#_snippet_2

LANGUAGE: c
CODE:
```
// always_failure.c
int main() {
    return 1;
}
```

----------------------------------------

TITLE: Debugging Caller with Remote Target - Debugger Commands
DESCRIPTION: This sequence of debugger commands is used to load the 'exec_caller' executable, connect to a remote debugger instance at 127.0.0.1:9999, set a breakpoint at the `__internal_syscall` function, and then continue execution twice. This is typical for debugging the caller's side of an interaction or a specific system call.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/examples/exec_gdb_cmd.txt#_snippet_0

LANGUAGE: Debugger Commands
CODE:
```
file exec_caller
target remote 127.0.0.1:9999
b __internal_syscall
c
c
```

----------------------------------------

TITLE: Generating Performance Profile with CKB Debugger
DESCRIPTION: This command uses `ckb-debugger` to execute the `fib` binary and save its execution trace data into a pprof-compatible file (`fib.pprof`), which can then be used for performance analysis and flamegraph visualization.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/examples/fib.md#_snippet_2

LANGUAGE: Shell
CODE:
```
$ ckb-debugger --bin fib --pprof fib.pprof
```

----------------------------------------

TITLE: Compiling C Program for CKB VM (sh)
DESCRIPTION: This command compiles the `print_log.c` source file using `riscv64-unknown-elf-gcc`, linking it statically with the CKB C standard library. It disables built-in printf and standard includes to ensure compatibility with the CKB environment, producing an executable named `print_log`.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/examples/print_log.md#_snippet_1

LANGUAGE: sh
CODE:
```
$ riscv64-unknown-elf-gcc -fno-builtin-printf -nostdinc -nostdlib -nostartfiles -I ./ckb-c-stdlib/libc -I ./ckb-c-stdlib -g -Wl,-static -o print_log print_log.c
```

----------------------------------------

TITLE: Executing CKB Debugger WASM with WASI in Node.js
DESCRIPTION: This JavaScript snippet demonstrates how to load and execute a `ckb-debugger` WASM module compiled for WASI within a Node.js environment. It configures a WASI host, sets up arguments and preopened directories, compiles the WASM binary, instantiates it with the WASI import object, and starts the WASI instance. It requires `node:fs` and `node:wasi` modules.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/docs/wasm.md#_snippet_4

LANGUAGE: JavaScript
CODE:
```
import * as fs from 'node:fs'
import * as wasi from 'node:wasi'

const wasihost = new wasi.WASI({
  version: 'preview1',
  args: ['ckb-debugger', '--bin', '/path/to/binary'],
  preopens: {
    '/path/to/binary': '/path/to/binary',
  },
});

async function main() {
  const wasm = await WebAssembly.compile(
    fs.readFileSync('/path/to/ckb-debugger.wasm'),
  );
  const instance = await WebAssembly.instantiate(wasm, wasihost.getImportObject());
  wasihost.start(instance);
}

main()
```

----------------------------------------

TITLE: Configuring VSCode Task to Stop CKB Debugger - JSON
DESCRIPTION: This VSCode `tasks.json` configuration defines a shell task to stop the `ckb-debugger` process. Since `ckb-debugger` doesn't exit automatically, this task uses `killall ckb-debugger` to terminate it, ensuring a clean shutdown after debugging.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/docs/debugging_contract_with_vscode.md#_snippet_5

LANGUAGE: json
CODE:
```
{
    "label": "stop-ckb-debugger",
    "type": "shell",
    "command": "killall ckb-debugger || true"
}
```

----------------------------------------

TITLE: Starting CKB Debugger in GDB Server Mode - Shell
DESCRIPTION: This shell command launches `ckb-debugger` in `gdb_gdbstub` mode, specifying the contract binary, listening port (8000), and the path to the transaction data file. The `-s` and `-i` flags specify the script and input index for debugging.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/docs/debugging_contract_with_vscode.md#_snippet_3

LANGUAGE: shell
CODE:
```
ckb-debugger \
    --bin=build/ckb-debug/c1 \
    --mode=gdb_gdbstub \
    --gdb-listen=0.0.0.0:8000 \
    --tx-file=tests/tx.json \
    -s=lock \
    -i=0
```

----------------------------------------

TITLE: Debugging RISC-V Programs with GDB and CKB Debugger
DESCRIPTION: This snippet demonstrates how to set up GDB for remote debugging a RISC-V program (`fib`) using `ckb-debugger`. It shows connecting GDB to the debugger, setting a breakpoint at the `fib` function, and continuing execution to inspect parameters at the breakpoint.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/examples/fib.md#_snippet_0

LANGUAGE: Shell
CODE:
```
$ ckb-debugger --mode gdb --gdb-listen 127.0.0.1:9999 --bin fib
$ riscv64-unknown-elf-gdb fib

$ (gdb) target remote 127.0.0.1:9999
$ (gdb) b fib
$ (gdb) c
```

----------------------------------------

TITLE: Tracing `do_sys_open` Function with bpftrace
DESCRIPTION: This `bpftrace` script demonstrates how to trace the `do_sys_open` function in the Linux kernel. It uses a `uprobe` to attach to the function and prints a message to the console every time the function is called. This illustrates a basic use case for `bpftrace` in user-level function tracing.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/docs/probes.md#_snippet_0

LANGUAGE: bpftrace
CODE:
```
uprobe:/usr/src/linux/fs/open.c:do_sys_open
{
    printf("do_sys_open called\n");
}
```

----------------------------------------

TITLE: Defining file_write Syscall Signature - C
DESCRIPTION: This C snippet presents the function signature for `file_write`, a cross-platform syscall. It accepts a `path` for the file, a `ptr` to the data buffer, and the `size` of the data. The syscall writes content to the local file system on Windows, *nix, and wasm-wasi, and to localstorage in hexadecimal format within wasm browser environments.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/examples/file_write.md#_snippet_0

LANGUAGE: c
CODE:
```
int file_write(const char* path, void *ptr, size_t size)
```

----------------------------------------

TITLE: Converting ckb-vm-pprof data to pprof format using Rust
DESCRIPTION: This command executes the `ckb-vm-pprof-converter` tool, which takes raw profiling data from `ckb-vm-pprof` (simulated here with `res/fib`) via a pipe and converts it into the `profile.proto` format. This is the first step in generating a `pprof` compatible output file.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-vm-pprof-converter/README.md#_snippet_0

LANGUAGE: Shell
CODE:
```
cargo run -- --bin res/fib | ckb-vm-pprof-converter
```

----------------------------------------

TITLE: Connecting LLDB to Remote CKB Debugger - LLDB
DESCRIPTION: This LLDB command connects the local LLDB instance to the `ckb-debugger`'s GDB server, which is listening on port 8000. Once connected, standard LLDB commands can be used for debugging the contract.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/docs/debugging_contract_with_vscode.md#_snippet_9

LANGUAGE: lldb
CODE:
```
gdb-remote 8000
```

----------------------------------------

TITLE: Connecting GDB to Remote CKB Debugger - GDB
DESCRIPTION: This GDB command connects the local GDB instance to the `ckb-debugger`'s GDB server, which is listening on `127.0.0.1:8000`. Once connected, standard GDB commands can be used for debugging the contract.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/docs/debugging_contract_with_vscode.md#_snippet_7

LANGUAGE: gdb
CODE:
```
target remote 127.0.0.1:8000
```

----------------------------------------

TITLE: DSL for Simplifying CKB Transaction JSON (Text)
DESCRIPTION: This snippet describes a Domain Specific Language (DSL) used to simplify the creation of `tx.json` files for CKB. It includes syntax for embedding file content as hexadecimal data, calculating and embedding file Blake2b hashes, and defining or referencing `type_id` values within the transaction structure.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/examples/spawn.md#_snippet_1

LANGUAGE: text
CODE:
```
{{ data path/to/file }} => replact it by hexdata of path/to/file
{{ hash path/to/file }} => replace it by blake2b of path/to/file
{{ def_type any_type_id_name }} => create a new type_id named any_type_id_name
{{ ref_type any_type_id_name }} => refer to the type_id above
```

----------------------------------------

TITLE: Invoking file_write Syscall - Rust Example
DESCRIPTION: This Rust example shows how to call the `file_write` syscall (number 9013) to write 'Hello World!' to 'file_write_foo.txt'. It converts the filename and data string into `u64` pointers using `CString` and `as_bytes().as_ptr()`, then passes them with the data size to the `syscall` function. The remaining arguments are placeholders.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/examples/file_write.md#_snippet_2

LANGUAGE: rs
CODE:
```
syscall(
    CString::from_str("file_write_foo.txt").unwrap().as_ptr() as u64,
    "Hello World!\n".as_bytes().as_ptr() as u64,
    13,
    0,
    0,
    0,
    0,
    9013,
);
```

----------------------------------------

TITLE: Launching GDB with Debug Symbols - Shell
DESCRIPTION: This shell command starts the GDB debugger, loading the compiled contract binary that includes debug symbols. This prepares GDB to connect to a remote GDB server for debugging.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/docs/debugging_contract_with_vscode.md#_snippet_6

LANGUAGE: shell
CODE:
```
gdb build/ckb-debug/c1.debug
```

----------------------------------------

TITLE: Debugging CKB Script with GDB and ckb-debugger (Shell)
DESCRIPTION: These commands initiate a GDB debugging session for a CKB script. The first command starts `ckb-debugger` in GDB mode, listening on a specified address, while the second launches `riscv64-unknown-elf-gdb` and loads GDB commands from a file to connect to the debugger.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/examples/exec.md#_snippet_1

LANGUAGE: sh
CODE:
```
ckb-debugger --tx-file exec.json --cell-index 0 --cell-type input --script-group-type lock --mode gdb --gdb-listen 127.0.0.1:9999
riscv64-unknown-elf-gdb --command=exec_gdb_cmd.txt
```

----------------------------------------

TITLE: Decoding RISC-V Jump Instructions in C
DESCRIPTION: This C snippet decodes various RISC-V jump instructions (JAL, JALR, OP_FAR_JUMP_ABS, OP_FAR_JUMP_REL) to determine the link address (return address) and the next program counter. It uses BPF helper functions like bpf_probe_read_user to access register values for JALR. The snippet is crucial for identifying potential function calls or returns by calculating the target addresses.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/docs/probes.md#_snippet_4

LANGUAGE: C
CODE:
```
    InstructionOpcode opcode = EXTRACT_OPCODE(instruction);
    uint8_t instruction_length = INSTRUCTION_LENGTH(instruction);
    // The return address that we will jump to when this jump instruction finishes,
    // normally current_pc + instruction_length.
    uint64_t link;
    // The address that this jump instruction will jump to.
    uint64_t next_pc;
    SImmediate imm;
    RegisterIndex ind;

    // Decode the instuction to get function calls/returns information.
    switch (opcode)
    {
        case OP_JAL:
            link = pc + instruction_length;
            imm = UTYPE_IMMEDIATE_S(instruction);
            next_pc = pc + imm;
            break;
        case OP_JALR_VERSION0:
        case OP_JALR_VERSION1:
            link = pc + instruction_length;
            imm = ITYPE_IMMEDIATE_S(instruction);
            ind = ITYPE_RS1(instruction);
            uint64_t reg_value = 0;
            bpf_probe_read_user(&reg_value, sizeof(uint64_t), (void *)(regs_addr + sizeof(uint64_t) * ind));
            next_pc = (reg_value + imm) & ~1;
            break;
        case OP_FAR_JUMP_ABS:
            link = pc + instruction_length;
            imm = UTYPE_IMMEDIATE_S(instruction);
            next_pc = imm & ~1;
            break;
        case OP_FAR_JUMP_REL:
            link = pc + instruction_length;
            imm = UTYPE_IMMEDIATE_S(instruction);
            next_pc = (pc + imm) & ~1;
            break;
        default:
            return 0;
    }
```

----------------------------------------

TITLE: Invoking file_write Syscall - C Example
DESCRIPTION: This C example demonstrates invoking the `file_write` syscall (number 9013) to write 'Hello World!' to 'file_write_foo.txt'. It initializes a `char` pointer `data` and its `size`, then passes these along with the filename to the `syscall` function. The trailing zeros are unused arguments for this specific syscall invocation.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/examples/file_write.md#_snippet_1

LANGUAGE: c
CODE:
```
char *data = "Hello World!\n";
size_t size = 13;
syscall(9013, "file_write_foo.txt", data, size, 0, 0, 0);
```

----------------------------------------

TITLE: Converting Pprof Data to Flamegraph SVG
DESCRIPTION: This command pipes the performance profile data from `fib.pprof` (generated by `ckb-debugger`) into `inferno-flamegraph`, which then generates an SVG visualization of the flamegraph, saved as `fib.svg`.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/examples/fib.md#_snippet_4

LANGUAGE: Shell
CODE:
```
$ cat fib.pprof | inferno-flamegraph > fib.svg
```

----------------------------------------

TITLE: Loading generated profile data into pprof
DESCRIPTION: This command loads the `output.pprof` file, which was generated by `ckb-vm-pprof-converter`, into the `pprof` tool. The `res/fib` argument likely provides the binary context for symbol resolution within the profile, enabling detailed analysis of the profiling data.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-vm-pprof-converter/README.md#_snippet_1

LANGUAGE: Shell
CODE:
```
pprof res/fib output.pprof
```

----------------------------------------

TITLE: Executing BCC Python Script for Function Tracing
DESCRIPTION: This command executes the `trace.py` BCC Python script with superuser privileges. This script is designed to trace function calls and returns, including parameters and return values, for CKB-VM programs, as demonstrated with the provided C example. It leverages BCC for sophisticated tracing capabilities.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/docs/probes.md#_snippet_3

LANGUAGE: bash
CODE:
```
sudo ./trace.py
```

----------------------------------------

TITLE: Tracing CKB-VM Syscall Instructions with bpftrace
DESCRIPTION: This `bpftrace` command traces the execution of `ecall` (syscall) instructions within the `ckb-debugger` by monitoring the `ckb_vm:execute_inst` USDT probe. It filters for instructions with the encoding `0x2000023` and prints the program counter, consumed cycles, instruction, and register/memory addresses. This helps in debugging and understanding syscall behavior.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/docs/probes.md#_snippet_1

LANGUAGE: bpftrace
CODE:
```
sudo bpftrace -e 'usdt:./target/release/ckb-debugger:ckb_vm:execute_inst /arg2 == 0x2000023/ { printf("%p, %d, %p, %p, %p\n", arg0, arg1, arg2, arg3, arg4); }'
```

----------------------------------------

TITLE: Launching LLDB with Debug Symbols - Shell
DESCRIPTION: This shell command starts the LLDB debugger, loading the compiled contract binary that includes debug symbols. This prepares LLDB to connect to a remote GDB server for debugging.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/docs/debugging_contract_with_vscode.md#_snippet_8

LANGUAGE: shell
CODE:
```
lldb build/ckb-debugger/c1.debug
```

----------------------------------------

TITLE: Installing Inferno for Flamegraph Visualization
DESCRIPTION: This shell command uses `cargo` to install the `inferno` tool, which is required to convert textual flamegraph data into a visual SVG format. `inferno` provides the `inferno-flamegraph` utility.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-vm-pprof/README.md#_snippet_2

LANGUAGE: Shell
CODE:
```
$ cargo install inferno
```

----------------------------------------

TITLE: Installing Inferno for Flamegraph Generation
DESCRIPTION: This command installs the `inferno` tool, a Rust-based utility, which is required to convert the textual pprof output generated by `ckb-debugger` into a visual flamegraph (SVG format).
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/examples/fib.md#_snippet_3

LANGUAGE: Shell
CODE:
```
$ cargo install inferno
```

----------------------------------------

TITLE: Building CKB Debugger for Node.js with wasm-pack
DESCRIPTION: This snippet provides the shell commands to install `wasm-pack` and build the `ckb-debugger` project for a Node.js target. `wasm-pack` is a tool for building Rust-generated WebAssembly and publishing it to npm.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/docs/wasm.md#_snippet_0

LANGUAGE: Shell
CODE:
```
$ cargo install wasm-pack
$ wasm-pack build --target nodejs
```

----------------------------------------

TITLE: Building CKB Debugger for WASI with Rust
DESCRIPTION: This snippet provides the shell commands to add the `wasm32-wasip1` target to Rust and build the `ckb-debugger` project for WASI. It also includes a dependency for `gcc-multilib` which might be needed for some WASI builds on Linux.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/docs/wasm.md#_snippet_3

LANGUAGE: Shell
CODE:
```
$ rustup target add wasm32-wasip1
$ sudo apt install gcc-multilib
$ cargo build --target wasm32-wasip1
```

----------------------------------------

TITLE: Defining Fibonacci Function in C
DESCRIPTION: This C code defines a recursive `fib` function to calculate Fibonacci numbers and a `main` function that calls `fib(10)` and asserts the result is 55. It serves as an example program for profiling.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-vm-pprof/README.md#_snippet_0

LANGUAGE: C
CODE:
```
int fib(int n) {
    if (n == 0 || n == 1) {
        return n;
    } else {
        return fib(n-1) + fib(n-2);
    }
}

int main() {
    if (fib(10) != 55) {
        return 1;
    }
    return 0;
}
```

----------------------------------------

TITLE: Determining Function Call/Return Status in C
DESCRIPTION: This C snippet determines if a jump is a function call or a return. It checks if the next_pc matches a predefined @@LOW_PC@@ to identify a call, incrementing a reference count for the link address. For returns, it checks if the link address is within a valid range (@@LOW_PC@@ to @@HIGH_PC@@) and decrements a reference count associated with next_pc in a hash table (jump_from_addresses).
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/ckb-debugger/docs/probes.md#_snippet_5

LANGUAGE: C
CODE:
```
    int is_calling = 0;
    int is_returning = 0;
    if (next_pc == @@LOW_PC@@) {
        // Initialize reference of the link, increment refcount if neccesary. 
        jump_from_addresses.increment(link);
        is_calling = 1;
    }

    if (link > @@LOW_PC@@ && link <= @@HIGH_PC@@) {
        uint64_t *refcount = jump_from_addresses.lookup(&next_pc);
        (*refcount)--;
        if (*refcount == 0) {
            jump_from_addresses.delete(&next_pc);
        }
        is_returning = 1;
    }
```

----------------------------------------

TITLE: Installing Protobuf on macOS (Bash)
DESCRIPTION: This command installs the `protobuf` package using Homebrew on macOS. It is a prerequisite for compiling `ckb-vm-pprof-converter`, ensuring the `protoc` binary is available for compilation.
SOURCE: https://github.com/nervosnetwork/ckb-standalone-debugger/blob/develop/README.md#_snippet_1

LANGUAGE: bash
CODE:
```
$ brew install protobuf
```