Day40 - Acquisition Mode & Control Plane Refactor

🎯 Goal

Refactor the control plane of the IIO ADC driver by introducing a mode-based acquisition model, replacing the previous implicit behavior driven by parameter combinations.

---

🔧 Problem Statement (Before Day40)

The driver previously relied on:

• sampling_frequency
• fifo_enable
• internal config bits

to determine behavior.

Issues:

• No clear concept of "mode"
• DRDY / FIFO / idle behavior mixed together
• sampling_frequency = 0 used as implicit "disable"
• Hard to extend (e.g. one-shot)

---

🧠 Design Overview

Introduce acquisition modes as the primary control abstraction.

Supported Modes

Mode	Description
idle	Sensor disabled, no sampling
continuous	Periodic sampling + DRDY IRQ
fifo	Periodic sampling + FIFO + watermark IRQ
one-shot	Reserved (not implemented yet)

---

🧩 Control Plane Design

Single Source of Truth

mode = acquisition behavior

Other parameters become configuration inputs, not behavior drivers.

---

Parameter Roles

Parameter	Role
sampling_frequency	staged configuration
fifo_watermark	staged FIFO parameter
fifo_enable	compatibility wrapper

---

🔄 Staged Parameter Model

Sampling Frequency

• Stored in data->sample_rate_hz
• Behavior:

IDLE mode        → staged only (no hardware write)
ACTIVE mode      → re-apply mode (update hardware)

---

FIFO Watermark

• Stored in data->fifo_watermark
• Behavior:

FIFO mode        → re-apply mode (update hardware)
Other modes      → staged only

---

Rollback Mechanism

If hardware apply fails:

restore previous value

Ensures driver never enters inconsistent state.

---

⚙️ apply_mode() Design

myadc_apply_mode() is the core of Day40.

Responsibilities:

• Map logical mode → hardware config
• Apply staged parameters
• Ensure deterministic state

Example Mapping

IDLE
  ENABLE = 0
  IRQ    = 0

CONTINUOUS
  ENABLE = 1
  DRDY   = 1
  FIFO   = 0
  IRQ    = 1

FIFO
  ENABLE = 1
  DRDY   = 0
  FIFO   = 1
  IRQ    = 1

---

Key Rule

apply_mode() must build final config explicitly

• Do NOT depend on previous config state
• Always generate final state from mode

---

🔌 Data Path Refactor

Before

config bits → decide FIFO / DRDY

After

mode → decide data path

Trigger Handler

switch (mode) {
case CONTINUOUS:
    read_channel();
    break;
case FIFO:
    read_fifo();
    break;
}

---

🔁 Compatibility Layer

fifo_enable

Still exposed for compatibility:

echo 1 → mode = fifo
echo 0 → mode = continuous

But:

mode is the real control source

---

🚫 Removed Behavior

• sampling_frequency = 0 as "disable"
• implicit mode via parameter combinations

---

🧪 Validation Rules

When buffer is enabled

All control changes are rejected:

mode change      → -EBUSY
sampling update  → -EBUSY
watermark update → -EBUSY

---

📌 Summary

Day40 establishes a clean architecture:

• Mode-driven control plane
• Staged parameter model
• Deterministic hardware configuration
• Clear separation of behavior vs configuration

---

🚀 Next Step (Day41)

• one-shot acquisition
• IRQ policy separation
• STM32 register redesign