From cc36a2dc5e4254a98c9b2dd956a488b2c34ef88a Mon Sep 17 00:00:00 2001 From: Amogh Munikote Date: Wed, 29 Jul 2026 17:35:09 +0000 Subject: [PATCH] Update to Docs * Debugging guide * Updated guides * Architecture doc * Basic contributing guide * Bump PR request template * Update docs a little more * Update README --- .github/pull_request_template.md | 3 + README.md | 61 ++------------- docs/ARCHITECTURE.md | 130 +++++++++++++++++++++++++++++++ docs/CONTRIBUTING.md | 39 ++++++++++ docs/DEBUGGING.md | 40 ++++++++++ docs/INSTALLATION.md | 43 ++++++++++ 6 files changed, 261 insertions(+), 55 deletions(-) create mode 100644 docs/ARCHITECTURE.md create mode 100644 docs/CONTRIBUTING.md create mode 100644 docs/DEBUGGING.md create mode 100644 docs/INSTALLATION.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 1f974b4..5e0a677 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,3 +1,6 @@ +# Pull Request Template - This format is required for all PRs + + ## Summary diff --git a/README.md b/README.md index e27d7bb..693a240 100644 --- a/README.md +++ b/README.md @@ -2,25 +2,10 @@ Unlock tool for the NVIDIA CMP 170HX (GA100) mining card. Restores full SM compute throughput and unlocked HBM2e memory geometry that are restricted in firmware/OTP configuration. -Targets **nvidia-open driver 610.43.0x** on Linux. cmpunlocker does **not** install the full NVIDIA userspace package — it patches and installs open kernel modules only. **[Join our Discord community](https://discord.gg/CdHSakKSFv)** for support and discussions. --- - -## Background - -The CMP 170HX is a physically complete GA100 die (same silicon as the A100) with compute and memory artificially limited. This tool applies an in-driver unlock path (SEC2 Booter PLM open + host SS0/SS1/CFG1/LMR writes + FB/PMA adjustments) that runs automatically every time the patched modules boot GSP for PCI ID `0x20C2`. - -Card size selects the memory geometry: - -| Physical card | Unlock geometry | CFG1 | LMR | -|---|---|---|---| -| **8 GB** | **64 GB** | `0x02779000` | `0x0000020B` | -| **10 GB** | **40 GB** | `0x02669000` | `0x0000028A` | - ---- - ## Proof of Concept Below are memory and performance results after applying the unlock: @@ -50,51 +35,20 @@ Below are memory and performance results after applying the unlock: ## Install -One command. Auto-detects 8GB vs 10GB from stock `nvidia-smi` memory, then builds patched open kernel modules into `/lib/modules/$(uname -r)/updates/cmpunlocker/`. +To install cmpunlocker, run the following command: ```bash sudo ./install.sh ``` -Force a profile if detection is wrong or `nvidia-smi` is unavailable: +To force a certain memory profile, use the `--profile` option: ```bash sudo ./install.sh --profile=8gb # 8GB card → 64GB unlock sudo ./install.sh --profile=10gb # 10GB card → 40GB unlock ``` -### IOMMU - -The installer also enables the IOMMU in passthrough mode, appending `intel_iommu=on iommu=pt` (Intel) or `amd_iommu=on iommu=pt` (AMD) to the kernel command line via `/etc/default/grub` or `/etc/kernel/cmdline`, then regenerating the boot config. Conflicting `iommu=` / `*_iommu=` entries are replaced, the original file is backed up to `*.cmpunlocker.bak`, and `remove.sh` restores it. - -This takes effect on the next reboot, and still requires VT-d / AMD-Vi to be enabled in BIOS/UEFI. To leave the kernel command line untouched: - -```bash -sudo ./install.sh --no-iommu -``` - -Then perform a **cold reboot** (full power off, then boot) if modules did not hot-reload cleanly, or if memory still shows the stock size. - ---- - -## Verify - -```bash -nvidia-smi -# 8GB card: expect ~65536 MiB -# 10GB card: expect ~40960 MiB - -nvidia-smi --query-gpu=memory.total,pcie.link.gen.current,pcie.link.gen.max,clocks.max.sm --format=csv -# Expect pcie.link.gen.current=2 and pcie.link.gen.max=2 after reboot - -sudo lspci -d 10de:20c2 -vv | grep -E 'LnkCap:|LnkSta:' -# Expect LnkSta: Speed 5GT/s (not 2.5GT/s) - -sudo dmesg | grep SEC2_DEBUG -# Expected: PLMs opening to 0xffffffff, CFG1/LMR/SS0/SS1 writes, late PMA -cat /lib/modules/$(uname -r)/updates/cmpunlocker/card_profile -# 8gb or 10gb -``` +Then perform a cold reboot (full power off, then boot). ## What Gets Unlocked @@ -102,22 +56,19 @@ cat /lib/modules/$(uname -r)/updates/cmpunlocker/card_profile |---|---| | Full SM compute throughput (SS0/SS1) | Working ✓ | | Memory geometry (64GB on 8GB cards, 40GB on 10GB cards) | Working ✓ | -| PCIe Gen2 link (`5GT/s`, Device Max ≥ 2) | Working ✓ | | Persistence across reboot (patched modules) | Working ✓ | --- ## Uninstall -Restore stock module loading: +To uninstall cmpunlocker, run the following command: ```bash -sudo ./remove.sh --yes +sudo ./uninstall.sh --yes ``` -This removes `/lib/modules/*/updates/cmpunlocker/`, runs `depmod`, and attempts to reload stock NVIDIA modules. Reboot if the GPU does not come back cleanly. - ---- +Then perform a cold reboot (full power off, then boot). ## Support & Community diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..0bc8a06 --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,130 @@ +# Architecture + +## Overview + +cmpunlocker restores full compute and memory capabilities to the NVIDIA CMP 170HX by patching the nvidia-open kernel modules. The unlock runs automatically during driver initialization and persists across reboots. + +The CMP 170HX is physically a complete GA100 die (same silicon as the A100) but with compute and memory artificially restricted via firmware and OTP configuration. cmpunlocker bypasses these restrictions at the driver level without requiring hardware modifications. + +--- + +## The Problem + +The CMP 170HX ships with: + +- **Disabled SMs (Streaming Multiprocessors)**: SS0 and SS1 (Suspension State registers) artificially disable clusters of SMs +- **Restricted memory geometry**: The HBM2e controller is configured for 8GB or 10GB instead of the full 64GB or 40GB the die supports +- **Firmware locks**: OTP (One-Time Programmable) fuses prevent reconfiguration at runtime + +All three are enforced during GSP (GPU System Processor) boot, which happens when the driver loads. + +--- + +## The Unlock Approach + +Instead of modifying OTP (which is physically locked), cmpunlocker intercepts the driver's boot flow and reconfigures the GPU before OTP locks take effect: + +1. **Open the SEC2 Booter PMM** — disable security restrictions on the Booter so it can execute custom PLM sequences +2. **Configure memory geometry** — write CFG1 (config) and LMR (LM Request) registers to unlock full HBM2e capacity +3. **Enable all SMs** — write SS0 and SS1 (Suspension State) to re-enable disabled SM clusters +4. **Finalize** — perform late PMA (Power Management Array) adjustments and allow normal boot to continue + +--- + +## Technical Components + +### SEC2 Booter & PLM + +The SEC2 Booter executes firmware sequences (PLMs: "Program Logic Modules") during GPU power-on and reset. Normally, PLMs are locked to a restricted set via security fuses. + +cmpunlocker: +- Patches the driver to open the PMM (Permute Mask Model) during boot +- Sets PLM permissions to `0xffffffff` (all PLMs enabled) +- Injects custom PLM sequences that reconfigure GPU state + +Expected dmesg output: +``` +SEC2_DEBUG: PLMs opening to 0xffffffff +SEC2_DEBUG: Executing unlock sequence... +``` + +Booter status codes like `0x31` or `0xffff` during early PLM passes are often harmless if the final boot succeeds. + +--- + +### Memory Geometry (CFG1 & LMR) + +The GPU memory controller is configured by two registers: + +| Card | CFG1 | LMR | Unlocked Capacity | +|---|---|---|---| +| 8GB | `0x02779000` | `0x0000020B` | 64GB | +| 10GB | `0x02669000` | `0x0000028A` | 40GB | + +- **CFG1**: Memory configuration register (address mapping, bank layout) +- **LMR**: LM (Local Memory) Request register (capacity/geometry selector) + +cmpunlocker writes both during the unlock sequence. Detection of 8GB vs 10GB happens at install time via Python script (reads `nvidia-smi` output). + +--- + +### Compute State (SS0 & SS1) + +SS0 and SS1 are Suspension State registers that control which SM clusters are active: + +- Stock firmware sets these to disable ~50% of the SMs +- cmpunlocker writes `0xffffffff` to both, enabling all clusters +- The GPU can then use full compute throughput + +Expected dmesg output: +``` +SEC2_DEBUG: SS0 = 0xffffffff +SEC2_DEBUG: SS1 = 0xffffffff +``` + +--- + +### FB & PMA Adjustments + +After core reconfiguration, the frame buffer (FB) and power management array (PMA) are adjusted to support the new memory geometry and active SMs: + +- FB is resized to reflect the new memory capacity +- PMA is reconfigured for the enabled SM clusters +- These changes are performed in "late PMA" phase, near the end of boot + +--- + +## Boot Flow + +1. **Driver loads** → nvidia-open kernel modules initialize +2. **GSP power-on** → SEC2 Booter executes (normally-locked path) +3. **cmpunlocker intercepts** → PMM is opened, custom PLM sequences run + - PLMs set to unrestricted mode + - CFG1/LMR written (memory geometry) + - SS0/SS1 written (compute state) + - Late PMA adjustments applied +4. **GSP boot completes** → GPU is now fully unlocked +5. **Driver ready** → `nvidia-smi` shows 65536 MiB (8GB) or 40960 MiB (10GB) + +--- + +## Persistence Across Reboot + +The unlock is applied by **patched kernel modules**, not a userspace daemon: + +- Modified `nvidia-drm.ko` and `nvidia.ko` are installed to `/lib/modules/$(uname -r)/updates/cmpunlocker/` +- These modules load before the stock NVIDIA modules (due to the `updates/` directory priority) +- Every time the driver initializes (on boot or after a reload), the patched sequence runs +- The unlock persists indefinitely until `./remove.sh` is run + +Card profile (8GB vs 10GB) is stored in `/lib/modules/$(uname -r)/updates/cmpunlocker/card_profile` at install time and used during every boot. + +--- + +## Known Limitations + +- **Secure Boot must be disabled** — patched modules are unsigned +- **Requires nvidia-open 610.43.0x** — stock NVIDIA proprietary driver has different boot paths and cannot be patched the same way +- **Linux only** — GSP boot path is Linux-specific (Windows WDDM driver is fundamentally different) +- **Kernel headers required** — modules must be compiled for the running kernel version + diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..0660c0d --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,39 @@ +# Contributing + +Thanks for your interest in contributing to cmpunlocker! This guide covers submitting changes. + +--- + +## Submitting Changes + +1. **Fork the repo** on GitHub + +2. **Create a branch** for your changes: + ```bash + git checkout -b feature/my-improvement + ``` + +3. **Make changes** and test thoroughly on real hardware + +4. **Commit with clear messages**: + ```bash + git commit -m "Add improvement to 8GB card support" + ``` + +5. **Push and open a PR**: + ```bash + git push origin my-feature + ``` + +6. **Describe your changes** in the PR body (following the PR template) + +--- + +## Code Style & Conventions + +- **Patch files**: Use unified diff format (`git diff` or `patch -u`). Include context lines. +- **Bash scripts**: Strict mode (`set -euo pipefail`), quote variables, error checking. +- **Comments in patches**: Use standard patch comments (`---` and `+++` headers); C comments go in the patched code. +- **Testing**: Always test on physical hardware before submitting. Describe your test environment (distro, kernel version, card variant). + +--- diff --git a/docs/DEBUGGING.md b/docs/DEBUGGING.md new file mode 100644 index 0000000..d10d0ff --- /dev/null +++ b/docs/DEBUGGING.md @@ -0,0 +1,40 @@ +# Debugging + +Before you go asking in the Discord for help, here is a FAQ you should take a look at: + +--- + +## "nvidia-smi: command not found" + +- The installer likely didn't run or even failed. Re-run `sudo ./install.sh` and cold reboot. + +--- + +## nvidia-smi shows 8192 or 10240 MiB (not 65536 or 40960) + +- All the PLMs must show `0xffffffff`. Run `sudo dmesg | grep SEC2_DEBUG`to confirm. + +- If this still persists, refer to the Discord protocol at the end of the document. + +--- + +## PCIe still at Gen1 after install + +- Confirm IOMMU passthrough mode is enabled. Depending on your operating system, enabling IOMMU passthrough can vary. + +- If this still persists, refer to the Discord protocol at the end of the document. + +--- + +## Discord protocol + +If you have tried the above steps and are still having issues, please follow these steps to get help in the [Discord community](https://discord.gg/CdHSakKSFv): + +1. Open a ticket in the #issue-support channel. + +2. Provide the following information in your ticket: + - Your operating system and version + - Your GPU model and driver version + - The output of `sudo dmesg | grep SEC2_DEBUG` + - Latest install log (if applicable) + diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md new file mode 100644 index 0000000..19bb734 --- /dev/null +++ b/docs/INSTALLATION.md @@ -0,0 +1,43 @@ +# Installation + +Here are the steps to install cmpunlocker on your system. + +--- + +## Requirements + +- NVIDIA CMP 170HX (8GB or 10GB) +- Linux operating system (Ubuntu, Debian, Fedora, etc.) +- Kernel headers matching the running kernel (linux-headers-$(uname -r) / kernel-devel) +- Python 3 +- **nvidia-open 610.43.0x already installed** (libs + firmware) +- Root access to the system (sudo privileges) +- Secure Boot disabled +- Network access on first install (downloads matching stock open-gpu-kernel-modules sources) + +## Install + +To install cmpunlocker, run the following command: + +```bash +sudo ./install.sh +``` + +To force a certain memory profile, use the `--profile` option: + +```bash +sudo ./install.sh --profile=8gb # 8GB card → 64GB unlock +sudo ./install.sh --profile=10gb # 10GB card → 40GB unlock +``` + +Then perform a cold reboot (full power off, then boot). + +## Uninstall + +To uninstall cmpunlocker, run the following command: + +```bash +sudo ./uninstall.sh --yes +``` + +Then perform a cold reboot (full power off, then boot). -- 2.51.2