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