Ringbuf Reader broken on 32-bit systems due to atomic misalignment

[ebirukov]

When running the built-in tests of ringbuf.Reader on a 32-bit system (e.g., i386), some tests fail due to incorrect behavior of the ring buffer, where unconsumed data appears to remain in the buffer, and expected errors like os.ErrDeadlineExceeded or ErrFlushed are not returned after all samples are read.

This appears to be caused by misaligned access to 64-bit atomic variables (prod_pos, cons_pos) in the ring buffer implementation.

System info:

Architecture: 386 (32-bit x86)

Kernel: Linux 6.1

Go version: 1.24

How to reproduce

Run the ringbuf tests on a 32-bit Linux system

Tests should pass, returning expected ErrFlushed or os.ErrDeadlineExceeded.

=== RUN   TestReaderNoWakeup
    reader_test.go:330: Expected os.ErrDeadlineExceeded from third Read but got <nil>
--- FAIL: TestReaderNoWakeup (0.00s)

=== RUN   TestReaderFlushPendingEvents
    reader_test.go:390: Expected ErrFlushed from third Read but got <nil>
--- FAIL: TestReaderFlushPendingEvents (0.01s)

Version information

github.com/cilium/ebpf v0.19.0

[lmb]

Yeah, this is very possible. We don't have CI for 32bit machines and there are BTF incompatibilities as well. So it's in effect not supported, we need to update the README.

Overall the eBPF ecosystem doesn't invest into 32 bit, so there will be more breakage.

[ebirukov]

Yeah, this is very possible. We don't have CI for 32bit machines and there are BTF incompatibilities as well. So it's in effect not supported, we need to update the README.

Overall the eBPF ecosystem doesn't invest into 32 bit, so there will be more breakage.

I understand that 32-bit support is not a priority in the eBPF ecosystem.

That said, this issue affects not only the test suite, but also real-world usage of ringbuf.Reader. Specifically:
If I run an infinite loop using reader.Read() expecting it to block when the buffer is empty, this does not work correctly on 32-bit systems. Instead of blocking, Read() keeps returning the last sample repeatedly, which breaks consumers that rely on blocking behavior.

I’ve experimented with replacing *uint64 fields (prod_pos, cons_pos) in ringReader with *uint32, along with the necessary logic updates. This workaround fixes the behavior — Read() starts blocking again on empty buffers as expected on 32-bit.

That said, I understand this fix is not suitable for production: it likely impacts performance and diverges from the ringbuf kernel implementation, which uses uint64 bpf_ringbuf_hdr.

For now, it looks like I’ll switch to using perf.Reader, which behaves correctly on 32-bit.

Still, I think it would be helpful to document this limitation more explicitly — not just in the README (regarding 32-bit support in general), but also in the ringbuf.Reader Go documentation, to warn users that blocking behavior is broken on 32-bit platforms.

[lmb]

Feel like sending a PR? We could add a BUGs section like in sync/atomic for example.

Could also return an error on 32 bit platforms by checking for unsafe.Sizeof(uintptr(0)) != 8 in the ringbuf reader..

[ebirukov]

Feel like sending a PR? We could add a BUGs section like in sync/atomic for example.

Could also return an error on 32 bit platforms by checking for unsafe.Sizeof(uintptr(0)) != 8 in the ringbuf reader..

I might be missing some deeper context or expertise here, but I tried modifying the ringbuf reader implementation to use uint32 instead of uint64 for the prod_pos and cons_pos pointers. This change made all the ringbuf tests pass on both 32-bit and 64-bit systems.

My own use case, which previously failed to block properly on empty buffers (returning stale data repeatedly), now works correctly as well after switching to uint32.

From what I can see in the kernel sources (e.g. struct bpf_ringbuf_hdr using 32-bit fields for len and pg_off, and consumer_pos/producer_pos accessed as unsigned long), this seems like a viable option. At least empirically, things behave correctly now.

If this sounds reasonable, I’d be happy to send a PR with the change.

Let me know if this direction seems acceptable or if there are known kernel-side assumptions that make this invalid or unsafe in production.

[lmb]

I might be missing some deeper context or expertise here, but I tried modifying the ringbuf reader implementation to use uint32 instead of uint64 for the prod_pos and cons_pos pointers. This change made all the ringbuf tests pass on both 32-bit and 64-bit systems.

Makes sense for 32 bit. I suspect that on 64 bit the tests never write enough data to trigger the difference between 32 and 64 bit.

The answer is most likely to change accesses to use uintptr for producer and consumer offset. See https://pkg.go.dev/sync/atomic#LoadUintptr and friends. By all means submit a PR, unfortunately we won't be able to test this in CI.

[joshuamcbeth]

#1843 passes all tests on 32-bit and 64-bit platforms using uintptr for the ringbuf producer and consumer position pointers

root@debian-32bit:/home/jmcbeth/ebpf/ringbuf# /home/jmcbeth/go/bin/go test -v
=== RUN   TestRingbufReader
=== RUN   TestRingbufReader/send_one_short_sample
=== RUN   TestRingbufReader/send_three_short_samples,_the_second_is_discarded
=== RUN   TestRingbufReader/send_five_samples,_every_even_is_discarded
--- PASS: TestRingbufReader (0.00s)
    --- PASS: TestRingbufReader/send_one_short_sample (0.00s)
    --- PASS: TestRingbufReader/send_three_short_samples,_the_second_is_discarded (0.00s)
    --- PASS: TestRingbufReader/send_five_samples,_every_even_is_discarded (0.00s)
=== RUN   TestReaderBlocking
--- PASS: TestReaderBlocking (0.10s)
=== RUN   TestReaderNoWakeup
--- PASS: TestReaderNoWakeup (0.00s)
=== RUN   TestReaderFlushPendingEvents
--- PASS: TestReaderFlushPendingEvents (0.01s)
=== RUN   TestReaderSetDeadline
--- PASS: TestReaderSetDeadline (0.00s)
PASS
ok  	github.com/cilium/ebpf/ringbuf	0.119s
root@debian-32bit:/home/jmcbeth/ebpf/ringbuf# uname -a
Linux debian-32bit 6.1.0-37-686-pae #1 SMP PREEMPT_DYNAMIC Debian 6.1.140-1 (2025-05-22) i686 GNU/Linux
root@debian-32bit:/home/jmcbeth/ebpf/ringbuf# /home/jmcbeth/go/bin/go version
go version go1.24.5 linux/386