Skip to content

Commit 8709f7a

Browse files
committed
docs: clarify more behaviour in config, and use sh instead of bash codeblocks
1 parent faff713 commit 8709f7a

2 files changed

Lines changed: 58 additions & 33 deletions

File tree

README.md

Lines changed: 57 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -53,25 +53,25 @@ daemons.
5353
## Features
5454

5555
- **Real-time CPU Management**: Monitor and control CPU governors, frequencies,
56-
and turbo boost
56+
and turbo boost.
5757
- **Intelligent Power Management**: Different profiles for AC and battery
58-
operation
58+
operation.
5959
- **Dynamic Turbo Boost Control**: Automatically enables/disables turbo based on
60-
CPU load and temperature
60+
CPU load and temperature.
6161
- **Fine-tuned Controls**: Adjust energy performance preferences, biases, and
62-
frequency limits
63-
- **Per-core Control**: Apply settings globally or to specific CPU cores
64-
- **Battery Management**: Monitor battery status and power consumption
65-
- **System Load Tracking**: Track system load and make intelligent decisions
66-
- **Daemon Mode**: Run in background with adaptive polling to minimize overhead
62+
frequency limits.
63+
- **Per-core Control**: Apply settings globally or to specific CPU cores.
64+
- **Battery Management**: Monitor battery status and power consumption.
65+
- **System Load Tracking**: Track system load and make intelligent decisions.
66+
- **Daemon Mode**: Run in background with adaptive polling to minimize overhead.
6767
- **Conflict Detection**: Identifies and warns about conflicts with other power
68-
management tools
68+
management tools.
6969

7070
## Usage
7171

7272
### Basic Commands
7373

74-
```bash
74+
```sh
7575
# Run as a daemon in the background with default configuration
7676
sudo watt
7777

@@ -88,7 +88,7 @@ Watt operates primarily as a daemon that automatically manages CPU and power
8888
settings based on the configuration rules. For manual CPU management, you can
8989
use the `cpu` command (requires the `cpu` binary to be available):
9090

91-
```bash
91+
```sh
9292
# Set CPU governor for all cores
9393
sudo cpu set --governor performance
9494

@@ -121,7 +121,7 @@ sudo cpu set --governor schedutil --energy-performance-preference balance_perfor
121121

122122
For manual power management, you can use the `power` command:
123123

124-
```bash
124+
```sh
125125
# Set battery charging thresholds to extend battery lifespan
126126
sudo power set --charge-threshold-start 40 --charge-threshold-end 80
127127

@@ -219,35 +219,44 @@ ones with lower priority.
219219

220220
### Configuration Locations
221221

222-
Default configuration locations (in order of precedence):
222+
Configuration locations (in order of precedence):
223223

224-
- Custom path via `WATT_CONFIG` environment variable
225-
- Built-in default configuration (if no custom path is specified)
224+
- Custom path via `--config` flag.
225+
- Custom path via `WATT_CONFIG` environment variable (if no flag is specified).
226+
- Built-in default configuration (if no custom path is specified).
226227

227228
If no configuration file is found, Watt uses a built-in default configuration.
228229

229230
### Rule-Based Configuration
230231

231232
Rules are the core of Watt's configuration system. Each rule can specify:
232233

233-
- **Conditions**: When the rule should apply (using the expression DSL)
234-
- **Priority**: Higher numbers take precedence (0-255)
235-
- **Actions**: CPU and power management settings to apply
234+
- **Conditions**: When the rule should apply (using the expression DSL). If not
235+
specified, always applies (defaults to `true`).
236+
- **Priority**: Higher numbers take precedence (0-65535).
237+
- **Actions**: CPU and power management settings to apply.
236238

237239
### Expression DSL
238240

239241
Watt includes a powerful expression language for defining conditions:
240242

243+
#### Constants
244+
245+
- `true`, `false` - Booleans
246+
- `123.456`, `42` - 64-bit Floats
247+
241248
#### System Variables
242249

243-
- `%cpu-usage` - Current CPU usage percentage (0.0-1.0)
244-
- `$cpu-usage-volatility` - CPU usage volatility measurement
245-
- `$cpu-temperature` - CPU temperature in Celsius
246-
- `$cpu-temperature-volatility` - CPU temperature volatility
247-
- `$cpu-idle-seconds` - Seconds since last significant CPU activity
248-
- `%power-supply-charge` - Battery charge percentage (0.0-1.0)
249-
- `%power-supply-discharge-rate` - Current discharge rate
250-
- `?discharging` - Boolean indicating if system is on battery power
250+
- `"%cpu-usage"` - Current CPU usage percentage (0.0-1.0)
251+
- `"$cpu-usage-volatility"` - CPU usage volatility measurement
252+
- `"$cpu-temperature"` - CPU temperature in Celsius
253+
- `"$cpu-temperature-volatility"` - CPU temperature volatility
254+
- `"$cpu-idle-seconds"` - Seconds since last significant CPU activity
255+
- `"%power-supply-charge"` - Battery charge percentage (0.0-1.0)
256+
- `"%power-supply-discharge-rate"` - Current discharge rate
257+
- `"?discharging"` - Boolean indicating if system is on battery power
258+
259+
The expression language only has boolean and 64-bit float values.
251260

252261
#### Operators
253262

@@ -256,7 +265,22 @@ Watt includes a powerful expression language for defining conditions:
256265
- **Logical**: `and`, `or`, `not`, `all`, `any`
257266
- **Arithmetic**: `plus`, `minus`, `multiply`, `divide`, `power`
258267

259-
#### Basic Configuration Example
268+
You can use operators with TOML attribute sets:
269+
270+
```toml
271+
[[rule]]
272+
if = { value = <expression>, <operator> = <parameter> }
273+
```
274+
275+
However, `all` and `any` do not take a `value` argument, but instead take a list
276+
of expressions as the parameter:
277+
278+
```toml
279+
[[rule]]
280+
if = { all = [ <expression>, <expression2> ] }
281+
```
282+
283+
### Basic Configuration Example
260284

261285
```toml
262286
# Emergency thermal protection (highest priority)
@@ -383,7 +407,7 @@ Available CPU configuration options:
383407
- `frequency-mhz-minimum` - Minimum CPU frequency in MHz
384408
- `frequency-mhz-maximum` - Maximum CPU frequency in MHz
385409
- `turbo` - Enable/disable turbo boost (boolean)
386-
- `for` - Apply settings to specific CPU cores (array of core IDs)
410+
- `for` - Apply settings to specific CPU cores (list of core IDs)
387411

388412
### Power Settings
389413

@@ -393,7 +417,7 @@ Available power management options:
393417
`low-power`)
394418
- `charge-threshold-start` - Battery charge level to start charging (0-100%)
395419
- `charge-threshold-end` - Battery charge level to stop charging (0-100%)
396-
- `for` - Apply settings to specific power supplies (array of supply names)
420+
- `for` - Apply settings to specific power supplies (list of supply names)
397421

398422
## Troubleshooting
399423

@@ -439,7 +463,7 @@ required.
439463
A `.envrc` is provided, and it's usage is encouraged for Nix users.
440464
Alternatively, you may use Nix for a reproducible developer environment
441465

442-
```bash
466+
```sh
443467
nix develop
444468
```
445469

@@ -448,8 +472,9 @@ manager, or using something like Rustup.
448472

449473
### Formatting & Lints
450474

451-
Please make sure to run _at least_ `cargo fmt` inside the repository to make
452-
sure all of your code is properly formatted. For Nix code, please use Alejandra.
475+
Please make sure to run _at least_ `cargo fmt` (and `taplo format` if you have
476+
modified any TOML) inside the repository to make sure all of your code is
477+
properly formatted. For Nix code, please use Alejandra.
453478

454479
Clippy lints are not _required_ as of now, but a good rule of thumb to run them
455480
before committing to catch possible code smell early.

watt/config.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -504,7 +504,7 @@ impl Expression {
504504
#[derive(Serialize, Deserialize, Default, Debug, Clone, PartialEq)]
505505
#[serde(deny_unknown_fields, rename_all = "kebab-case")]
506506
pub struct Rule {
507-
pub priority: u8,
507+
pub priority: u16,
508508

509509
#[serde(default, rename = "if", skip_serializing_if = "is_default")]
510510
pub condition: Expression,

0 commit comments

Comments
 (0)