playdate-symbolize

Crates.ioplaydate-symbolize
lib.rsplaydate-symbolize
version0.2.2
created_at2024-04-24 07:47:13.743447+00
updated_at2025-02-10 19:34:42.149453+00
descriptionTools for symbolise addresses from bin (pdex.elf) and Playdate's trace or crashlog.
homepagehttps://github.com/boozook/playdate
repositoryhttps://github.com/boozook/playdate.git
max_upload_size
id1218468
size162,367
Alex (boozook)

documentation

README

Symbolizer for Playdate

These tools helps symbolize addresses from your game's ELF file (pdex.elf) and Playdate's CPU-trace logs or crash logs.

Provided command-line utilities to make this process easier:

  • pd-addr2line - takes address, returns symbol with span
  • pd-symbolize-crashlog - takes crashlog.txt, returns symbolized crashlog
  • pd-symbolize-trace - takes trace-dump and symbolizing it

All of them have almost same interface.

Usage

The pd-addr2line can operate with stdin or file.

pd-addr2line --exe pdex.elf -Cfri 0xc0a 0x8053C75 10 0x6000027a 0x080bf518
echo "0x8053c75\n0x80bf518" | pd-addr2line --exe pdex.elf -Cfri

The pd-symbolize-crashlog can process crashlog file, currently stdin not supported.

pd-symbolize-crashlog --exe pdex.elf -Cfr /Volumes/PLAYDATE/crashlog.txt

The pd-symbolize-trace can operate with stdin or file. Parameter --exe is optional and usually not needed for traces, but 🤷🏻‍♂️.

export RUST_LOG="info" # prevent unnecessary logs from appearing in the output
pd-symbolize-trace -Cfri trace-dump.txt # parse file, without elf
pd-symbolize-trace --exe pdex.elf -Cfri trace-dump.txt # with elf
cat trace-dump.txt | pd-symbolize-trace --exe pdex.elf -Cfri # pipe
The above ☝🏻 snippet assumes that you have prepared a trace-dump...

⚠️ If you don't know what it is, you probably don't need it. Be careful and perform all actions at your own risk.

How to retrieve cpu-trace

  1. connect to device
  2. send command "trace", dump it to ./trace-dump.txt
  3. send "stoptrace"

How to do it using pdtool - see Usage with pdtool / Trace below.

All tools have --help parameter.

Usage with pdtool

The pdtool is a util for ease interaction with a device via USB.

Trace

pdtool send ! "trace 10" && pdtool read | pd-symbolize-trace --exe pdex.elf -Cfri | ./symbolized-trace.log
# ...
pdtool send ! stoptrace

Crashlog

pdtool mount --wait && pd-symbolize-crashlog --exe pdex.elf -Cfri /Volumes/PLAYDATE/crashlog.txt;
pdtool unmount

Install

You can grab the latest release or you can build your own.

Build

To build tools you need Rust nightly toolchain. Recomended version is there.

From crates.io:

cargo install playdate-symbolize

From the repo:

cargo install playdate-symbolize --git=https://github.com/boozook/playdate.git

Prerequisites

To symbolize pointers (or offsets) outside of your program you need Playdate SDK. Ensure that env var PLAYDATE_SDK_PATH points to the SDK root. This is optional, but good move to help the tool to find SDK, and also useful if you have more then one version of SDK.

Also you need your program - elf saved before packing into pdx.

This software is not sponsored or supported by Panic.

Commit count: 562

cargo fmt