KW-DEBUG(1)

🌸 kw-debug — Kernel debug() 💅

okay bestie, welcome to the manual page for kw-debug (that's the kw debug command, and yes it lives in section 1 of your man pages, iykyk) ✨

---

🦋 SYNOPSIS

kw debug [(-e | --event) <event-syntax> [(-d | --disable)] [(-k | --history)] [(-f | --follow)] ]
kw debug [(-t | --ftrace)]
kw debug [(-g | --dmesg) [(-f | --follow)] [(-c | --cmd) "COMMAND"] ]
kw debug [(-l | --list)[=(<ftrace> | <events>)]] [(-e | --event)]
kw debug [--reset]
kw debug [(-h | --help)]
kw debug [(--verbose)]

---

🎀 DESCRIPTION

so basically, the Linux kernel ships with like multiple mechanisms for debugging, and kw is out here trying to make three of them not be a whole ordeal: events, ftrace, and dmesg. And all of these debug options? They're built to support both remote and local targets. periodt. 💖

✨ EVENTS TRACE

to actually use the event feature that kw wraps up all cute for you, you gotta follow this little syntax first. it's giving grammar homework but it's worth it:

event[:<specific-event[[filter]]>[,<specific-event[[filter]]>,...]][;event...]

okay let's break that down step-by-step, no cap:

• event: this should be an event that actually exists in your kernel, like for example /sys/kernel/debug/tracing/events/amdgpu_dm. And if you're sitting there like "bestie what events do I even have" — that's literally what the list option is for 🫶. Oh also, you can pass multiple events by separating them with ';'.
• specific-event: inside each event (the one you told it via event), you get to pick which specific event you actually want to look at. like, inside amdgpu_dm there's amdgpu_dm_dc_clocks_state, which translates to "amdgpu_dm:amdgpu_dm_dc_clocks_state". slay.
• filter: usually every event supports filters, and you can set one via kw debug using the filter syntax. for example: amdgpu_dm:amdgpu_dm_dce_clocks_state[sclk_khz > 0].

and notice — you have a flexible way of defining which events you want to trace with this event syntax. also the debug option comes with extra features that make working with debug data from the Linux Kernel way less painful. iconic honestly 💅

🌸 FTRACE TRACE

the kernel has this feature called ftrace that lets developers get a high-level view of code execution. kw wraps it under the --ftrace option. And if you don't give it any output, kw will display all available ftrace options.

the ftrace debug feature gives you different trace algorithms (peep all the options via the --list option) and it simplifies the output. The --ftrace option wraps these two configs using this syntax:

ftrace_type[:filter[,filter, ...]]

let's look real close at that:

• ftrace_type: use this to say which ftrace algorithm you wanna use.
• filter: ftrace lets you filter its output. this sets specific function names, or even a pattern filtered by ftrace. and yeah — you can pass multiple filters, just separate them with commas, bestie.

💜 DMESG LOG

the dmesg log is vital for debugging issues in the Linux kernel, and kw debug gives you the --dmesg option to help developers grab that info fast. and btw this feature works in the local and remote context. no cap.

🧚 LIST

there are a lot of debug options hanging out under ftrace and event. that's why kw debug has the list feature — it's the one responsible for showing you what's available. If you use --list with no parameters, kw shows you all ftrace algorithms and events options. You can also hand it a specific debug option via ftrace or event. And specifically — if you want to list details about one particular event, you can use event:TARGET_EVENT 👑

💀 RESET

so when users cancel some of the debug operations, we sometimes end up in a situation where some configurations get accidentally left set, and that can cause problems when you try to use the debug option a second time. It's especially common to end up with a hung process in the trace_pipe file 😭. The --reset option is the one responsible for resetting and killing any debug option process. it's the cleanup bestie.

---

🎀 OPTIONS

• -d, --disable — Disable all events specified inside --event "" and --ftrace. Heads up: this one does not apply to the --dmesg option.
• -l, --list[=(<ftrace> | <events>)] — If you use it together with the event option, it lists all available events. And if a specific event is informed via --events "<event>", this option will only list specific events related to that "<event>". Also: this feature does not apply to the --dmesg option.
• -k, --history — Creates a debug directory that keeps track of every debug the users have made. It creates a directory and organizes it based on an ID and a date. keeping receipts, fr fr 💖
• -f, --follow — Real time output. literally watching it happen live ✨
• -c, --cmd — If you use this alongside --event or --ftrace, here's the sequence: (1) Enable specific trace, (2) collect trace in background, (3) run the command, (4) disable traces. But when it's used with --dmesg, kw will (1) clean the dmesg log, (2) run the command, (3) and collect the log.
• --verbose — Verbose mode makes the kw program display debug messages so you can track its steps. Honestly super useful during the debugging process — it lets you spot possible errors way more easily 🫶.

---

🌈 EXAMPLES

for this whole set, let's just pretend you're debugging the AMD GPU driver. iconic of you. you can start by trying to learn what options you even have via:

kw debug --list

that command shows all the debug options available in the target kernel. Now that you can see everything available, let's say you've got the amdgpu driver — you can list its specific events with:

kw debug --list --event "amdgpu_dm"

you can also use:

kw debug --list="ftrace"
kw debug --list="events:amdgpu_dm"

now that you found all the trace options available for your target driver, you can enable that event trace and follow it in real-time with something like:

kw debug --event "amdgpu_dm:amdgpu_dm_atomic_update_cursor" --follow

if you want to save the trace output in a log file, use the --history flag:

kw debug --event "amdgpu_dm:amdgpu_dm_atomic_update_cursor" --follow --history

and if you interrupt the above command with Ctrl+C, kw will disable the target event on the target machine. Basically, something like the command below gets executed:

kw debug --event "amdgpu_dm" --disable

another powerful debug trick is the --cmd option — it makes kw enable the target trace, execute a specific command, disable the trace at the end, and bring the log to the host machine:

kw debug --event "amdgpu_dm:amdgpu_dm_dce_clocks_state[sclk_khz > 0]" --cmd "DO SOMETHING"

if you want to see the dmesg log from the target machine, you can use:

kw debug --dmesg

for keeping following the dmesg log and saving it locally, you can use:

kw debug --dmesg --follow --history

let's say you want to run a command on a remote machine and collect the dmesg log after the command execution:

kw debug --dmesg --cmd "/home/user/specific_app"

suppose you have an AMD and you want to track the display manager's behavior — use this:

kw debug --ftrace="function_graph:amdgpu_dm*" --follow --history

if you want to run a command and capture the ftrace:

kw debug --ftrace="function_graph:amdgpu_dm_*" --cmd="/root/igt-build/tests/kms_atomic --run-subtest test-only" --history

and to reset the debug option back to its default:

kw debug --reset

---

💖 quick vibe check: when something here is dangerous or says it "might cause problems", that's not me being dramatic — that's the page saying it. respect the caveats, bestie 🙈

---

and that's the whole page, bestie 🎀 this cutie came to you from the kw-debug - Kernel debug() corner of the world — source and version info live right there in the footer, so go check the doc itself for the date, mwah 💋✨