[FEATURE] Analog (ADC/DAC) interfaces unification and better API

[PiyushPatle26]

Is your feature request related to a problem? Please describe.

Piyush Patle
Related: #16916

Overview

This project aims to define a clear and portable interface contract for the ADC subsystem in Apache NuttX.

Currently, ADC behavior varies significantly across drivers, making it difficult to write applications that work across platforms without conditional compilation. This proposal introduces a capability-driven, layered API that standardizes core functionality while preserving hardware flexibility and backward compatibility.

Motivation

While studying the ADC subsystem, several structural issues became evident:

• Ambiguous read() behavior: The return format depends on buflen % N, which can silently omit channel information. This is already flagged by an upstream REVISIT comment.

• No standard channel selection mechanism: Applications must use a poll-and-discard loop, which is inefficient and non-deterministic.

• No capability discovery mechanism: Hardware differences (resolution, DMA, calibration, etc.) require #ifdef-based application logic.

• Driver inconsistency: For example, rp2040_adc.c returns -ENOTTY for IOCTLs implemented by STM32 and ESP32, indicating no defined conformance model.

These issues collectively indicate the absence of a well-defined subsystem contract.

Describe the solution you'd like

Proposed Approach

The proposed solution adds a layered API model to the ADC subsystem to make it more organised and consistent while still allowing for different hardware capabilities. The design's main idea is to create a small required interface that all drivers must use. This means that read() will always return a struct adc_msg_s, ANIOC_GET_CAPS will be used to find out what capabilities are available, and ANIOC_SET_CHANNEL will be used to make sure that channels can be chosen in a predictable way. Optional layers add more features to platforms that support them, like controlling the resolution, calibrating the runtime, setting the voltage reference, streaming over DMA, and triggering events based on thresholds. To make sure that older drivers still work, existing driver-specific IOCTLs stay the same. The main goal is to make things portable by finding out what they can do, make sure unsupported features are handled clearly with -ENOTSUP, and not break any apps that are already out there.

For more Detailed Version: Proposal

Describe alternatives you've considered

No response

Verification

• I have verified before submitting the report.

[acassis]

@PiyushPatle26 something I noticed: the title includes DAC, but you missed it in your text. Also you didn't include nothing about creating Documentation about these new subsystems. Same repeats on your proposal.
@michallenc @raiden00pl please review, tomorrow is the GSoC candidade deadline.

[PiyushPatle26]

@acassis Thanks for pointing this out.

Regarding DAC, the project title refers to broader analog interface unification, but the current scope is intentionally focused on the ADC subsystem as the first step. This is explicitly defined in the proposal, where ADC is treated as the primary target due to its higher complexity (asynchronous input, buffering, DMA, multi-channel sequencing), while DAC is planned as future work once the ADC interface is stabilized.

[linguini1]

I read through your detailed proposal:

• What do you mean by using mmap as future work? (p. 6)
• Are you sure that every ADC can signal when a new value is ready?
• What is the RP2040s round-robin ADC scheduling?
• What is the benefit of the per-fd state structs?
• I think capabilities are bitter implemented as a single caps bitfield as opposed to bool members, but someone else can correct me if that's misguided
• What is the value of max_open_fds?

Nice that you included a testing section, maybe a test suite in nuttx-apps can be part of your deliverables.

[PiyushPatle26]

@linguini1 thanks for the suggestion, will include test suite in nuttx-apps! I’ll address each point below:

What do you mean by using mmap as future work? (p. 6)

For DMA-capable ADCs, a zero-copy interface could be exposed as an optional capability, but it introduces synchronization, cache coherency, and multi-reader challenges. This is why it is deferred to future work pending stabilization of the core API.

Are you sure that every ADC can signal when a new value is ready?

actually correct, that was too broadly stated.
What I meant is that every compliant ADC driver eventually calls adc_receive() when a sample is available. However, how the lower-half detects that varies by hardware: some MCUs (like STM32/ESP32) use end-of-conversion interrupts, while others (like RP2040) trigger based on FIFO thresholds.

From the upper-half perspective, poll/notification still works in all cases, only the timing and latency differ depending on the hardware.

What is the RP2040s round-robin ADC scheduling?

The RP2040 ADC uses a round-robin mode: you select a set of channels, and the hardware continuously cycles through them, pushing results into a FIFO and triggering interrupts at a set threshold. There’s no way to sample a specific channel on demand, it always rotates through enabled channels. Because of this, I set supports_set_channel = false.
I also didn’t expose it as ANIOC_START_STREAM, since its behavior (FIFO + interrupts) is quite different from STM32-style DMA streaming, and treating them the same would hide that difference.

What is the benefit of the per-fd state structs?

With a device-global channel setting, two applications opening /dev/adc0 can interfere: one ANIOC_SET_CHANNEL call overwrites the other, leading to incorrect or inconsistent data. Per-fd state avoids this. Each open gets its own channel configuration and buffer, so samples are delivered only to the relevant file descriptor. This isolates multiple users and prevents them from affecting each other.

It also makes channel switching cleaner, since only that fd’s buffer is reset rather than changing global device state.
There can be few alternatives, but each has some trade-offs.

I think capabilities are bitter implemented as a single caps bitfield as opposed to bool members, but someone else can correct me if that's misguided

It would allow us checking multiple capabilities efficiently, and aligns with existing patterns in NuttX.
so I think this way is btter

What is the value of max_open_fds?

Real thing is If too many opens occur, adc_open() will naturally fail with -ENOMEM when the heap is exhausted. It's more like how many concurrent opens are realistically supported based on memory and buffering. I’m open to removing it if it’s not considered useful.

[linguini1]

That clarifies all my questions, thanks!

Real thing is If too many opens occur, adc_open() will naturally fail with -ENOMEM when the heap is exhausted. It's more like how many concurrent opens are realistically supported based on memory and buffering. I’m open to removing it if it’s not considered useful.

I think it is better to rely on the existing failure mechanisms. Realistically, I don't see what a user can do by checking the max fds member, so I'm not sure it's useful. That is a very minor detail of your proposal though.

[PiyushPatle26]

Thanks for the review! I’ll drop max_open_fds from the struct

Would love to get feedback from other mentors as well.

[acassis]

Please confirm if you submitted the proposal before the deadline yesterday?

[PiyushPatle26]

Please confirm if you submitted the proposal before the deadline yesterday?

Yes! I have submitted the proposal