Update docs for 0.11.0 and include new changes - #119
Merged
Merged
Conversation
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (3)
📝 WalkthroughWalkthroughCardwire’s documentation now covers its product model, supported environments, installation paths, Smart Mode behavior, development architecture, Mermaid rendering, and NVIDIA troubleshooting. ChangesDocumentation and Mermaid guidance
Estimated code review effort: 2 (Simple) | ~10 minutes Sequence Diagram(s)sequenceDiagram
participant Process
participant eBPF
participant UserspaceAnalyzer
participant CardwireDaemon
Process->>eBPF: Emit exec event
eBPF->>UserspaceAnalyzer: Publish process event
UserspaceAnalyzer->>CardwireDaemon: Update allowed PID state
CardwireDaemon->>Process: Permit or block GPU access
Process->>eBPF: Emit exit event
eBPF->>CardwireDaemon: Publish cleanup event
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/getting-started/installation.md (1)
139-141: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winScope this fallback to supported systemd distributions.
The requirements document states that non-systemd distros are unsupported, but this section tells “other distros” to build and install Cardwire without that restriction. A non-systemd user could follow these steps into an unsupported setup; explicitly require systemd here or rename the section accordingly.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/getting-started/installation.md` around lines 139 - 141, Update the “Other distros” installation guidance to explicitly limit this fallback to distributions using systemd, matching the documented support requirements. Either rename the section to identify supported systemd distributions or add an equivalent systemd prerequisite to the existing clone, make, and BPF LSM instructions.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/diagnostics/troubleshooting.md`:
- Around line 46-54: Update the “nvidia-powerd failure after switching modes”
troubleshooting guidance to scope the restart remedy to systems supporting
NVIDIA Dynamic Boost and where the nvidia-powerd.service unit exists. Clarify
that users on unsupported systems should not run the restart command, while
preserving the existing command for applicable systems.
In `@docs/getting-started/installation.md`:
- Around line 103-117: Update the BPF LSM link in the Ubuntu/Debian installation
instructions to use the generated anchor for the “Enabling BPF LSM (with GRUB)”
heading, `#enabling-bpf-lsm-with-grub`, while leaving the surrounding
installation steps unchanged.
In `@docs/getting-started/requirements.md`:
- Around line 49-53: Update the BPF verification guidance in “Verify BPF is in
the boot cmdline” to distinguish kernel configuration from runtime state:
describe CONFIG_BPF_LSM and CONFIG_LSM outputs as showing built-in/default LSM
support and order only, and identify /proc/cmdline as the source of truth for
whether bpf is active. Preserve the existing GRUB example that appends bpf.
In `@docs/getting-started/usage.md`:
- Line 59: Update the Smart mode description to hyphenate “real-time” when
describing the analyzer, without changing the surrounding wording.
---
Outside diff comments:
In `@docs/getting-started/installation.md`:
- Around line 139-141: Update the “Other distros” installation guidance to
explicitly limit this fallback to distributions using systemd, matching the
documented support requirements. Either rename the section to identify supported
systemd distributions or add an equivalent systemd prerequisite to the existing
clone, make, and BPF LSM instructions.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 81a27fc8-1b0d-4b45-be8c-e467479dd481
📒 Files selected for processing (5)
docs/diagnostics/troubleshooting.mddocs/getting-started/installation.mddocs/getting-started/requirements.mddocs/getting-started/usage.mddocs/introduction.md
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/development/bpf.md`:
- Around line 11-12: Add a blank line immediately after each affected Markdown
heading, including the “LSM Hooks” heading and the heading at the referenced
second section, to satisfy MD022 while preserving the existing section content.
- Around line 39-41: Update docs/development/bpf.md lines 39-41 to retain the
dirent-length filtering explanation and explicitly state that blocked GPUs are
omitted from directory listings rather than causing an error. Update
docs/development/smart.md lines 51-61 by separating the getdents64 listing
behavior from file_open access behavior, documenting the former as hiding
entries and the latter with its correct -ENOENT result.
- Around line 29-35: Unify the Smart-mode state machine by defining one
canonical mapping for environment flags, analyzer outcomes, cw_allowed_pid
values, and GPU visibility, then apply it consistently at
docs/development/bpf.md:29-35, docs/development/smart.md:21-23,
docs/development/smart.md:55-61, and docs/development/switcheroo.md:41-53.
Update the cw_allowed_pid documentation, analyzer and environment-variable
semantics, Mermaid branches, and CARDWIRE_FORCE_DGPU/CARDWIRE_ALLOW behavior to
match that single mapping.
In `@docs/development/dbus.md`:
- Around line 7-8: Update the SwitcherooControl note link in dbus.md to
reference switcheroo.md, matching the added documentation file and SUMMARY.md
entry.
In `@docs/development/switcheroo.md`:
- Around line 15-16: Add blank lines after every affected subsection heading in
docs/development/switcheroo.md, including HasDualGpu and the referenced
sections, and ensure the file ends with exactly one trailing newline.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 7478fb06-35cd-4ce0-b165-b45cc39edf8a
⛔ Files ignored due to path filters (1)
docs/lib/mermaid/mermaid.min.jsis excluded by!**/*.min.js
📒 Files selected for processing (8)
book.tomldocs/SUMMARY.mddocs/development/bpf.mddocs/development/dbus.mddocs/development/smart.mddocs/development/switcheroo.mddocs/lib/mermaid/mermaid-init.jsflake.nix
Comment on lines
+29
to
+35
| - **`cw_mode`**: Stores the current Cardwire mode (0=Integrated, 1=Hybrid, 2=Manual, 3=Smart). | ||
| - **`cw_blocked_ino`**: A hash map containing the inodes of blocked DRM devices (`/dev/dri/cardX`, `/dev/dri/renderDX`). The value indicates the GPU ID (0 for iGPU, 1 for dGPU). | ||
| - **`cw_exp_blk_ino`**: Contains inodes of blocked NVIDIA-specific files when `experimental_nvidia_block` is enabled. | ||
| - **`cw_allowed_pid`**: Used in Smart mode. Contains the PIDs of applications that have been analyzed and allowed to use the dGPU. The stored value (`__u8`) is used to identify if PID is meant for iGPU(0) or dGPU(1) | ||
| - **`cw_allowed_comm`**: A whitelist of process names (like `udev` or `pacman`) that bypass blocking entirely. | ||
| - **`cw_daemon_pid`**: Cardwire's own PID so it doesn't block itself. | ||
| - **`cw_exec_events`**, **`cw_close_events`**, **`cw_report_events`**: Ring buffers used to send process and block events back to userspace. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Unify the Smart-mode state machine across the development guides.
The environment flags, allowed-PID values, and GPU visibility states currently describe incompatible mappings. Define one canonical table and apply it at every affected site.
docs/development/bpf.md#L29-L35: document the canonicalcw_allowed_pidvalue mapping.docs/development/smart.md#L21-L23: align analyzer and environment-variable semantics.docs/development/smart.md#L55-L61: align the Mermaid branches with that mapping.docs/development/switcheroo.md#L41-L53: alignCARDWIRE_FORCE_DGPUandCARDWIRE_ALLOWbehavior.
📍 Affects 3 files
docs/development/bpf.md#L29-L35(this comment)docs/development/smart.md#L21-L23docs/development/smart.md#L55-L61docs/development/switcheroo.md#L41-L53
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/development/bpf.md` around lines 29 - 35, Unify the Smart-mode state
machine by defining one canonical mapping for environment flags, analyzer
outcomes, cw_allowed_pid values, and GPU visibility, then apply it consistently
at docs/development/bpf.md:29-35, docs/development/smart.md:21-23,
docs/development/smart.md:55-61, and docs/development/switcheroo.md:41-53.
Update the cw_allowed_pid documentation, analyzer and environment-variable
semantics, Mermaid branches, and CARDWIRE_FORCE_DGPU/CARDWIRE_ALLOW behavior to
match that single mapping.
Comment on lines
+39
to
+41
| Across all blocking modes (Integrated, Manual, Smart), Cardwire uses the `getdents64` syscall hooks to manipulate the contents of directories (like `/dev/dri/`) on the fly. | ||
|
|
||
| **BLOCKED_NVIDIA_FILES** | ||
|
|
||
| - For the list of blocked NVIDIA files | ||
|
|
||
| **SETTINGS** | ||
|
|
||
| - For experimental_nvidia_block | ||
|
|
||
| ## Block list | ||
|
|
||
| ### PCI files | ||
|
|
||
| Files that get blocked when a gpu's PCI address is blocked: | ||
|
|
||
| - config | ||
| - current_link_speed | ||
| - current_link_width | ||
| - max_link_speed | ||
| - max_link_width | ||
|
|
||
| ### NVIDIA files | ||
|
|
||
| These files are only blocked when the `experimental_nvidia_block` setting is enabled | ||
|
|
||
| - libGLX_nvidia.so.0 | ||
| - nvidia_icd.json | ||
| - nvidia_icd.x86_64.json | ||
| - nvidiactl | ||
|
|
||
| /dev/nvidia? using the minor | ||
|
|
||
| Example: | ||
|
|
||
| ```bash | ||
| /dev/nvidia0 | ||
| ``` | ||
|
|
||
| Will be blocked using the major `195` and the minor `0` | ||
|
|
||
| ### DRM | ||
|
|
||
| DRM node (card + renderD) are blocked using their major + minor ID | ||
|
|
||
| Example: | ||
|
|
||
| ```bash | ||
| /dev/dri/card1 | ||
| /dev/dri/renderD128 | ||
| ``` | ||
|
|
||
| Will be blocked using the major `226` and the minor `1` || `128` | ||
| When an application calls `getdents64` to list available GPUs, the eBPF program `patch_dirent_if_found` loops through the directory entries in memory. If it spots an inode belonging to a blocked GPU, it overwrites the previous entry's length field, effectively "jumping over" the blocked device. To the application, the blocked GPU simply does not exist. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Separate directory hiding from file-access errors.
The prose and diagram disagree on whether getdents64 removes entries by rewriting dirent lengths or returns -ENOENT. Document each hook’s actual behavior independently.
docs/development/bpf.md#L39-L41: retain the dirent-filtering behavior and state its observable result.docs/development/smart.md#L51-L61: split thegetdents64listing path fromfile_openand show the correct result for each.
📍 Affects 2 files
docs/development/bpf.md#L39-L41(this comment)docs/development/smart.md#L51-L61
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/development/bpf.md` around lines 39 - 41, Update docs/development/bpf.md
lines 39-41 to retain the dirent-length filtering explanation and explicitly
state that blocked GPUs are omitted from directory listings rather than causing
an error. Update docs/development/smart.md lines 51-61 by separating the
getdents64 listing behavior from file_open access behavior, documenting the
former as hiding entries and the latter with its correct -ENOENT result.
Comment on lines
+15
to
+16
| ### `HasDualGpu` | ||
| Indicates whether the system has exactly two GPUs. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Complete the markdown formatting incantations.
MD022 flags missing blank lines after the subsection headings, and MD047 reports that the file lacks its final newline. Add the required spacing and exactly one trailing newline.
Also applies to: 20-21, 25-26, 41-42, 50-51, 53-53
🧰 Tools
🪛 markdownlint-cli2 (0.23.1)
[warning] 15-15: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/development/switcheroo.md` around lines 15 - 16, Add blank lines after
every affected subsection heading in docs/development/switcheroo.md, including
HasDualGpu and the referenced sections, and ensure the file ends with exactly
one trailing newline.
Source: Linters/SAST tools
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/getting-started/usage.md (1)
71-71: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winName the actual fallback condition, young scribe.
The daemon gates this XDG/Flatpak detection on
!switcheroo_support; it does not check whether “switcheroo/cardwire” is absent. Please change the parenthetical to “Only on systems that do not support Switcheroo,” so the guidance matchescrates/cardwire-daemon/src/analyzer/models.rs:183-216.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/getting-started/usage.md` at line 71, Update the parenthetical description for Flatpak apps with XDG PrefersNonDefaultGpu=true to state “Only on systems that do not support Switcheroo,” matching the daemon’s !switcheroo_support condition. Keep the surrounding guidance unchanged.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.github/workflows/cicd.yml:
- Line 149: Update the mdbook-mermaid installation step to pin the version
tested with mdbook 0.5.2 and pass Cargo’s --locked option, replacing the
unconstrained install command while preserving the existing workflow setup.
---
Outside diff comments:
In `@docs/getting-started/usage.md`:
- Line 71: Update the parenthetical description for Flatpak apps with XDG
PrefersNonDefaultGpu=true to state “Only on systems that do not support
Switcheroo,” matching the daemon’s !switcheroo_support condition. Keep the
surrounding guidance unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: cbf88bb1-178c-4505-87ee-6f170129ea87
📒 Files selected for processing (3)
.github/workflows/cicd.ymldocs/getting-started/installation.mddocs/getting-started/usage.md
💤 Files with no reviewable changes (1)
- docs/getting-started/installation.md
| curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf -y | sh | ||
| rustup update | ||
| cargo install --version ${MDBOOK_VERSION} mdbook | ||
| cargo install mdbook-mermaid |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win
Pin mdbook-mermaid for reproducible builds.
The workflow pins mdbook but installs an unconstrained Mermaid preprocessor, so future releases can change CI behavior without any repository change. Pin the version tested with mdbook 0.5.2 and use --locked; the upstream project publishes versioned releases and supports Cargo installation. (github.com)
🪄 Proposed fix
- cargo install mdbook-mermaid
+ cargo install --version <tested-version> --locked mdbook-mermaid🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.github/workflows/cicd.yml at line 149, Update the mdbook-mermaid
installation step to pin the version tested with mdbook 0.5.2 and pass Cargo’s
--locked option, replacing the unconstrained install command while preserving
the existing workflow setup.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Please include a summary of the changes and if applicable, a related issue.
If this PR introduce a new feature, explain your motivations
Fixes # (issue)
TODO
Checklist:
Summary by CodeRabbit
nvidia-powerdfailures after switching GPU modes.