Initial commit

2025-11-30 08:53:24 +08:00
commit a4d116219f
7 changed files with 1489 additions and 0 deletions
--- a/skills/breenix-github-workflow-authoring/SKILL.md
+++ b/skills/breenix-github-workflow-authoring/SKILL.md
@@ -0,0 +1,457 @@
+---
+name: github-workflow-authoring
+description: This skill should be used when creating or improving GitHub Actions CI/CD workflows for Breenix kernel development. Use for authoring new test workflows, optimizing existing CI pipelines, adding new test types, fixing workflow configuration issues, or adapting workflows for new kernel features.
+---
+
+# GitHub Workflow Authoring for Breenix
+
+Create and improve GitHub Actions workflows for Breenix OS kernel development and testing.
+
+## Purpose
+
+This skill provides patterns, templates, and best practices for authoring GitHub Actions workflows specifically for Breenix kernel development. It addresses the unique challenges of OS kernel CI/CD: QEMU virtualization, custom Rust targets, userspace binary building, timeout management, and kernel-specific test patterns.
+
+## When to Use This Skill
+
+Use this skill when:
+
+- **Creating new test workflows**: Adding CI for new kernel features or test suites
+- **Optimizing CI performance**: Reducing build times, improving caching, tuning timeouts
+- **Fixing CI failures**: Workflow configuration issues, missing dependencies, wrong environment
+- **Adapting workflows**: Modifying workflows for new kernel capabilities or test requirements
+- **Debugging CI issues**: Understanding why workflows fail, reproducing issues locally
+- **Adding test coverage**: Expanding CI to cover more kernel subsystems or scenarios
+
+## Key Breenix CI Patterns
+
+### Rust Toolchain Requirements
+
+Breenix requires specific Rust configuration:
+
+```yaml
+- name: Install Rust
+  uses: actions-rs/toolchain@v1
+  with:
+    toolchain: nightly-2025-06-24      # Pinned for consistency
+    override: true
+    target: x86_64-unknown-none        # Custom kernel target
+    components: rust-src, llvm-tools-preview
+```
+
+**Critical**: The Rust nightly version is pinned to avoid unexpected breakage from compiler changes.
+
+### System Dependencies
+
+All kernel tests require QEMU and supporting tools:
+
+```yaml
+- name: Install system dependencies
+  run: |
+    sudo apt-get update
+    sudo apt-get install -y \
+      qemu-system-x86 \
+      qemu-utils \
+      ovmf \
+      mtools \
+      dosfstools \
+      xorriso \
+      nasm \
+      lld
+```
+
+### Userspace Binary Building
+
+**CRITICAL**: Before running kernel tests that execute userspace code, userspace binaries must be built:
+
+```yaml
+- name: Build userspace tests
+  run: |
+    export PATH="$PATH:$(rustc --print sysroot)/lib/rustlib/x86_64-unknown-linux-gnu/bin"
+    cd userspace/tests
+    ./build.sh
+```
+
+Forgetting this step causes kernel tests to fail mysteriously!
+
+### Using xtask for Tests
+
+Breenix uses the `xtask` pattern for complex test workflows:
+
+```yaml
+- name: Run Ring-3 smoke test
+  run: cargo run -p xtask -- ring3-smoke
+```
+
+This handles:
+- Building the kernel with correct features
+- Starting QEMU with appropriate flags
+- Monitoring serial output for success signals
+- Timeout management (30s local, 60s CI)
+- Cleanup and artifact collection
+
+## Timeout Strategies
+
+Different workflows need different timeouts:
+
+```yaml
+jobs:
+  quick-test:
+    timeout-minutes: 20    # Build + simple smoke test
+
+  full-integration:
+    timeout-minutes: 45    # Complete test suite with shared QEMU
+
+  code-quality:
+    timeout-minutes: 15    # Clippy and static analysis
+```
+
+**Rule of thumb**: CI environments are 2-3x slower than local development machines. Budget accordingly.
+
+## Caching for Performance
+
+Proper caching reduces build times from ~10 minutes to ~2 minutes:
+
+```yaml
+- name: Cache cargo
+  uses: actions/cache@v4
+  with:
+    path: |
+      ~/.cargo/registry
+      ~/.cargo/git
+      target
+    key: cargo-${{ runner.os }}-${{ hashFiles('**/Cargo.lock') }}
+```
+
+Cache invalidates when `Cargo.lock` changes, ensuring fresh builds for dependency updates.
+
+## Log Artifact Upload
+
+Always upload logs, especially on failure:
+
+```yaml
+- name: Upload logs
+  if: always()        # Run even if previous steps failed
+  uses: actions/upload-artifact@v4
+  with:
+    name: breenix-logs
+    path: |
+      logs/*.log
+      target/xtask_ring3_smoke_output.txt
+      target/xtask_ring3_enosys_output.txt
+    if-no-files-found: ignore
+    retention-days: 7
+```
+
+This enables post-mortem analysis of failed runs.
+
+## Workflow Patterns
+
+### Pattern 1: Smoke Test (Fast Feedback)
+
+Runs on every push to provide quick feedback:
+
+```yaml
+name: Ring-3 Smoke Test
+
+on:
+  push:
+    branches: [ "**" ]
+  pull_request:
+
+jobs:
+  ring3-smoke:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Rust
+        # ... (see above)
+      - name: Cache cargo
+        # ... (see above)
+      - name: Install system dependencies
+        # ... (see above)
+      - name: Build userspace tests
+        # ... (see above)
+      - name: Run smoke test
+        run: cargo run -p xtask -- ring3-smoke
+      - name: Upload logs
+        if: always()
+        # ... (see above)
+```
+
+**Purpose**: Verify basic kernel functionality (boot, userspace execution) quickly.
+
+### Pattern 2: Code Quality (Static Analysis)
+
+Runs on kernel code changes:
+
+```yaml
+name: Code Quality
+
+on:
+  push:
+    paths:
+      - 'kernel/**'
+      - '.github/workflows/code-quality.yml'
+
+jobs:
+  clippy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Rust
+        with:
+          components: clippy, rust-src
+      - name: Run Clippy
+        run: |
+          cd kernel
+          cargo clippy --target x86_64-unknown-none \
+            -- -Dclippy::debug_assert_with_mut_call
+```
+
+**Purpose**: Catch code quality issues before they reach main branch.
+
+### Pattern 3: Manual Trigger (Expensive Tests)
+
+For tests that take too long to run on every commit:
+
+```yaml
+name: Full Integration Tests
+
+on:
+  workflow_dispatch:   # Only run manually
+
+jobs:
+  integration:
+    timeout-minutes: 45
+    # ... full test suite
+```
+
+**Purpose**: Comprehensive testing before releases or major merges.
+
+## Reference Files
+
+The skill includes reference material in the `references/` directory:
+
+- **`breenix-ci-patterns.md`**: Comprehensive CI patterns, timeout strategies, caching, success signals
+
+To reference these during workflow authoring:
+```bash
+cat github-workflow-authoring/references/breenix-ci-patterns.md
+```
+
+## Workflow Creation Process
+
+When creating a new workflow:
+
+1. **Identify the test type**: Smoke test, integration test, static analysis, etc.
+2. **Determine trigger**: Every push, PR only, manual, or path-specific
+3. **Set appropriate timeout**: Based on test complexity and CI overhead
+4. **Copy template from existing workflow**: Start with `ring3-smoke.yml` or `code-quality.yml`
+5. **Customize steps**: Add specific build steps, test commands, or checks
+6. **Add caching**: Use cargo cache unless testing cache-sensitive issues
+7. **Configure artifact upload**: Always include logs for debugging
+8. **Test locally first**: Use the same commands that will run in CI
+9. **Add to PR**: Update .github/workflows/ and create PR for review
+10. **Monitor first runs**: Watch for environment-specific issues
+
+## Common Workflow Issues and Fixes
+
+### Issue: "rustup: command not found"
+**Cause**: Rust toolchain not installed or wrong action version
+**Fix**: Use `actions-rs/toolchain@v1` or `dtolnay/rust-toolchain`
+
+### Issue: "error: target 'x86_64-unknown-none' may not be installed"
+**Cause**: Missing custom target
+**Fix**: Add `target: x86_64-unknown-none` to toolchain setup
+
+### Issue: "error: could not compile `bootloader`"
+**Cause**: Missing `rust-src` component
+**Fix**: Add `rust-src` to components list
+
+### Issue: "qemu-system-x86_64: command not found"
+**Cause**: QEMU not installed in CI environment
+**Fix**: Add qemu-system-x86 to apt-get install list
+
+### Issue: Test times out but works locally
+**Cause**: CI environment slower, or test hung
+**Fix**: Increase timeout-minutes or investigate kernel hang
+
+### Issue: Cache seems corrupted
+**Cause**: Cache key collision or partial build artifacts
+**Fix**: Change cache key (add version suffix) or clear cache
+
+### Issue: Userspace test fails with "file not found"
+**Cause**: Userspace binaries not built before kernel test
+**Fix**: Add userspace build step before kernel test runs
+
+## Advanced Patterns
+
+### Matrix Builds (Future)
+
+Test multiple configurations:
+
+```yaml
+strategy:
+  matrix:
+    mode: [uefi, bios]
+    features: [testing, production]
+
+steps:
+  - run: cargo run --bin qemu-${{ matrix.mode }} --features ${{ matrix.features }}
+```
+
+### Conditional Steps
+
+Skip steps based on conditions:
+
+```yaml
+- name: Upload logs
+  if: failure()   # Only on failure
+  # or
+  if: always()    # Always run
+  # or
+  if: success()   # Only on success
+```
+
+### Environment-Specific Behavior
+
+```yaml
+env:
+  CI: true
+  RUST_BACKTRACE: full
+  BREENIX_TIMEOUT: 60    # Used by xtask
+```
+
+## Best Practices
+
+1. **Pin Rust version**: Avoid unexpected breakage from nightly changes
+2. **Cache aggressively**: Cargo builds are slow, caching saves 5-8 minutes
+3. **Fail fast**: Set reasonable timeouts to avoid wasting CI minutes
+4. **Upload artifacts**: Always capture logs for post-mortem analysis
+5. **Test locally first**: Run the exact commands that CI will run
+6. **Use xtask**: Complex test logic belongs in xtask, not YAML
+7. **Monitor CI time**: If workflows exceed 20-30 minutes, consider splitting
+8. **Document workflows**: Add comments explaining non-obvious steps
+
+## Integration with Breenix Development
+
+When adding new kernel features that require CI testing:
+
+1. **Identify test requirements**: What needs to be verified?
+2. **Create or extend xtask**: Add new test command (e.g., `ring3-fork-test`)
+3. **Add workflow**: Either extend existing or create new workflow file
+4. **Add success signal**: Add kernel log marker for test completion
+5. **Update workflow docs**: Document the new test in CLAUDE.md or README
+
+## Example: Adding a New Test Workflow
+
+Let's say you want to add CI for testing the fork() syscall:
+
+```yaml
+name: Fork System Call Test
+
+on:
+  push:
+    paths:
+      - 'kernel/src/process/**'
+      - 'kernel/src/syscall/**'
+      - 'userspace/tests/fork_test*'
+
+jobs:
+  fork-test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust
+        uses: actions-rs/toolchain@v1
+        with:
+          toolchain: nightly-2025-06-24
+          override: true
+          target: x86_64-unknown-none
+          components: rust-src, llvm-tools-preview
+
+      - name: Cache cargo
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: cargo-${{ runner.os }}-fork-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y qemu-system-x86 ovmf nasm
+
+      - name: Build userspace tests
+        run: |
+          export PATH="$PATH:$(rustc --print sysroot)/lib/rustlib/x86_64-unknown-linux-gnu/bin"
+          cd userspace/tests
+          ./build.sh
+
+      - name: Run fork test
+        run: cargo run -p xtask -- fork-test
+
+      - name: Upload logs
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: fork-test-logs
+          path: |
+            logs/*.log
+            target/xtask_fork_test_output.txt
+          retention-days: 7
+```
+
+Then update `xtask/src/main.rs`:
+
+```rust
+#[derive(StructOpt)]
+enum Cmd {
+    Ring3Smoke,
+    Ring3Enosys,
+    ForkTest,  // New test
+}
+
+fn main() -> Result<()> {
+    match Cmd::from_args() {
+        Cmd::Ring3Smoke => ring3_smoke(),
+        Cmd::Ring3Enosys => ring3_enosys(),
+        Cmd::ForkTest => fork_test(),
+    }
+}
+
+fn fork_test() -> Result<()> {
+    // Similar to ring3_smoke but looks for fork-specific signals
+    // ...
+}
+```
+
+## Troubleshooting CI Failures
+
+When a workflow fails:
+
+1. **Download artifacts**: Get the log files from the Actions run
+2. **Search for errors**: Look for panic, double fault, timeout messages
+3. **Compare with local**: Run the exact same command locally
+4. **Check environment**: Verify Rust version, QEMU version, dependencies
+5. **Reproduce in clean environment**: Use Docker or fresh VM if needed
+6. **Use ci-failure-analysis skill**: Systematic analysis of CI failures
+
+## Summary
+
+GitHub workflow authoring for Breenix requires understanding:
+- Rust nightly toolchain with custom targets
+- QEMU-based kernel testing patterns
+- xtask for test orchestration
+- Timeout management for CI environments
+- Caching strategies for performance
+- Log artifact collection for debugging
+
+Always reference the existing workflows as templates, test locally before committing, and leverage the xtask pattern for complex test logic.
--- a/skills/breenix-github-workflow-authoring/references/breenix-ci-patterns.md
+++ b/skills/breenix-github-workflow-authoring/references/breenix-ci-patterns.md
@@ -0,0 +1,240 @@
+# Breenix CI/CD Patterns Reference
+
+## Core Requirements
+
+### Rust Toolchain
+- **Nightly version**: `nightly-2025-06-24` (pinned for consistency)
+- **Components**: `rust-src`, `llvm-tools-preview`
+- **Optional**: `clippy` for code quality checks
+- **Target**: `x86_64-unknown-none` for kernel builds
+
+### System Dependencies
+```bash
+sudo apt-get update
+sudo apt-get install -y \
+  qemu-system-x86 \
+  qemu-utils \
+  ovmf \
+  mtools \
+  dosfstools \
+  xorriso \
+  nasm \
+  lld
+```
+
+### Build Tools
+- **llvm-tools**: Add to PATH: `$(rustc --print sysroot)/lib/rustlib/x86_64-unknown-linux-gnu/bin`
+- **ld.lld**: Required for linking userspace binaries
+
+## Breenix-Specific Build Patterns
+
+### Userspace Binary Building
+Must be done before kernel tests that execute userspace code:
+
+```bash
+export PATH="$PATH:$(rustc --print sysroot)/lib/rustlib/x86_64-unknown-linux-gnu/bin"
+cd userspace/tests
+./build.sh
+```
+
+### Kernel Build with Testing Features
+```bash
+cargo run --release --features testing --bin qemu-uefi -- -serial stdio -display none
+```
+
+### Using xtask for Tests
+Breenix uses the `xtask` pattern for complex test workflows:
+
+```bash
+cargo run -p xtask -- ring3-smoke
+cargo run -p xtask -- ring3-enosys
+```
+
+## Timeout Strategies
+
+### Typical Timeouts
+- **Code quality checks**: 10-15 minutes
+- **Build + simple tests**: 20 minutes
+- **Full integration tests**: 45 minutes
+- **CI environment**: Add 2-3x overhead for slower runners
+
+### QEMU Execution Timeouts
+- **Local**: 30 seconds for smoke tests
+- **CI**: 60 seconds (logs are verbose, builds are slower)
+- **File creation**: 30s local, 300s (5 min) CI
+
+## Caching Strategies
+
+### Cargo Cache
+```yaml
+- uses: actions/cache@v4
+  with:
+    path: |
+      ~/.cargo/registry
+      ~/.cargo/git
+      target
+    key: cargo-${{ runner.os }}-${{ hashFiles('**/Cargo.lock') }}
+```
+
+### Benefits
+- Reduces build time from ~10 minutes to ~2 minutes
+- Especially important for dependency-heavy builds
+- Invalidates on Cargo.lock changes
+
+## Test Execution Patterns
+
+### Serial Output to File
+```yaml
+- name: Run test
+  run: cargo run -p xtask -- ring3-smoke
+```
+
+Internally, xtask uses:
+```rust
+-serial file:target/xtask_ring3_smoke_output.txt
+```
+
+### Log Artifact Upload
+```yaml
+- name: Upload logs
+  if: always()  # Run even on failure
+  uses: actions/upload-artifact@v4
+  with:
+    name: breenix-logs
+    path: |
+      logs/*.log
+      target/xtask_ring3_smoke_output.txt
+    if-no-files-found: ignore
+    retention-days: 7
+```
+
+## Success Detection Patterns
+
+### Looking for Signals in Output
+```rust
+// Check for userspace execution evidence
+if contents.contains("USERSPACE OUTPUT: Hello from userspace") ||
+   (contents.contains("Context switch: from_userspace=true, CS=0x33") &&
+    contents.contains("restore_userspace_thread_context: Restoring thread"))
+```
+
+### Common Success Signals
+- `USERSPACE OUTPUT: Hello from userspace`
+- `🎯 KERNEL_POST_TESTS_COMPLETE 🎯`
+- `Context switch: from_userspace=true, CS=0x33`
+- `✅ SUCCESS: Userspace syscall completed`
+
+### Common Failure Patterns
+- `DOUBLE FAULT` - Page table or stack issues
+- `PAGE FAULT` - Memory mapping problems
+- `Timeout` - Test hung or infinite loop
+- Build errors - Missing dependencies or wrong toolchain
+
+## Workflow Triggers
+
+### Current Patterns
+```yaml
+# Run on all branches
+on:
+  push:
+    branches: [ "**" ]
+  pull_request:
+
+# Run only manually (for expensive tests)
+on:
+  workflow_dispatch:
+
+# Run on specific paths
+on:
+  push:
+    paths:
+      - 'kernel/**'
+      - '.github/workflows/code-quality.yml'
+```
+
+## Environment Variables
+
+### Useful Vars
+```yaml
+env:
+  RUST_BACKTRACE: full
+  CARGO_UNSTABLE_BINDEPS: true  # For build dependencies
+  CI: true  # Detection for different timeouts
+```
+
+## Common Workflow Structure
+
+```yaml
+name: Test Name
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-22.04
+    timeout-minutes: 20
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust
+        uses: actions-rs/toolchain@v1
+        with:
+          toolchain: nightly-2025-06-24
+          override: true
+          target: x86_64-unknown-none
+          components: rust-src, llvm-tools-preview
+
+      - name: Cache cargo
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: cargo-${{ runner.os }}-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y qemu-system-x86 ovmf nasm
+
+      - name: Build userspace tests
+        run: |
+          export PATH="$PATH:$(rustc --print sysroot)/lib/rustlib/x86_64-unknown-linux-gnu/bin"
+          cd userspace/tests
+          ./build.sh
+
+      - name: Run test
+        run: cargo run -p xtask -- ring3-smoke
+
+      - name: Upload logs
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-logs
+          path: |
+            logs/*.log
+            target/xtask_*_output.txt
+          retention-days: 7
+```
+
+## Debugging Failed CI
+
+### Step 1: Check Logs
+Download artifacts from the Actions run, look for:
+- Compilation errors (wrong Rust version, missing components)
+- Missing system dependencies (QEMU, OVMF, etc.)
+- Timeout vs actual kernel panic
+
+### Step 2: Reproduce Locally
+```bash
+# Use exact same commands as CI
+cargo run -p xtask -- ring3-smoke
+```
+
+### Step 3: Common Fixes
+- **Rust version mismatch**: Update toolchain specification
+- **Missing QEMU**: Add to system dependencies
+- **Timeout**: Increase timeout or optimize test
+- **Userspace not built**: Add userspace build step before kernel test
+- **Cache corruption**: Clear cache or change cache key