Confusion about Zephyr ADC API semantics

Marti Bolivar


I've been reading through the ADC API, its users, and its test cases,
and I'm confused about the semantics of struct adc_seq_entry, in
particular the field named "buffer". The API docs are vague and the
users contradict each other; something seems wrong to me.

(I volunteer to try to improve the documentation if we can clear
things up; I'm working on an ADC driver and would like to make sure
I'm doing the right thing.)

The main header says "buffer" is a byte array:

But it doesn't say anything about the contents. That's strange,
especially since common ADC IPs can do 12+ bit conversions. (I at
least expected a u16*, and something written about the left- or
right-alignment of sample data, e.g. how a 12 bit sample is stored in
a 16 bit word.)

That same header only has this to say about the returned values from
an adc_read() call:

* The sample data can be retrieved from the memory buffers in
* the sequence table structure.

So I looked at the API users to find out more, but the results were
even more confusing.

This "simple" test wants to interpret the results as though the buffer
field points at an array of u32 (note the _print_sample_in_hex
implementation and the "delta" printk in adc_test):

It also says buffer should be void*, which isn't true:

This "api" test thinks buffer is u16*:

The ADC-based grove temperature driver treats Zephyr samples as if
they were 12 bit right aligned values in a u16 array, and has a
comment saying that's the common convention:

Can anyone clarify what the correct interpretation of this field is?


Join to automatically receive all group messages.