libiphb-timerfd

A small, self-contained reimplementation of Nemomobile's libiphb — the "IP heartbeat" client library — backed by a plain Linux timerfd instead of a heartbeat daemon.

It builds and installs as libiphb (same soname, same public headers, same pkg-config name), so it is a drop-in ABI-compatible replacement. The project is named libiphb-timerfd only to distinguish this implementation from the original.

Background

Historically libiphb was a thin client that talked to a heartbeat server living inside the dsme daemon over a Unix-domain socket. The purpose of that server was to coalesce the wakeups of many clients onto a few shared "slots" so the device could stay suspended as long as possible.

On kernels >= 3.10 the dsme server was itself implemented on top of a timerfd (using CLOCK_BOOTTIME_ALARM to wake the device out of suspend). The socket round-trip to dsme therefore bought nothing but a process dependency: the kernel already provides everything needed to arm a suspend-waking timer from the client itself.

AsteroidOS no longer ships dsme, so this implementation drops the socket and the server entirely. Each iphb_t handle owns a private timerfd. Wakeups are armed with timerfd_settime() and consumed by read()ing the 8-byte expiration count.

Suspend wakeups and CAP_WAKE_ALARM

When a "resume" wakeup is requested, the handle's timer uses CLOCK_BOOTTIME_ALARM so it can pull the device out of (auto)suspend. Creating such a timer requires the CAP_WAKE_ALARM capability. If the calling process does not have it, iphb_open() transparently falls back to CLOCK_BOOTTIME, which still fires correctly while the device is awake but will not wake it from suspend.

Callers that need suspend-waking heartbeats must therefore run with CAP_WAKE_ALARM. For a systemd service the clean way to grant it is:

[Service]
AmbientCapabilities=CAP_WAKE_ALARM

(root processes already have it; unprivileged ones need it granted explicitly).

ABI compatibility

The public API and ABI are unchanged from the original libiphb.h. There is a single behavioural difference visible to callers who drive the descriptor themselves:

The file descriptor returned by iphb_get_fd() is a timerfd, not a socket. It must be drained with read() (which yields a uint64_t expiration count) rather than recv(), which would fail with ENOTSOCK.

Callers that use iphb_wait()/iphb_wait2() in blocking mode, or that use the iphb_discard_wakeups() / iphb_I_woke_up() helpers, need no changes.

Because there is no longer a central server, iphb_get_stats() reports a single local client so callers that sanity-check the struct keep working.

Building

make                 # builds libiphb.so.0.0.0
make install DESTDIR=/ PREFIX=/usr

This installs the shared library, the iphbd/libiphb.h header, and a libiphb.pc pkg-config file.

License

LGPL-2.1-or-later. See COPYING.

The public interface (libiphb.h) originates from dsme, Copyright (C) Nokia Corporation; the timerfd implementation is part of AsteroidOS.