Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
44 commits
Select commit Hold shift + click to select a range
452e71e
CLAUDE.md
spoulson May 20, 2026
aa970c3
Initial implementation
spoulson May 20, 2026
1ef0b1b
Use github.com/bougou/go-ipmi library
spoulson May 20, 2026
aff66be
Dry run mode
spoulson May 25, 2026
329ea39
Adjust logs
spoulson May 25, 2026
ffb518c
Rename device terminology to sensor
spoulson May 27, 2026
4af2694
Code fixes with interval handling
spoulson May 27, 2026
af26302
Propagate context to IPMI operations for clean shutdown
spoulson May 27, 2026
2ea28de
Skip fan speed apply when no new suggestions have arrived
spoulson May 27, 2026
1be00e9
Extract logFanSpeeds closure to named function
spoulson May 27, 2026
55aace6
Move main loop to service.go, leaving main() as bootstrap only
spoulson May 27, 2026
ec771f3
Fix set speed bug
spoulson May 27, 2026
ec417af
Sensor readings keyed by ID; fan log reverts to per-fan lines
spoulson May 27, 2026
acb4381
Tidy code
spoulson May 27, 2026
159e5d1
Add --version flag to print version and exit
spoulson May 27, 2026
fbd58ed
Tidy code
spoulson May 27, 2026
db01ab6
Add "make lint" target to call golangci-lint
spoulson May 27, 2026
c092d66
Fix lint errors
spoulson May 27, 2026
dc6ba18
Add GitHub Actions lint workflow using golangci-lint-action v9
spoulson May 27, 2026
8d83433
Add GitHub Actions test workflow
spoulson May 27, 2026
60bd8a4
Enable race detector in test workflow
spoulson May 27, 2026
18e93f1
Add uninstall_clean target; preserve config on reinstall
spoulson May 27, 2026
2d472c7
Add logrotate config; include in install and package targets
spoulson May 27, 2026
df7ddf2
Update .gitignore
spoulson May 27, 2026
16ae9ba
Combine lint and test into single Verification workflow
spoulson May 27, 2026
b88f2da
Rename workflow to "Verify"
spoulson May 27, 2026
104eaee
Use max sensor reading per poll; add configurable JSON log format
spoulson May 27, 2026
ba13db6
Deduplicate CPU sensor names with suffix starting at _2
spoulson May 27, 2026
e81ec7a
Deduplicate GPU sensor names with suffix starting at _2
spoulson May 27, 2026
f17eb04
Update README with description, build/install instructions, and confi…
spoulson May 27, 2026
0dcb87d
Update README.md
spoulson May 28, 2026
10b7694
Add Prometheus metrics HTTP server.
spoulson Jun 1, 2026
fe9da9e
Refine Prometheus metric names and GPU sensor ID
spoulson Jun 1, 2026
f5d6f99
Track per-sensor-ID rolling aggregates for fan speed
spoulson Jun 1, 2026
81ba07a
Port to C
spoulson Jun 11, 2026
acd6819
Tidy Makefile
spoulson Jun 28, 2026
7bad04b
Logger to use local timezone
spoulson Jun 28, 2026
8e4f809
Fix bug with fan_log_interval
spoulson Jun 28, 2026
84cd948
Fix fan-log busy loop and IPMI sensor/fan-control bugs
spoulson Aug 30, 2026
2757bf2
Bound blocking waits so shutdown signals are noticed promptly
spoulson Aug 30, 2026
a8a772e
Remove .claude/
spoulson Aug 31, 2026
7262027
Merge branch 'main' of github.com:spoulson/frostd into spoulson/c-3
spoulson Aug 31, 2026
7ccbeb6
Merge branch 'spoulson/c' into spoulson/c-3
spoulson Aug 31, 2026
9187c44
Update README requirements for the C toolchain
spoulson Sep 2, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 0 additions & 14 deletions .claude/settings.local.json

This file was deleted.

32 changes: 19 additions & 13 deletions .github/workflows/verify.yml
Original file line number Diff line number Diff line change
Expand Up @@ -6,30 +6,36 @@ on:
pull_request:
branches: [main]

env:
GOLANGCI_LINT_VERSION: v2.11.4

jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- uses: actions/setup-go@v5
with:
go-version-file: go.mod
- name: Install C dev dependencies
run: |
sudo apt-get update -q
sudo apt-get install -y \
libcyaml-dev libyaml-dev \
libipmimonitoring-dev libfreeipmi-dev \
libmicrohttpd-dev \
libcmocka-dev \
cppcheck

- uses: golangci/golangci-lint-action@v9
with:
version: ${{ env.GOLANGCI_LINT_VERSION }}
- run: make lint

test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- uses: actions/setup-go@v5
with:
go-version-file: go.mod
- name: Install C dev dependencies
run: |
sudo apt-get update -q
sudo apt-get install -y \
libcyaml-dev libyaml-dev \
libipmimonitoring-dev libfreeipmi-dev \
libmicrohttpd-dev \
libcmocka-dev

- run: go test -race ./...
- run: make test
5 changes: 5 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,3 +1,8 @@
/frostd
/bin
frostd*.deb
test_config
test_cpu
test_fan
test_gpu
test_metrics
116 changes: 79 additions & 37 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,60 +90,95 @@ affecting hardware.

## Technology Stack

`frostd` is written in Golang and compiled to standalone executable file to be
run on Debian or Ubuntu Linux on x86-64 architecture. The executable runs as a
systemd service.
`frostd` is written in C (C23 standard) and compiled to a standalone executable
to be run on Debian or Ubuntu Linux on x86-64 architecture. The executable
runs as a systemd service.

## Developer Prerequisites

- Debian or Ubuntu Linux OS on x86-64 architecture
- Golang 1.26+ installed
- GCC 9+ installed (GCC 13+ recommended for C23 support)
- `make` installed
- C development libraries:
- `libcyaml-dev` (YAML parsing)
- `libyaml-dev` (libcyaml dependency)
- `libipmimonitoring-dev` (IPMI sensor reads)
- `libfreeipmi-dev` (IPMI raw commands)
- `libmicrohttpd-dev` (Prometheus HTTP server)
- `libcmocka-dev` (unit testing)
- `cppcheck` (static analysis)

## Software Design

### Technology Stack

- `frostd` is a systemd service written in latest Golang.
- `frostd` is a systemd service written in C (C23 standard).
- It must be run on a Dell PowerEdge 12th generation server.

### Source Layout

```
src/ C source and header files
tests/ Unit test files and shared test helpers
packaging/ Debian package scripts and systemd configuration
```

### Tooling

- Use `slog` package for logging.
- Use module `github.com/bougou/go-ipmi` for IPMI support. Do not depend on
the commonly used `ipmitool` command.
- Use structured logging via `src/log.c/.h` (text key=value or JSON format).
- Use `libipmimonitoring` for IPMI sensor reads (temperature, fan).
- Use `libfreeipmi` API (`ipmi_ctx_t`) for IPMI raw commands (fan control).
- Do not depend on the commonly used `ipmitool` command.
- Use `libcyaml` for YAML config parsing.
- Use `libmicrohttpd` for the Prometheus metrics HTTP endpoint.

### Interfaces (vtable pattern)

C interfaces are implemented as function-pointer structs:
- `ipmi_ops_t` (`src/ipmi.h`) — IPMI operations (connect/sensors/raw command)
- `temp_reader_t` (`src/metrics.h`) — temperature reader for sensor monitors
- `cmd_runner_t` (`src/gpu.h`) — command execution (nvidia-smi)

Tests inject mock implementations of these vtables instead of real hardware.

### Service Lifecycle

Service starts up by parsing and validating the configuration file.

Then, the service runs in a loop. On each iteration:
Then, the service runs with one pthread per sensor type. Each sensor thread:
- Polls temperature metrics
- Compute suggested fan speed
- Set chassis fan speed
- Sleep until next interval
- Sleep to incremental times, not static durations. This ensures loops occur
on steady cadence even if one iteration takes a bit longer to process.
- Computes suggested fan speed
- Posts the speed to a shared `speed_bus_t` (mutex + condvar)
- Sleeps until next tick using `clock_nanosleep(CLOCK_MONOTONIC, TIMER_ABSTIME)`
for steady cadence

The main thread waits on the `speed_bus_t` condvar (with a fan-log timeout),
takes the max speed across all sensors, and calls `fan_set_speed()`.

The service gracefully stops on SIGTERM/SIGINT via a `volatile sig_atomic_t
g_shutdown` flag checked in each thread loop.

The service immediately and gracefully stops when requested with command:
`systemctl stop frostd`.
**Note:** IPMI calls are synchronous and blocking. SIGTERM response time may
be up to one IPMI timeout period (~5–10 seconds) while an IPMI call completes.

### Tests

Tests are required to confirm requirements and prevent regressions during code
maintenance.

Use module `github.com/stretchr/testify` for `assert` and `require` packages
for simplifying assertions and validation logic.
Use `libcmocka` for test assertions (`assert_int_equal`, `assert_string_equal`,
`assert_float_equal`, etc.). Each test file has its own `main()` function and
is compiled and run independently by `make test`.

End-to-end tests are required for functionality:
- Configuration parsing
- YAML file structure
- Validation for each field with happy path, numeric range errors, and likely special case checks
- Computing aggregate temperature metrics
Shared mock helpers live in `tests/test_helpers.h` and `tests/test_helpers.c`.

Test coverage required for:
- Configuration parsing (YAML, defaults, validation)
- Computing aggregate temperature metrics (rolling buffer)
- Computing suggested fan speeds from mock temperature samples
- Reading actual CPU temperature metrics
- Reading actual NVIDIA GPU temperature metrics using `nvidia-smi`
- Reading CPU temperature metrics via mock IPMI vtable
- Reading GPU temperature metrics via mock command runner
- Fan IPMI control (ReadFanSpeeds, SetSpeed) via mock IPMI vtable

### Error Handling

Expand All @@ -165,18 +200,17 @@ next iteration when fan speed is suggested again.

## Launch From Source

The repository will provide a `make run` target that will:
- Call `go run` to launch the service using the configuration file `dev.yaml`.
- `dev.yaml` is a copy of the default configuration file used for installing
`/etc/frostd.yaml`.
- Log output goes to stdout instead of a log file.
The repository provides a `make run` target that:
- Builds the service binary
- Launches it using the configuration file `dev.yaml`
- Log output goes to stdout (since `dev.yaml` has no `log_file` set)

## Software Package Installation

The repository will provide a `make package` target that will:
- Build the executable
- Build a Debian .deb package that can be installed with `apt install` on
Debian and Ubuntu Linux OS
The repository provides a `make package` target that:
- Builds the executable
- Builds a Debian .deb package installable with `apt install` on
Debian and Ubuntu Linux OS

The package includes the compiled executable, default configuration for
`/etc/frostd.yaml`, and systemd service configuration.
Expand All @@ -196,10 +230,18 @@ not a literal filename. Place the directive on the line before its definition,
not as a single directive for all targets. This helps prevent forgetting to
update the list.

### Golang
### C

Write code targeting C23 (`-std=c2x` flag for GCC 13). Follow standard C best
practices: const-correctness, error-checked return codes, no implicit fallthrough.

Write code for latest Golang version. Follow Golang's current standards of code
style and best practices as outlined in Effective Go by Google.
- Compile flags: `-std=c2x -D_GNU_SOURCE -Wall -Wextra -Wpedantic`
- No global mutable state except `volatile sig_atomic_t g_shutdown` in main.c
- Memory ownership: functions that allocate with `malloc` expose a matching
`*_free()` function; the caller is responsible for calling it.
- Error reporting: functions return -1 (or NULL) on failure and write a
human-readable message into a caller-supplied `char *errbuf, int errbuflen`
parameter pair.

## License

Expand Down
52 changes: 40 additions & 12 deletions Makefile
Original file line number Diff line number Diff line change
@@ -1,25 +1,53 @@
BINARY = frostd
GOLANGCI_LINT = ./bin/golangci-lint
GOLANGCI_LINT_VERSION = v2.11.4

CC = gcc
CFLAGS = -std=c2x -D_GNU_SOURCE -Wall -Wextra -Wpedantic \
$(shell pkg-config --cflags libcyaml libipmimonitoring libfreeipmi libmicrohttpd)
LIBS = $(shell pkg-config --libs libcyaml libipmimonitoring libfreeipmi libmicrohttpd) \
-lpthread -lm

TEST_CFLAGS = $(CFLAGS) $(shell pkg-config --cflags cmocka)
TEST_LIBS = $(LIBS) $(shell pkg-config --libs cmocka)

SRCS = src/config.c src/cpu.c src/fan.c src/gpu.c src/ipmi.c \
src/log.c src/metrics.c src/prometheus.c src/service.c

TEST_SRCS = tests/test_config.c tests/test_metrics.c tests/test_fan.c \
tests/test_gpu.c tests/test_cpu.c

$(BINARY): $(SRCS)
$(CC) $(CFLAGS) -o $(BINARY) src/main.c $(SRCS) $(LIBS)

.PHONY: build
build:
go build -o $(BINARY) .
build: $(BINARY)

.PHONY: run
run:
go run . -c dev.yaml
run: build
./$(BINARY) -c dev.yaml

.PHONY: test
test:
go test -race ./...

$(GOLANGCI_LINT):
curl -sfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b ./bin $(GOLANGCI_LINT_VERSION)
$(CC) $(TEST_CFLAGS) -o test_config src/config.c src/log.c \
tests/test_config.c $(TEST_LIBS) && ./test_config
$(CC) $(TEST_CFLAGS) -o test_metrics src/metrics.c \
tests/test_metrics.c tests/test_helpers.c $(TEST_LIBS) && ./test_metrics
$(CC) $(TEST_CFLAGS) -o test_fan src/fan.c src/metrics.c \
tests/test_fan.c tests/test_helpers.c $(TEST_LIBS) -lm && ./test_fan
$(CC) $(TEST_CFLAGS) -o test_gpu src/gpu.c \
tests/test_gpu.c tests/test_helpers.c $(TEST_LIBS) && ./test_gpu
$(CC) $(TEST_CFLAGS) -o test_cpu src/cpu.c \
tests/test_cpu.c tests/test_helpers.c $(TEST_LIBS) && ./test_cpu

.PHONY: lint
lint: $(GOLANGCI_LINT)
$(GOLANGCI_LINT) run
lint:
cppcheck --std=c2x --enable=warning,style,performance \
--suppress=missingIncludeSystem \
--suppress=syntaxError \
src/ 2>&1

.PHONY: clean
clean:
rm -f $(BINARY) test_config test_metrics test_fan test_gpu test_cpu

.PHONY: install
install: build
Expand Down
14 changes: 12 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,10 +36,20 @@ This allows for a measurable power reduction at idle.

- Dell PowerEdge 12th generation server (e.g. R720)
- Debian or Ubuntu Linux, x86-64
- Go 1.26+ (build only)
- `make` (build only)
- Compatible NVIDIA driver and CUDA toolkit (GPU monitoring only)

### Build requirements

- GCC 9+ (GCC 13+ recommended for C23 support)
- `make`
- `libcyaml-dev` (YAML parsing)
- `libyaml-dev` (libcyaml dependency)
- `libipmimonitoring-dev` (IPMI sensor reads)
- `libfreeipmi-dev` (IPMI raw commands)
- `libmicrohttpd-dev` (Prometheus HTTP server)
- `libcmocka-dev` (unit testing)
- `cppcheck` (static analysis)

## Dev Tooling
### Build

Expand Down
Loading
Loading