tools

Developer utilities for CopperlineOS.
This repo contains small, focused command-line tools that make it easy to poke at CopperlineOS services, send messages over ports, inspect timelines, and debug buffers. All tools are designed to be scriptable, safe defaults, and friendly for demos.

TL;DR: portctl to talk to services, timeline-inspect to watch frames, dmabuf-dump to debug surfaces, latency-meter for timing, and copper-asm for Copper programs (validate/assemble).

---

What’s inside (Phase-0)

Tool	Purpose	Status
portctl	Send JSON requests to a service port (Unix socket), read responses/events, pass FDs.	✅ MVP
timeline-inspect	Subscribe to copperd/compositord events and render a live textual timeline/jitter stats.	✅ MVP
dmabuf-dump	Print metadata about a DMABUF (format/stride/modifier) or raw file buffer.	✅ MVP
latency-meter	Measure port round-trip latency and vsync jitter under load.	✅ MVP
copper-asm	Validate/pretty-print Copper JSON; future: assemble JSON → binary ring format.	✅ MVP (validate)

All tools are implemented in Rust for a uniform build; no big runtime dependencies.

---

Layout

tools/
├─ portctl/              # CLI to send/recv JSON over ports (+ FD passing)
├─ timeline-inspect/     # Live view of vsync/IRQ/pageflip, jitter histograms
├─ dmabuf-dump/          # Inspect DMABUF/RAW buffers
├─ latency-meter/        # Port RTT and vsync jitter measurement
├─ copper-asm/           # Copper program validator/formatter (assembler later)
└─ Cargo.toml            # Workspace manifest

---

Install

Option A: Build all tools

git clone https://github.com/CopperlineOS/tools
cd tools
cargo build --release
# Binaries in ./target/release

Option B: Install a single tool

cargo install --path portctl
# or
cargo install --path dmabuf-dump

Requires Rust stable (see each tool’s README for minimal version).

---

portctl — talk to a service port

Send one JSON request and print the response:

portctl /run/copperline/copperd.sock '{"cmd":"ping"}'
# → {"ok":true,"name":"copperd","version":"0.1.0","protocol":0}

Subscribe to an event stream:

portctl /run/copperline/compositord.sock   '{"cmd":"subscribe","events":["vsync"]}' --stream

Create a layer and bind a debug image:

portctl /run/copperline/compositord.sock '{"cmd":"create_layer"}'
portctl /run/copperline/compositord.sock   '{"cmd":"bind_image","id":1,"path":"/tmp/sprite.rgba","w":128,"h":128,"format":"RGBA8"}'

Attach file descriptors (SCM_RIGHTS):

# Example: send a DMABUF FD (index 0) to compositord
# The JSON references fd_index:0; the actual FD is attached with --fd /proc/self/fd/<n> or a path.
portctl /run/copperline/compositord.sock   '{"cmd":"bind_dmabuf","id":1,"w":128,"h":128,"format":"RGBA8","stride":512,"fd_index":0}'   --fd /proc/self/fd/17

Common flags: --pretty (pretty-print JSON), --timeout 2000, --cap TOKEN (capability token), --stream (don’t exit after first response).

---

timeline-inspect — watch timing live

Subscribe to vsync, pageflip, and irq events and render a simple textual timeline plus jitter stats.

# compositor timing
timeline-inspect --socket /run/copperline/compositord.sock --events vsync,pageflip

# copper program IRQS per frame
timeline-inspect --socket /run/copperline/copperd.sock --events irq

Output (example):

frame 4242  vsync @ 12345678us   Δ=16.70ms  jitter=+0.13ms
frame 4243  vsync @ 12345695us   Δ=16.67ms  jitter=-0.03ms
...
irq tick    prog=42 @ 12345710us

Flags: --hist (print histogram periodically), --window 200 (sample size).

---

dmabuf-dump — inspect buffers

dmabuf-dump --fd 17
# format=RGBA8 stride=7680 w=1920 h=1080 modifier=LINEAR
dmabuf-dump --file /tmp/sprite.rgba --w 128 --h 128 --format RGBA8 --stride 512

Useful to verify what you’re binding to compositord or blitterd.

---

latency-meter — measure RTT & jitter

# Round-trip request/response latency against copperd
latency-meter --socket /run/copperline/copperd.sock --cmd '{"cmd":"ping"}' --count 2000

# Vsync jitter while CPU/GPU are busy (optional stress modes)
latency-meter --vsync --socket /run/copperline/compositord.sock --duration 10s --stress cpu,gpu

Reports min/mean/p95/p99 and a simple histogram; can emit NDJSON for ingestion.

---

copper-asm — validate/format (assemble later)

# Validate Copper JSON and pretty-print
copper-asm validate demo.json
copper-asm fmt demo.json > demo.pretty.json

# Planned
copper-asm assemble demo.json --out demo.cbin   # binary ring format (future)

Validation checks op names/fields, label targets, and register names.

---

Environment & discovery

Most tools default to well-known sockets; override via env vars:

• COPPERD_SOCKET — /run/copperline/copperd.sock
• COMPOSITORD_SOCKET — /run/copperline/compositord.sock
• BLITTERD_SOCKET — /run/copperline/blitterd.sock
• AUDIOMIXERD_SOCKET — /run/copperline/audiomixerd.sock

---

Building from source

rustup default stable
rustup component add rustfmt clippy
cargo fmt --all
cargo clippy --all-targets -- -D warnings
cargo test

Many tools have zero tests initially—add golden tests for request/response envelopes as they land.

---

Contributing

• Keep tools small and no-setup (single binary, clear --help).
• Add examples in each tool’s README and ensure they work with the current services.
• For new flags or output fields, document them and provide a --json machine mode if applicable.

See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

---

License

Dual-licensed under Apache-2.0 OR MIT.

---

See also

• ports — message-port protocol & client libs
• copperd · compositord · blitterd · audiomixerd