docs: add README with build/usage instructions
Signed-off-by: NotAShelf <raf@notashelf.dev> Change-Id: I6a6a6964b03685f7d0b7060c928d3bd8b28f5819
This commit is contained in:
parent
6abac69e75
commit
1d1d0f96c7
GPG key ID:
29D95B64378DB4BF
1 changed files with 383 additions and 0 deletions
383
docs/README.md
Normal file
383
docs/README.md
Normal file
|
|
@ -0,0 +1,383 @@
|
|||
# Deepcool
|
||||
|
||||
An unofficial Linux kernel module Provides early boot support and sysfs
|
||||
interface for monitoring and controlling device display modes for Deepcool
|
||||
Digital USB HID devices (CPU coolers, AIOs, cases). The module runs directly in
|
||||
kernel space, providing early boot support and standard Linux interfaces for
|
||||
controlling Deepcool Digital USB HID devices.
|
||||
|
||||
## Motive
|
||||
|
||||
[deepcool-digital-linux]: https://github.com/Nortank12/deepcool-digital-linux
|
||||
|
||||
This project exists solely because I hoped to replace the userspace daemon with
|
||||
a kernel module that is always loaded. Simply put, I don't need it to be an
|
||||
userspace daemon, and I am under the impression that using the Linux kernel APIs
|
||||
directly will yield be better performance, or at least less overhead.
|
||||
|
||||
[deepcool-digital-linux] is an userspace daemon that does a little more than
|
||||
this project, and is a more suitable replacement if you are not looking to taint
|
||||
your kernel with out-of-tree modules. Not that a "tainted kernel" is inherently
|
||||
bad, though. There are different usecases. See below for a better comparison
|
||||
between **Deepcool** (this module) and **deepcool-digital-linux**, the userspace
|
||||
daemon.
|
||||
|
||||
## Features
|
||||
|
||||
The primary feature of Deepcool is that it supports early boot, or in other
|
||||
words, its functionality fully available _as soon as you reach the kernel_. Rest
|
||||
of the functionality is almost identical with little caveats.
|
||||
|
||||
- **Real-time Monitoring**: CPU temperature, usage, power, frequency
|
||||
- **Display Modes**: Auto-cycling, CPU temp, CPU usage, CPU power, and more
|
||||
- **Sysfs Interface**: Standard Linux interface for configuration
|
||||
- **Automatic Device Detection**: Supports most Deepcool Digital product series
|
||||
- **Multiple Device Series Support**:
|
||||
- AK Series (AK400 DIGITAL, AK500 DIGITAL, AK620 DIGITAL)
|
||||
- AK400 PRO, AK620 PRO
|
||||
- LS Series
|
||||
- AG Series
|
||||
- LQ Series
|
||||
- LD Series
|
||||
- LP Series
|
||||
- CH Series (Gen1, Gen2, CH510)
|
||||
|
||||
> [!INFO]
|
||||
> **For device support, please refer to the
|
||||
> [device support matrix](#device-support-matrix) below**
|
||||
|
||||
If you believe there is anything missing that belongs in a kernel module, please
|
||||
feel free to let me know. I'd be happy to discuss.
|
||||
|
||||
## Usage
|
||||
|
||||
To use Deepcool, you must load it in your kernel. The installation steps may
|
||||
differ based on your distro, but most distros should be supported out of the
|
||||
box.
|
||||
|
||||
### Requirements
|
||||
|
||||
- Linux kernel 5.10 or later
|
||||
- Kernel headers for your running kernel
|
||||
- Build essentials (gcc, make)
|
||||
- Root/sudo access for installation
|
||||
|
||||
#### Kernel Configuration
|
||||
|
||||
The following kernel options must be enabled:
|
||||
|
||||
```plaintext
|
||||
CONFIG_HID=y or m
|
||||
CONFIG_HIDRAW=y or m
|
||||
CONFIG_USB_HID=y or m
|
||||
CONFIG_THERMAL=y
|
||||
CONFIG_CPU_FREQ=y
|
||||
CONFIG_CPUFREQ_STATS=y
|
||||
CONFIG_SYSFS=y
|
||||
```
|
||||
|
||||
Most of those features are enabled on most kernels, but is best to check before
|
||||
you build. `zcat` can be used to check the configuration for your current kernel
|
||||
configuration:
|
||||
|
||||
```sh
|
||||
$ zcat /proc/config.gz | grep CONFIG_HID
|
||||
# => CONFIG_HIDRAW=y
|
||||
```
|
||||
|
||||
For Intel RAPL power monitoring:
|
||||
|
||||
```plaintext
|
||||
CONFIG_POWERCAP=y
|
||||
CONFIG_INTEL_RAPL=y or m
|
||||
```
|
||||
|
||||
### Building
|
||||
|
||||
Once you confirm that you meet the requirements, you may build the kernel
|
||||
module. To build, navigate to the cloned directory and run `make`.
|
||||
|
||||
```bash
|
||||
$ make
|
||||
#=> The module will be built as `deepcool.ko`.
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
### Manual Installation
|
||||
|
||||
[DKMS framework]: https://wiki.archlinux.org/title/Dynamic_Kernel_Module_Support
|
||||
|
||||
The Makefile provides a task to install Deepcool for Linux distributions using
|
||||
the [DKMS framework]. NixOS should refer to the section below.
|
||||
|
||||
```bash
|
||||
# Build the module
|
||||
make
|
||||
|
||||
# Install to system
|
||||
sudo make dkms-install
|
||||
|
||||
# Load the module
|
||||
sudo modprobe deepcool
|
||||
```
|
||||
|
||||
## Automatic Loading on Boot
|
||||
|
||||
Create a module configuration file:
|
||||
|
||||
```bash
|
||||
sudo tee /etc/modules-load.d/deepcool_digital.conf <<EOF
|
||||
deepcool
|
||||
EOF
|
||||
```
|
||||
|
||||
Once loaded, the module automatically detects connected Deepcool Digital devices
|
||||
and creates sysfs entries under `/sys/bus/hid/drivers/deepcool_digital/`.
|
||||
|
||||
### Finding Your Device
|
||||
|
||||
```bash
|
||||
# List all detected devices
|
||||
ls /sys/bus/hid/drivers/deepcool_digital/
|
||||
```
|
||||
|
||||
The device path will typically be something like:
|
||||
|
||||
```plaintext
|
||||
/sys/bus/hid/drivers/deepcool_digital/0003:3633:0007.XXXX/
|
||||
```
|
||||
|
||||
Replace `0003:3633:0007.XXXX` with your actual device path in the examples
|
||||
below.
|
||||
|
||||
### Sysfs Attributes
|
||||
|
||||
This module uses sysfs to interact with the module. You may find configuration
|
||||
attributes below.
|
||||
|
||||
#### Configuration Attributes (Read/Write)
|
||||
|
||||
**`mode`** - Display mode
|
||||
|
||||
```bash
|
||||
# View current mode
|
||||
cat mode
|
||||
|
||||
# Set mode
|
||||
echo "cpu_temp" > mode
|
||||
|
||||
# Available modes:
|
||||
# - auto (cycle between supported metrics)
|
||||
# - cpu_temp (CPU temperature)
|
||||
# - cpu_usage (CPU usage percentage)
|
||||
# - cpu_power (CPU power consumption)
|
||||
# - cpu_freq (CPU frequency)
|
||||
# - cpu_fan (CPU fan speed, if supported)
|
||||
# - gpu_temp (GPU temperature, if supported)
|
||||
# - gpu_usage (GPU usage, if supported)
|
||||
# - gpu_power (GPU power, if supported)
|
||||
```
|
||||
|
||||
**`update_interval`** - Update interval in milliseconds (100-2000)
|
||||
|
||||
```bash
|
||||
# View current interval
|
||||
cat update_interval
|
||||
|
||||
# Set to 500ms
|
||||
echo 500 > update_interval
|
||||
```
|
||||
|
||||
**`fahrenheit`** - Temperature unit (0=Celsius, 1=Fahrenheit)
|
||||
|
||||
```bash
|
||||
# Use Fahrenheit
|
||||
echo 1 > fahrenheit
|
||||
|
||||
# Use Celsius
|
||||
echo 0 > fahrenheit
|
||||
```
|
||||
|
||||
**`alarm`** - Temperature alarm (0=off, 1=on)
|
||||
|
||||
```bash
|
||||
# Enable alarm
|
||||
echo 1 > alarm
|
||||
|
||||
# Disable alarm
|
||||
echo 0 > alarm
|
||||
```
|
||||
|
||||
#### Sensor Attributes (Read-Only)
|
||||
|
||||
**`cpu_temp`** - CPU temperature (°C or °F based on fahrenheit setting)
|
||||
|
||||
```bash
|
||||
cat cpu_temp
|
||||
```
|
||||
|
||||
**`cpu_usage`** - CPU usage percentage (0-100)
|
||||
|
||||
```bash
|
||||
cat cpu_usage
|
||||
```
|
||||
|
||||
**`cpu_power`** - CPU power consumption (Watts)
|
||||
|
||||
```bash
|
||||
cat cpu_power
|
||||
```
|
||||
|
||||
**`cpu_freq`** - CPU frequency (MHz)
|
||||
|
||||
```bash
|
||||
cat cpu_freq
|
||||
```
|
||||
|
||||
### Examples
|
||||
|
||||
#### Set CPU temperature display with Fahrenheit
|
||||
|
||||
```bash
|
||||
echo "cpu_temp" > /sys/bus/hid/drivers/deepcool_digital/0003:3633:0007.XXXX/mode
|
||||
echo 1 > fahrenheit
|
||||
echo 1 > alarm
|
||||
```
|
||||
|
||||
#### Auto-cycle between metrics at 1-second intervals
|
||||
|
||||
```bash
|
||||
echo "auto" > /sys/bus/hid/drivers/deepcool_digital/0003:3633:0007.XXXX/mode
|
||||
echo 1000 > /sys/bus/hid/drivers/deepcool_digital/0003:3633:0007.XXXX/update_interval
|
||||
```
|
||||
|
||||
#### Monitor CPU power consumption
|
||||
|
||||
```bash
|
||||
echo "cpu_power" > /sys/bus/hid/drivers/deepcool_digital/0003:3633:0007.XXXX/mode
|
||||
```
|
||||
|
||||
#### Create a simple monitoring script
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
DEVICE="/sys/bus/hid/drivers/deepcool_digital/0003:3633:0007.XXXX"
|
||||
|
||||
while true; do
|
||||
echo "CPU Temp: $(cat $DEVICE/cpu_temp)°C"
|
||||
echo "CPU Usage: $(cat $DEVICE/cpu_usage)%"
|
||||
echo "CPU Power: $(cat $DEVICE/cpu_power)W"
|
||||
echo "CPU Freq: $(cat $DEVICE/cpu_freq)MHz"
|
||||
echo "---"
|
||||
sleep 1
|
||||
done
|
||||
```
|
||||
|
||||
## Device Support Matrix
|
||||
|
||||
<!-- markdownlint-disable MD013 -->
|
||||
|
||||
| Device Series | Auto Mode | Alarm | Fahrenheit | Secondary Display | Rotation |
|
||||
| ------------- | --------- | ------ | ---------- | ----------------- | -------- |
|
||||
| AK Series | ✓ | ✓ | ✓ | ✗ | ✗ |
|
||||
| AK400 PRO | ✓ | HW | ✓ | ✗ | ✗ |
|
||||
| AK620 PRO | ✓ | HW | ✓ | ✗ | ✗ |
|
||||
| LS Series | ✓ | ✓ | ✓ | ✗ | ✗ |
|
||||
| AG Series | ✓ | ✓ | ✗ | ✗ | ✗ |
|
||||
| LP Series | ✓ | ✗ | ✓ | ✓ | ✓ |
|
||||
| LQ Series | ✓ | ✓ | ✓ | ✗ | ✗ |
|
||||
| CH Series | ✓ | varies | varies | varies | ✗ |
|
||||
|
||||
<!-- markdownlint-enabled MD013 -->
|
||||
|
||||
**Legend:**
|
||||
|
||||
| Supported | Not Supported | Hardware-Controlled (Fixed thresholds) |
|
||||
| :-------: | :-----------: | :------------------------------------: |
|
||||
| ✓ | ✗ | HW |
|
||||
|
||||
## How It Works
|
||||
|
||||
### Initialization
|
||||
|
||||
1. Module loads and registers HID driver
|
||||
2. Kernel calls `probe()` when device is detected
|
||||
3. Driver identifies device series and capabilities
|
||||
4. Sysfs attributes are created
|
||||
5. Work queue is scheduled for periodic updates
|
||||
|
||||
### Runtime Operation
|
||||
|
||||
```
|
||||
Timer fires (every update_interval ms)
|
||||
↓
|
||||
Work queue handler executes
|
||||
↓
|
||||
Read CPU sensors:
|
||||
* Temperature from thermal subsystem
|
||||
* Usage from kernel CPU statistics
|
||||
* Frequency from CPUFreq
|
||||
* Power from Intel RAPL
|
||||
↓
|
||||
Build device-specific packet
|
||||
↓
|
||||
Send HID output report over USB
|
||||
↓
|
||||
Display updates
|
||||
↓
|
||||
Reschedule work queue
|
||||
```
|
||||
|
||||
### User Interaction
|
||||
|
||||
```
|
||||
User writes to sysfs attribute
|
||||
↓
|
||||
Kernel calls store() handler
|
||||
↓
|
||||
Validate input
|
||||
↓
|
||||
Update device configuration
|
||||
↓
|
||||
Next work cycle uses new configuration
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are always welcome! When submitting patches, please try to follow
|
||||
the several recommendations:
|
||||
|
||||
- Tabs and 8 character indentations are heretical. A cardinal sin. Please don't
|
||||
use those.
|
||||
- Testing on your own hardware is recommended, but not a hard-requirement
|
||||
- If there is device-specific behaviour (or non-behaviour), please document it!
|
||||
- Include dmesg output for new devices
|
||||
|
||||
Refer to [BUILD.md](./BUILD.md) for additional notes on working with and
|
||||
building Deepcool.
|
||||
|
||||
## License
|
||||
|
||||
GPL-2.0-only
|
||||
|
||||
## Attributions
|
||||
|
||||
[Nortank12]: https://github.com/Nortank12
|
||||
[zenpower]: https://github.com/ocerman/zenpower
|
||||
|
||||
There are a few projects that I would like to give credit to. Namely I'd like to
|
||||
thank the [deepcool-digital-linux] project for the inspiration and the device
|
||||
data. This project would be incredibly annoying to do without the efforts of
|
||||
[Nortank12]. Please make sure to give them some love!
|
||||
|
||||
I'd like to extend my thanks to the [zenpower] project that provided insight
|
||||
into developing Linux kernel modules, and the DKMS installation tasks. Thank you
|
||||
:)
|
||||
|
||||
## See Also
|
||||
|
||||
- [deepcool-digital-linux]: an userspace daemon providing similar functionality,
|
||||
with better GPU support.
|
||||
- Linux HID documentation: `Documentation/hid/` in kernel source
|
||||
- Sysfs documentation: `Documentation/filesystems/sysfs.txt`
|
||||
Loading…
Add table
Add a link
Reference in a new issue