Day 42 - IIO Timestamp, FIFO Debug & Scan Mask

🎯 Objectives

• Integrate timestamp into IIO buffered data
• Understand IIO scan layout and alignment
• Debug FIFO streaming issue (I2C transaction boundary)
• Explore scan mask behavior and buffer packing

---

🧠 IIO Data Path Overview

Sensor (STM32)
    ↓
FIFO (fixed frame: ch0~ch3)
    ↓
I2C block read
    ↓
Driver unpack → sample
    ↓
Driver pack (scan mask)
    ↓
IIO buffer (aligned layout + timestamp)
    ↓
Userspace decode

---

📦 Timestamp Integration

Step 1 - Add timestamp channel

IIO_CHAN_SOFT_TIMESTAMP(4)

---

Step 2 - Use timestamp API

iio_push_to_buffers_with_timestamp(indio_dev, data, ts);

---

Step 3 - Buffer must have enough space

• scan buffer must include timestamp space
• alignment must be respected

---

⚠️ Key Concept: scan layout ≠ struct layout

IIO does NOT treat your struct as-is.

Instead:

• uses scan_index
• builds layout dynamically
• enforces alignment (especially for timestamp)

---

📐 Alignment Behavior (Critical)

Example: 1 channel + timestamp

[ch0][padding][timestamp]

• ch0 = 2 bytes
• padding = 6 bytes
• timestamp = 8 bytes

Total = 16 bytes

---

General rule

channel_bytes → align to 8 → timestamp

---

Result (your driver)

enabled channels	total bytes
1	16
2	16
3	16
4	16

---

🔥 FIFO Streaming Bug (Important)

Symptom

• corrupted channel values
• misaligned frames
• inconsistent data

---

Root Cause

FIFO is implemented as a streaming register

FIFO_DATA → byte stream
frame pop only after full read

BUT:

• I2C transaction can be split
• partial read leaves cursor mid-frame
• next read continues incorrectly

---

Fix

Reset FIFO stream state on transaction boundary:

sensor_reg_reset_fifo_stream();

Applied in:

• HAL_I2C_ListenCpltCallback()
• HAL_I2C_ErrorCallback() (AF)

---

🧩 Scan Mask Concept

Hardware vs IIO

Layer	Format
Sensor	fixed frame (ch0~ch3)
IIO	dynamic layout

---

Driver responsibility

Convert:

[ch0][ch1][ch2][ch3]

into:

[ch0][ch2][timestamp]

---

Important insight

scan mask affects buffer layout, not hardware data

---

⚖️ Design Trade-off

Current design

• hardware always outputs full frame
• driver repacks data

Pros

• simple
• stable
• easy debugging

Cons

• extra bandwidth
• scan mask not fully optimized

---

🏁 Summary

• IIO buffer layout is dynamic
• timestamp enforces alignment
• FIFO must respect transaction boundary
• scan mask requires driver-side packing