Seven entry points silently acknowledge interrupts by reading the configuration register

[felipebalbi]

In interrupt mode, reading the configuration register is acknowledging an alert. Seven public or internal entry points do it. None of their doc comments say so, and the flags that read consumes are discarded before any caller can see them.

Source

event, the SMBus ALERT Response only clears the pin and not the flags. Reading the configuration register

— datasheet §7.5.3.4, sources/datasheet.txt:926

clears both the flags and the pin.

— datasheet §7.5.3.4, sources/datasheet.txt:927

Code

Every one of these performs a configuration read:

Path	Line (blocking)	Notes
probe()	src/lib.rs:1031	looks like a pure liveness check; is not
read_configuration()	src/lib.rs:1056	the only one where it is arguably obvious
configure()	src/lib.rs:1086	read-modify-write
one_shot()	src/lib.rs:1135	read-modify-write via modify
shutdown()	—	read-modify-write
wait_for_temperature()	src/lib.rs:1216	reads config purely to pick a delay
continuous()	entry + cleanup	twice per call

The async shells mirror all of these. The hysteresis trait impl reaches two reads via read_configuration followed by configure.

Flags are dropped at src/lib.rs:379:

pub(crate) fn decode_config(c: Configuration) -> Config {
    Config {
        thermostat_mode: c.tm(),
        alert_polarity: c.pol(),
        conversion_rate: c.cr(),
        hysteresis: c.hys(),
    }
}

FL, FH and M are not in Config.

Gap

A caller using interrupt mode has no way to know that calling probe() — or wait_for_temperature(), which reads configuration only to compute a sleep duration — destroys a pending alert. The information is not merely undocumented, it is unrecoverable: decode_config projects the register onto the 64 setting combinations and throws FL/FH away, so even the read that consumed the event cannot report it.

This is the general case of which #59 is the acute instance.

Smaller

An effect boundary, not an oversized argument — no wrapper type prevents acknowledgement from happening. What a richer type can do is preserve the flags that the read already consumed, so the event survives to the caller instead of being dropped on the floor.

Note Config is otherwise correctly sized: 2 x 2 x 4 x 4 = 64 inhabitants, exactly matching the documented field combinations. The problem is that it is a settings projection being used as if it were a register snapshot.

Action

• Short: document the interrupt-mode acknowledgement effect on all seven entry points, including the implicit read-modify-write paths and the error/cancellation cases that abort after the read has already landed. Make read_configuration's docs state it returns configurable parameters, not complete hardware state.
• Medium: add an explicitly-named snapshot/acknowledge operation that returns FL/FH alongside the settings.

Do not change read_configuration's return type. Config is exported and v0.6.0 is published; that would be a breaking migration for downstream users.

Related: #58, #59, #60 (completion readback needs M, also dropped here).

---

Audit provenance

Raised by a datasheet-compliance audit of 5e7b8d2 (byte-identical to published crates.io v0.6.0).

id	document	revision	sha256
datasheet	TI TMP108 Datasheet	SBOS663A	ec086250fc4331e7fc923be62173062bbf0fccedad6894c2741b73cd1c084556
an-sbaa588	TI Application Note	SBAA588A	030ca48a844df836f6268e2960b2ea1fdf073eba07ee693b404303efa7848e50
an-sboa431	TI Application Note	SBOA431	97d7fcc22ab7584b80b6464608d41d5ff9d7568a25e4a4398b4a5b12fd52e198
ta-sszt228	TI Technical Article	SSZT228	3a10a4f529a184041deaf9aa0721e9e1baf6fff9379122a689788c61fe8f01c9

Line anchors such as sources/datasheet.txt:927 refer to pdftotext -layout extractions of the documents above. Every quote in this issue was re-grepped against its cited line. TI permalinks are unversioned, so re-derive line numbers if you re-fetch; the sha256 is what pins the bytes.

[felipebalbi]

Confirmed on hardware

Rig: Pico de Gallo v1.1 rev2 (fw v0.11.0) + TMP108 @ 0x48. Raw I2C, no driver involved.

Interrupt mode (TM=1), CR=0.25Hz (4 s period, chosen so two back-to-back reads cannot race the next conversion), THIGH=10 C against an ambient of 23.4 C — so the over-temperature condition is true and stays true for the whole test.

Three consecutive reads of the configuration register:

read #1: [16, 10]  ID=0 CR=00 FH=1 FL=0 TM=1 M=10 | POL=0 HYS=01
read #2: [06, 10]  ID=0 CR=00 FH=0 FL=0 TM=1 M=10 | POL=0 HYS=01
read #3: [06, 10]  ID=0 CR=00 FH=0 FL=0 TM=1 M=10 | POL=0 HYS=01

FH is set on the first read and clear on the next two. Nothing about the physical condition changed — the part was still over temperature throughout. The only thing that happened between read #1 and read #2 is that read #1 occurred.

This confirms datasheet §7.5.3.4 (sources/datasheet.txt:926-927) literally:

Reading the configuration register clears both the flags and the pin.

So every one of the seven entry points listed in this issue destroys interrupt evidence as a side effect, including probe() (which looks like a liveness check) and wait_for_temperature() (which reads config only to pick a sleep duration).

This is the measured premise underneath #58 and #59.