Initial commit
This commit is contained in:
Zhongwei Li
221
skills/breenix-kernel-debug-loop/SKILL.md
Normal file
221
skills/breenix-kernel-debug-loop/SKILL.md
Normal file
@@ -0,0 +1,221 @@
|
||||
---
|
||||
name: kernel-debug-loop
|
||||
description: This skill should be used when performing fast iterative kernel debugging, running time-bound kernel sessions to detect specific log signals or test kernel behavior. Use for rapid feedback cycles during kernel development, boot sequence analysis, or feature verification.
|
||||
---
|
||||
|
||||
# Kernel Debug Loop
|
||||
|
||||
Fast iterative kernel debugging with signal detection and time-bounded execution.
|
||||
|
||||
## Purpose
|
||||
|
||||
This skill provides a rapid feedback loop for kernel development by running the Breenix kernel for short, time-bounded sessions (default 15 seconds) while monitoring logs in real-time for specific signals. The kernel terminates immediately when the expected signal is detected, or when the timeout expires, enabling fast iteration cycles during debugging.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when:
|
||||
|
||||
- **Iterative debugging**: Testing kernel changes with quick feedback loops
|
||||
- **Boot sequence analysis**: Verifying the kernel reaches specific initialization checkpoints
|
||||
- **Signal detection**: Waiting for specific kernel log messages before proceeding
|
||||
- **Behavior verification**: Confirming the kernel responds correctly to tests or inputs
|
||||
- **Fast failure detection**: Identifying boot failures or hangs quickly without waiting for full timeout
|
||||
- **Checkpoint validation**: Ensuring the kernel reaches expected states during execution
|
||||
|
||||
## How to Use
|
||||
|
||||
### Basic Usage
|
||||
|
||||
The skill provides the `quick_debug.py` script for time-bounded kernel runs with optional signal detection.
|
||||
|
||||
**Run kernel with signal detection:**
|
||||
|
||||
```bash
|
||||
kernel-debug-loop/scripts/quick_debug.py --signal "KERNEL_INITIALIZED"
|
||||
```
|
||||
|
||||
This runs the kernel for up to 15 seconds, terminating immediately when "KERNEL_INITIALIZED" appears in the logs.
|
||||
|
||||
**Run kernel with custom timeout:**
|
||||
|
||||
```bash
|
||||
kernel-debug-loop/scripts/quick_debug.py --timeout 30
|
||||
```
|
||||
|
||||
Runs the kernel for up to 30 seconds without specific signal detection.
|
||||
|
||||
**Run in BIOS mode:**
|
||||
|
||||
```bash
|
||||
kernel-debug-loop/scripts/quick_debug.py --signal "Boot complete" --mode bios
|
||||
```
|
||||
|
||||
**Quiet mode (kernel output only):**
|
||||
|
||||
```bash
|
||||
kernel-debug-loop/scripts/quick_debug.py --signal "READY" --quiet
|
||||
```
|
||||
|
||||
Suppresses progress messages, showing only kernel output.
|
||||
|
||||
### Common Signals to Watch For
|
||||
|
||||
Based on Breenix's test infrastructure, common signals include:
|
||||
|
||||
- `🎯 KERNEL_POST_TESTS_COMPLETE 🎯` - All runtime tests completed
|
||||
- `KERNEL_INITIALIZED` - Basic kernel initialization complete
|
||||
- `USER_PROCESS_STARTED` - User process execution began
|
||||
- `MEMORY_MANAGER_READY` - Memory management subsystem initialized
|
||||
- Custom checkpoint markers added for specific debugging needs
|
||||
|
||||
### Workflow Patterns
|
||||
|
||||
#### Pattern 1: Fast Iteration During Development
|
||||
|
||||
When making changes to kernel initialization:
|
||||
|
||||
1. Make code change
|
||||
2. Run: `kernel-debug-loop/scripts/quick_debug.py --signal "TARGET_CHECKPOINT" --timeout 10`
|
||||
3. Verify signal appears or analyze why it didn't
|
||||
4. Iterate
|
||||
|
||||
This provides feedback in ~10-15 seconds instead of waiting for full kernel execution or manual termination.
|
||||
|
||||
#### Pattern 2: Boot Sequence Verification
|
||||
|
||||
When debugging boot issues:
|
||||
|
||||
1. Identify the checkpoint expected to be reached
|
||||
2. Run with that checkpoint as the signal
|
||||
3. If timeout occurs, the kernel failed to reach that point
|
||||
4. Examine the output buffer to see how far boot progressed
|
||||
5. Add intermediate checkpoints to narrow down the failure point
|
||||
|
||||
#### Pattern 3: Regression Testing
|
||||
|
||||
When verifying fixes:
|
||||
|
||||
1. Run with the signal that was previously failing to appear
|
||||
2. Success (signal found) confirms the fix worked
|
||||
3. Failure (timeout) indicates the issue persists
|
||||
4. The output buffer contains diagnostic information
|
||||
|
||||
#### Pattern 4: Performance Checkpoint Analysis
|
||||
|
||||
When optimizing boot time:
|
||||
|
||||
1. Run with a specific checkpoint signal
|
||||
2. Note the elapsed time when signal is found
|
||||
3. Make optimization changes
|
||||
4. Re-run to measure improvement
|
||||
5. The script reports exact elapsed time for comparison
|
||||
|
||||
### Integration with Claude Workflows
|
||||
|
||||
When assisting with kernel debugging:
|
||||
|
||||
1. **Suggest checkpoints**: Recommend adding strategic log markers at key points
|
||||
2. **Run quick tests**: Use this script to verify changes before full test suite
|
||||
3. **Analyze output**: Parse the output buffer to diagnose issues
|
||||
4. **Iterate rapidly**: Chain multiple quick debug runs to test hypotheses
|
||||
5. **Report findings**: Summarize what signals were found and timing information
|
||||
|
||||
### Script Output
|
||||
|
||||
The script provides:
|
||||
|
||||
- **Real-time kernel output**: All kernel logs stream to stdout during execution
|
||||
- **Status indicators**: Visual feedback on signal detection and timeout
|
||||
- **Session summary**: Success/failure status, timing, and output statistics
|
||||
- **Exit code**: 0 if signal found (or no signal specified), 1 if timeout without signal
|
||||
|
||||
### Output Buffer Analysis
|
||||
|
||||
After a debug session, the entire kernel output is available for analysis:
|
||||
|
||||
- Search for error messages or warnings
|
||||
- Verify initialization sequence order
|
||||
- Check memory allocation patterns
|
||||
- Analyze interrupt handling
|
||||
- Examine test results
|
||||
|
||||
### Advanced Usage
|
||||
|
||||
**Multiple checkpoint verification:**
|
||||
|
||||
Run sequential sessions to verify a series of checkpoints:
|
||||
|
||||
```bash
|
||||
for signal in "PHASE1" "PHASE2" "PHASE3"; do
|
||||
kernel-debug-loop/scripts/quick_debug.py --signal "$signal" --quiet || break
|
||||
done
|
||||
```
|
||||
|
||||
**Capture output for analysis:**
|
||||
|
||||
```bash
|
||||
kernel-debug-loop/scripts/quick_debug.py --signal "READY" > kernel_output.log 2>&1
|
||||
```
|
||||
|
||||
**Integration with test scripts:**
|
||||
|
||||
```python
|
||||
import subprocess
|
||||
|
||||
result = subprocess.run(
|
||||
['kernel-debug-loop/scripts/quick_debug.py', '--signal', 'TEST_COMPLETE'],
|
||||
capture_output=True,
|
||||
text=True
|
||||
)
|
||||
|
||||
if result.returncode == 0:
|
||||
print("Test passed!")
|
||||
else:
|
||||
print("Test failed or timed out")
|
||||
analyze_output(result.stdout)
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Add strategic checkpoints**: Insert log markers at key kernel execution points
|
||||
2. **Use descriptive signals**: Make signal patterns unique and meaningful
|
||||
3. **Set appropriate timeouts**: Balance between waiting long enough and fast iteration
|
||||
4. **Check exit codes**: Use return codes in scripts for automation
|
||||
5. **Save output for analysis**: Redirect output when debugging complex issues
|
||||
6. **Start broad, narrow down**: If a checkpoint isn't reached, add earlier checkpoints
|
||||
7. **Combine with full tests**: Use for quick iteration, then validate with full test suite
|
||||
|
||||
## Technical Details
|
||||
|
||||
- **Timeout**: Default 15 seconds, configurable via `--timeout`
|
||||
- **Signal detection**: Performs substring matching on each output line
|
||||
- **Termination**: Graceful SIGTERM followed by SIGKILL if needed
|
||||
- **Output buffering**: Line-buffered for real-time display
|
||||
- **Exit codes**: 0 for success (signal found or no signal specified), 1 for timeout/failure
|
||||
|
||||
## Examples
|
||||
|
||||
**Verify kernel reaches user mode:**
|
||||
|
||||
```bash
|
||||
kernel-debug-loop/scripts/quick_debug.py --signal "USER_PROCESS_STARTED" --timeout 20
|
||||
```
|
||||
|
||||
**Quick sanity check after changes:**
|
||||
|
||||
```bash
|
||||
kernel-debug-loop/scripts/quick_debug.py --timeout 5
|
||||
```
|
||||
|
||||
**Debug memory initialization:**
|
||||
|
||||
```bash
|
||||
kernel-debug-loop/scripts/quick_debug.py --signal "MEMORY_MANAGER_READY" --quiet > mem_init.log
|
||||
```
|
||||
|
||||
**Test both UEFI and BIOS modes:**
|
||||
|
||||
```bash
|
||||
kernel-debug-loop/scripts/quick_debug.py --signal "BOOT_COMPLETE" --mode uefi
|
||||
kernel-debug-loop/scripts/quick_debug.py --signal "BOOT_COMPLETE" --mode bios
|
||||
```
|
||||
Reference in New Issue
Block a user