Feature/clear readmes

.editorconfig

@@ -0,0 +1,28 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+trim_trailing_whitespace = true
+
+[*.{sh,bash}]
+indent_style = tab
+
+[Makefile]
+indent_style = tab
+
+[Kbuild]
+indent_style = tab
+
+[*.{json,md,yml,yaml}]
+indent_style = space
+indent_size = 2
+
+[*.{c,h}]
+indent_style = tab
+indent_size = 8
+
+[*.ps1]
+indent_style = space
+indent_size = 4

.github/workflows/lint.yml

@@ -0,0 +1,113 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  shellcheck:
+    name: shellcheck + bash -n
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install shellcheck
+        run: sudo apt-get update && sudo apt-get install -y shellcheck
+
+      - name: bash -n (syntax check)
+        run: |
+          for f in scripts/lib/*.sh scripts/0*.sh; do
+            echo "::group::bash -n $f"
+            bash -n "$f"
+            echo "::endgroup::"
+          done
+
+      - name: shellcheck
+        run: shellcheck -x scripts/lib/common.sh scripts/0*.sh
+
+  json:
+    name: validate JSON
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: validate .vscode/*.json
+        run: |
+          for f in .vscode/*.json; do
+            echo "::group::python -m json.tool $f"
+            python3 -m json.tool "$f" > /dev/null
+            echo "::endgroup::"
+          done
+
+  makefile:
+    name: Makefile syntax
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: make help (dry-parse)
+        run: make help
+
+  build:
+    name: build example module against runner kernel (${{ matrix.os }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-22.04, ubuntu-24.04, ubuntu-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: install host kernel headers + build tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            build-essential \
+            bc bison flex libelf-dev libssl-dev \
+            "linux-headers-$(uname -r)"
+
+      - name: use the example module
+        run: make use-example NAME=chuck_norise
+
+      - name: build via top-level Makefile (default target)
+        # KDIR defaults to /lib/modules/$(uname -r)/build when there's no
+        # .kernel-cache/current, so this exercises the full prepare-build +
+        # KCFLAGS pipeline against a real (the runner's) kernel.
+        run: make modules
+
+      - name: assert a .ko was produced
+        run: |
+          set -e
+          shopt -s nullglob
+          kos=(build/artifacts/*/*/*.ko)
+          if [ "${#kos[@]}" -eq 0 ]; then
+            echo "::error::no .ko produced under build/artifacts/"
+            ls -R build/ || true
+            exit 1
+          fi
+          for ko in "${kos[@]}"; do
+            echo "built $ko ($(stat -c %s "$ko") bytes)"
+            file "$ko"
+          done
+
+      - name: verify DWARF prefix-map rewrote paths back to module/
+        # The whole point of -ffile-prefix-map is that DWARF references your
+        # source under module/<...>.c, not build/intermediate/<...>.c. If a
+        # change to the Makefile breaks the injection, this catches it.
+        run: |
+          set -e
+          ko=$(find build/artifacts -name '*.ko' | head -1)
+          if objdump --dwarf=decodedline "$ko" 2>/dev/null \
+              | grep -qE '/build/intermediate/'; then
+            echo "::error::DWARF still references build/intermediate/ — prefix-map broken"
+            objdump --dwarf=decodedline "$ko" 2>/dev/null | grep -E '/build/intermediate/' | head
+            exit 1
+          fi
+          echo "ok: DWARF paths point at module/"
+
+      - name: clean-module resets cleanly
+        run: |
+          make clean-module
+          ls module/
+          [ "$(ls module/)" = "README.md" ] || { echo "::error::clean-module did not reduce module/ to just README.md"; exit 1; }

.gitignore

@@ -1,11 +1,16 @@
+# Per-machine config (lab.example.env is the tracked template).
 lab.local.env
 
+# Per-target synced kernel headers, source, vmlinux.
 .kernel-cache/
-.gdb/*.gdb
-.gdb/*.ready
-.gdb/*.log
+
+# Generated GDB init files (regenerated by scripts/04 on every F5).
+.gdb/
+
+# Per-target build intermediates and final .ko artifacts.
 build/
 
+# Kbuild stragglers in case anything runs out of place.
 *.ko
 *.mod
 *.mod.c
@@ -14,6 +19,13 @@ build/
 Module.symvers
 modules.order
 
+# IDE / editor noise.
 .vscode/ipch/
 .codex
+.claude/
 
+# Agent / session local notes (CLAUDE.md is consumed by Claude Code; keep it
+# out of the public repo so workflow guidance stays separate from user docs).
+CLAUDE.md
+session.md
+todo.md

.vscode/c_cpp_properties.json

@@ -3,20 +3,19 @@
   "configurations": [
     {
       "name": "Linux kernel module - current",
-      "compilerPath": "/usr/bin/gcc-13",
+      "compilerPath": "/usr/bin/gcc",
       "intelliSenseMode": "linux-gcc-x64",
       "cStandard": "gnu11",
       "defines": [
         "__KERNEL__",
         "MODULE",
         "CC_USING_FENTRY",
-        "KBUILD_MODNAME=\"hello\"",
-        "KBUILD_BASENAME=\"hello\"",
-        "__KBUILD_MODNAME=kmod_hello"
+        "KBUILD_MODNAME=\"kmod\"",
+        "KBUILD_BASENAME=\"kmod\"",
+        "__KBUILD_MODNAME=kmod_kmod"
       ],
       "includePath": [
-        "${workspaceFolder}/module/include",
-        "${workspaceFolder}/module/src",
+        "${workspaceFolder}/module/**",
         "${workspaceFolder}/.kernel-cache/current/build/include",
         "${workspaceFolder}/.kernel-cache/current/build/include/uapi",
         "${workspaceFolder}/.kernel-cache/current/build/include/generated",
@@ -29,8 +28,7 @@
       ],
       "browse": {
         "path": [
-          "${workspaceFolder}/module/include",
-          "${workspaceFolder}/module/src",
+          "${workspaceFolder}/module",
           "${workspaceFolder}/.kernel-cache/current/build/ubuntu/include",
           "${workspaceFolder}/.kernel-cache/current/build/include",
           "${workspaceFolder}/.kernel-cache/current/build/arch/x86/include"
@@ -42,90 +40,6 @@
         "${workspaceFolder}/.kernel-cache/current/build/include/linux/kconfig.h",
         "${workspaceFolder}/.kernel-cache/current/build/include/linux/compiler_types.h"
       ]
-    },
-    {
-      "name": "Linux kernel module - desktop",
-      "compilerPath": "/usr/bin/gcc-13",
-      "intelliSenseMode": "linux-gcc-x64",
-      "cStandard": "gnu11",
-      "defines": [
-        "__KERNEL__",
-        "MODULE",
-        "CC_USING_FENTRY",
-        "KBUILD_MODNAME=\"hello\"",
-        "KBUILD_BASENAME=\"hello\"",
-        "__KBUILD_MODNAME=kmod_hello"
-      ],
-      "includePath": [
-        "${workspaceFolder}/module/include",
-        "${workspaceFolder}/module/src",
-        "${workspaceFolder}/.kernel-cache/desktop/build/include",
-        "${workspaceFolder}/.kernel-cache/desktop/build/include/uapi",
-        "${workspaceFolder}/.kernel-cache/desktop/build/include/generated",
-        "${workspaceFolder}/.kernel-cache/desktop/build/include/generated/uapi",
-        "${workspaceFolder}/.kernel-cache/desktop/build/ubuntu/include",
-        "${workspaceFolder}/.kernel-cache/desktop/build/arch/x86/include",
-        "${workspaceFolder}/.kernel-cache/desktop/build/arch/x86/include/uapi",
-        "${workspaceFolder}/.kernel-cache/desktop/build/arch/x86/include/generated",
-        "${workspaceFolder}/.kernel-cache/desktop/build/arch/x86/include/generated/uapi"
-      ],
-      "browse": {
-        "path": [
-          "${workspaceFolder}/module/include",
-          "${workspaceFolder}/module/src",
-          "${workspaceFolder}/.kernel-cache/desktop/build/ubuntu/include",
-          "${workspaceFolder}/.kernel-cache/desktop/build/include",
-          "${workspaceFolder}/.kernel-cache/desktop/build/arch/x86/include"
-        ],
-        "limitSymbolsToIncludedHeaders": true
-      },
-      "forcedInclude": [
-        "${workspaceFolder}/.kernel-cache/desktop/build/include/linux/compiler-version.h",
-        "${workspaceFolder}/.kernel-cache/desktop/build/include/linux/kconfig.h",
-        "${workspaceFolder}/.kernel-cache/desktop/build/include/linux/compiler_types.h"
-      ]
-    },
-    {
-      "name": "Linux kernel module - server",
-      "compilerPath": "/usr/bin/gcc-13",
-      "intelliSenseMode": "linux-gcc-x64",
-      "cStandard": "gnu11",
-      "defines": [
-        "__KERNEL__",
-        "MODULE",
-        "CC_USING_FENTRY",
-        "KBUILD_MODNAME=\"hello\"",
-        "KBUILD_BASENAME=\"hello\"",
-        "__KBUILD_MODNAME=kmod_hello"
-      ],
-      "includePath": [
-        "${workspaceFolder}/module/include",
-        "${workspaceFolder}/module/src",
-        "${workspaceFolder}/.kernel-cache/server/build/include",
-        "${workspaceFolder}/.kernel-cache/server/build/include/uapi",
-        "${workspaceFolder}/.kernel-cache/server/build/include/generated",
-        "${workspaceFolder}/.kernel-cache/server/build/include/generated/uapi",
-        "${workspaceFolder}/.kernel-cache/server/build/ubuntu/include",
-        "${workspaceFolder}/.kernel-cache/server/build/arch/x86/include",
-        "${workspaceFolder}/.kernel-cache/server/build/arch/x86/include/uapi",
-        "${workspaceFolder}/.kernel-cache/server/build/arch/x86/include/generated",
-        "${workspaceFolder}/.kernel-cache/server/build/arch/x86/include/generated/uapi"
-      ],
-      "browse": {
-        "path": [
-          "${workspaceFolder}/module/include",
-          "${workspaceFolder}/module/src",
-          "${workspaceFolder}/.kernel-cache/server/build/ubuntu/include",
-          "${workspaceFolder}/.kernel-cache/server/build/include",
-          "${workspaceFolder}/.kernel-cache/server/build/arch/x86/include"
-        ],
-        "limitSymbolsToIncludedHeaders": true
-      },
-      "forcedInclude": [
-        "${workspaceFolder}/.kernel-cache/server/build/include/linux/compiler-version.h",
-        "${workspaceFolder}/.kernel-cache/server/build/include/linux/kconfig.h",
-        "${workspaceFolder}/.kernel-cache/server/build/include/linux/compiler_types.h"
-      ]
     }
   ]
 }

.vscode/extensions.json

@@ -1,6 +1,6 @@
 {
   "recommendations": [
-    "ms-vscode.cpptools"
+    "ms-vscode.cpptools",
+    "webfreak.debug"
   ]
 }
-

.vscode/launch.json

@@ -1,45 +1,47 @@
 {
   "version": "0.2.0",
+  "inputs": [
+    {
+      "id": "debugEndpoint",
+      "type": "promptString",
+      "description": "GDB remote endpoint (host:port). Only used by Native Debug — cppdbg reads it from the generated .gdb script.",
+      "default": "127.0.0.1:1234"
+    }
+  ],
   "configurations": [
     {
-      "name": "Kernel: Debug server",
+      "name": "Kernel: cppdbg (full GDB MI)",
       "type": "cppdbg",
       "request": "launch",
-      "program": "${workspaceFolder}/.kernel-cache/server/vmlinux",
+      "program": "${workspaceFolder}/.gdb/current-vmlinux",
       "cwd": "${workspaceFolder}",
       "MIMode": "gdb",
       "miDebuggerPath": "gdb",
       "targetArchitecture": "x64",
-      "preLaunchTask": "Kernel: Deploy Debug server",
+      "preLaunchTask": "Kernel: Deploy Debug",
       "setupCommands": [
         {
-          "description": "Attach KGDB and trigger deferred module load",
-          "text": "source ${workspaceFolder}/.gdb/server-kgdb.gdb",
+          "description": "Source the GDB init script generated by scripts/04",
+          "text": "source ${workspaceFolder}/.gdb/current-debug.gdb",
           "ignoreFailures": false
         }
       ],
       "launchCompleteCommand": "exec-continue",
       "externalConsole": false
     },
     {
-      "name": "Kernel: Debug desktop",
-      "type": "cppdbg",
-      "request": "launch",
-      "program": "${workspaceFolder}/.kernel-cache/desktop/vmlinux",
+      "name": "Kernel: Native Debug (faster, fewer features)",
+      "type": "gdb",
+      "request": "attach",
+      "executable": "${workspaceFolder}/.gdb/current-vmlinux",
+      "target": "${input:debugEndpoint}",
+      "remote": true,
       "cwd": "${workspaceFolder}",
-      "MIMode": "gdb",
-      "miDebuggerPath": "gdb",
-      "targetArchitecture": "x64",
-      "preLaunchTask": "Kernel: Deploy Debug desktop",
-      "setupCommands": [
-        {
-          "description": "Attach KGDB and trigger deferred module load",
-          "text": "source ${workspaceFolder}/.gdb/desktop-kgdb.gdb",
-          "ignoreFailures": false
-        }
-      ],
-      "launchCompleteCommand": "exec-continue",
-      "externalConsole": false
+      "preLaunchTask": "Kernel: Deploy Debug",
+      "valuesFormatting": "parseText",
+      "autorun": [
+        "source ${workspaceFolder}/.gdb/current-debug-attached.gdb"
+      ]
     }
   ]
 }