Hello again,

Since about a week has passed by with no response, I assume that the
ADC infrastructure is currently unmaintained (or the maintainers are
on vacation), and will do my best to fix the core semantics as best I
can. I will also make a best effort to contact authors of existing ADC
drivers if I need help as regards to changes that might impact those.

I hope and expect to submit some PRs around this in the first week of
2018, now that I've spent a few days hacking on an nRF SAADC driver
and feel I understand the issues a bit better.

Please let me know if you'd like to help!

Thanks,
Marti

On Fri, Dec 15, 2017 at 9:00 PM, Marti Bolivar
<marti@opensourcefoundries.com> wrote:

Hi,

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:

https://github.com/zephyrproject-rtos/zephyr/blob/master/include/adc.h#L39

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):

https://github.com/zephyrproject-rtos/zephyr/blob/master/tests/drivers/adc/adc_simple/src/main.c#L36

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

https://github.com/zephyrproject-rtos/zephyr/blob/master/tests/drivers/adc/adc_simple/src/main.c#L78

This "api" test thinks buffer is u16*:

https://github.com/zephyrproject-rtos/zephyr/blob/master/tests/drivers/adc/adc_api/src/test_adc.c#L53

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:

https://github.com/zephyrproject-rtos/zephyr/blob/master/drivers/grove/temperature_sensor.c#L46

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

Thanks,
Marti