RP1 GPCLK DKMS

RP1-GPCLK-DKMS provides a stock-kernel, out-of-tree Linux module for bounded control of the Raspberry Pi RP1 GPCLK0 peripheral. It is the kernel component used by WsprryPi on Raspberry Pi 5-family hardware and is distributed as source that DKMS builds for the operator's installed kernel.

The module supplements the stock Raspberry Pi clk-rp1 driver. It does not replace the kernel clock provider, require a custom kernel, or expose arbitrary MMIO, DMA channels, register writes, or GPIO routes to userspace.

Release status

0.9.0 is the current pre-release development baseline with the canonical userspace interface and independent GPIO4/GPIO20 runtime routes. Source/DKMS/module version 0.9.0 and Debian version 0.9.0-1 are coordinated labels, not frozen artifacts or qualification. See the development identity and migration contract. The development baseline is unpublished and not release-qualified. Experimental is a runtime compatibility classification, not a release status. It identifies a bounded development build and route; it does not qualify installation, clock output, transmission, RF use, or product behavior.

Safety

Installing the package does not select an overlay, edit boot configuration, load the module, enable a clock, change GPIO state, or authorize transmission. Both overlays are installed inactive. Route selection, root-only endpoint use, and product operation are separate administrative decisions. Compatibility IDs are stable across kernel releases; exact kernel and board identities remain visible in build and diagnostic records.

Unknown or ambiguous RP1 topology, routes, resources, signing state, compatibility state, or cleanup state fails closed. Eligibility is established from the RP1 device-tree/provider/resource structure, not a Raspberry Pi product model allowlist. Structural acceptance does not make a kernel or board qualified. There is no /dev/mem, raw userspace MMIO, custom-kernel, arbitrary-route, or alternate-transmitter fallback.

Installation

For exact-commit development installation, follow the source-development guide. The current 0.9.0 package is an unpublished development artifact. Review the identity and migration contract before installing over an existing version.

DKMS builds the module for eligible installed Raspberry Pi kernel headers. The package installs the GPIO4 and GPIO20 overlays but leaves both inactive. Review the package lifecycle guide before making any route, boot, module, or signing changes.

To build an unpublished development package from the reviewed source checkout:

dpkg-buildpackage -us -uc -b

Building from source requires the Debian packaging toolchain, DKMS development support, and device-tree compiler. A package build is compatibility evidence only; it does not qualify installation or hardware behavior on a target.

Interface

The byte-authoritative userspace header is include/uapi/linux/rp1_gpclk.h. The userspace interface contract describes queries, root-only ownership, generic finite events, state, bounded cancellation, passive snapshots, and immutable test inhibition. This unreleased interface has no legacy layouts or compatibility fallbacks.

The API supports:

• QUERY for capabilities and compatibility state;
• ACQUIRE and RELEASE for exclusive ownership;
• bounded generic tone/gap event submission with fixed coherent DMA chunks;
• GET_STATE for stable runtime and terminal state;
• GET_SNAPSHOT for passive, non-owning state observation; and
• STOP for generation-specific bounded cancellation.

GPIO4 and GPIO20 are independent administrative routes. Qualification or selection of one route never transfers to the other.

Diagnostics and administration

rp1-gpclk-diagnostics produces a bounded, read-only JSON report without installing, loading, binding, repairing, or operating hardware. See Read-only diagnostics.

Module signing and trust enrollment remain administrator-owned. The package does not ship a private key or weaken the host's signing policy. See Module signing.

Development

Ordinary development and validation are offline, unprivileged, hardware-free, and safe to repeat:

make check
make package-check

For a maintainer-facing build/install/load workflow from an exact unreleased Git commit, see Exact-source development lifecycle. That path is package-independent and remains explicitly Experimental; it does not create release or qualification identity. Its route-neutral mode installs the exact DKMS source and module without selecting a GPIO route, installing an overlay, loading the module, or enabling output. Route administration and loading remain later explicit operations.

The maintained test inventory and the distinction between automatic, parameterized build, and explicitly authorized hardware checks are documented in Testing.

Release generation and publication are disabled pending a reviewed current release pipeline. Use the development installer or local Debian build above.

Build the module against an explicitly selected local kernel build tree:

make KERNEL_BUILD=/path/to/kernel/build

Compilation proves build compatibility only. It does not qualify module loading, GPIO behavior, timing, coexistence, cleanup, transmission, RF, or an operator installation.

Read CONTRIBUTING.md, the module contract before contributing. See LICENSE.md for licensing terms.

The external qualification boundary is defined by the Harness integration contract.

Route workflows

GPIO4 and GPIO20 are separate routes. With neither overlay active, the route is none and there is no endpoint; two active overlays are ambiguous and rejected.

Administration profile	Workflow
Packaged manager	Configure a route, reboot and reconcile
Source-development manager	Passive query and current-boot adoption
Opt-in runtime manager	Rebootless GPIO4/GPIO20 switching and recovery to none

The runtime profile uses the runtime controller and application restoration. For diagnosis and removal, see diagnostics and module lifecycle. Passive observations and operation authorization are distinct parts of the userspace interface contract; route selection never authorizes transmission.

Project boundary

• This repository owns the kernel module, canonical UAPI, overlays, DKMS packaging, module lifecycle tooling, compatibility metadata, and releases.
• WsprryPi/WSPR-Transmitter owns its userspace adapter and conversion into this UAPI.
• WsprryPi/WsprryPi owns application policy, configuration, scheduling, installer orchestration, operator workflow, and product qualification.

The projects coordinate through tagged artifacts, the canonical UAPI, compatibility metadata, and explicit cross-repository validation. WsprryPi does not consume this repository's moving default branch.

Licensing

Original project work is MIT licensed wherever practical. Kernel-facing module source and device-tree sources are dual-licensed under GPL-2.0-only OR MIT. The userspace-visible UAPI uses (GPL-2.0-only WITH Linux-syscall-note) OR MIT. Imported material retains its original license and attribution. See LICENSE.md.