[Feedback needed] Proposal for ADC API

[Duc Doan]

Hello,

I would like to propose an ADC API that aims to create an interface for
reading analog value conveniently with blocking/non-blocking styles and
support custom transfer function for each pin. The API depends on the
new GPIO API. 

Here are some features of the ADC API:
- Blocking/non-blocking read
- Interrupt
- Assign a transfer function to a pin, so that the result of a read()
function may already be converted to a desired output
- Setting some common options: resolution, data alignment

The changes I needed to make to the GPIO API:
- Add members to rtems_gpio struct: adc_handlers, adc_tf (only if
option BSP_ENABLE_ADC is defined 1)

I implemented ADC for STM32F4 using this API. The current state of
STM32F4 ADC:
- Using single channel conversion, regular group
- Pins that belong to multiple ADCs use ADC1
- Non-blocking read uses EOCS interrupt
- Supports up to 3 user-defined ISR, one for each ADC

Example API calls:

/************************************/
// Get GPIO objects and configure pin in ANALOG mode
rtems_gpio_get(POT_VPIN, &pot);
rtems_gpio_init(pot);
rtems_gpio_set_pin_mode(pot, RTEMS_GPIO_PINMODE_ANALOG);
rtems_gpio_set_pull(pot, RTEMS_GPIO_NOPULL);

// Setting resolution
rtems_adc_set_resolution(pot, 10);

// Blocking read
rtems_adc_read_raw(pot, &pot_value);

// Non-blocking read
rtems_adc_start_read_nb(pot);
rtems_adc_read_raw_nb(pot, &pot_value);

// Reading with transfer function y = 6x + 5
uint32_t params[] = {6, 5};
rtems_adc_assign_tf(pot, linear1, params);
double tf_result;
rtems_adc_read(pot, &tf_result);
...
double linear1(void *params, uint32_t raw) {
    uint32_t *p = (uint32_t *) params;
    return ((double) raw) * p[0] + p[1];
}
...
/**********************************/

Sample applications can be found in the RTEMS_ADC_* folders in this
repo: https://github.com/dtbpkmte/GSoC-2022-RTEMS-Sample-Apps

Please have a look at these files:
- Modified GPIO API:
https://github.com/dtbpkmte/GSoC-2022-RTEMS/blob/adc-api/bsps/include/bsp/gpio2.h
https://github.com/dtbpkmte/GSoC-2022-RTEMS/blob/adc-api/bsps/shared/dev/gpio/gpio.c
- ADC API:
https://github.com/dtbpkmte/GSoC-2022-RTEMS/blob/adc-api/bsps/include/bsp/adc.h
https://github.com/dtbpkmte/GSoC-2022-RTEMS/tree/adc-api/bsps/shared/dev/adc
- STM32F4 GPIO:
https://github.com/dtbpkmte/GSoC-2022-RTEMS/blob/adc-api/bsps/arm/stm32f4/include/bsp/stm32f4_gpio.h
https://github.com/dtbpkmte/GSoC-2022-RTEMS/blob/adc-api/bsps/arm/stm32f4/gpio/gpio.c
- STM32F4 ADC:
https://github.com/dtbpkmte/GSoC-2022-RTEMS/blob/adc-api/bsps/arm/stm32f4/include/bsp/stm32f4_adc.h
https://github.com/dtbpkmte/GSoC-2022-RTEMS/blob/adc-api/bsps/arm/stm32f4/adc/adc.c

The code still has bugs and I am fixing/writing test applications and
adding documentation. I would appreciate all feedback. Thank you very
much.

Best,

Duc Doan