From 3fe7264eedf033ff984c56a9f58074bae4cf8208 Mon Sep 17 00:00:00 2001 From: Dawid Niedzwiecki Date: Wed, 22 Dec 2021 15:38:35 +0100 Subject: zephyr: docs: add ADC documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add documentation for configuring ADC. BUG=b:208435885 TEST=Browse doc in gerrit BRANCH=main Signed-off-by: Dawid Niedzwiecki Change-Id: Ib83af48f84582e7e5bf63808cfbc2fac77faacab Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/3352468 Tested-by: Dawid Niedźwiecki Reviewed-by: Keith Short Commit-Queue: Keith Short --- docs/images/volteer_adc.png | Bin 0 -> 59791 bytes docs/zephyr/zephyr_adc.md | 198 ++++++++++++++++++++++++++++++ docs/zephyr/zephyr_new_board_checklist.md | 1 + 3 files changed, 199 insertions(+) create mode 100644 docs/images/volteer_adc.png create mode 100644 docs/zephyr/zephyr_adc.md diff --git a/docs/images/volteer_adc.png b/docs/images/volteer_adc.png new file mode 100644 index 0000000000..305334ef92 Binary files /dev/null and b/docs/images/volteer_adc.png differ diff --git a/docs/zephyr/zephyr_adc.md b/docs/zephyr/zephyr_adc.md new file mode 100644 index 0000000000..437c53bf80 --- /dev/null +++ b/docs/zephyr/zephyr_adc.md @@ -0,0 +1,198 @@ +# Zephyr ADC Configuration + +[TOC] + +## Overview + +[ADC] is used to measure VBUS, temperature and other values depending on a board. + +## Kconfig Options + +Kconfig Option | Default state | Documentation +:--------------------------------- | :------------ | :------------ +`CONFIG_PLATFORM_EC_ADC` | Enabled | [EC ADC] + +The following options are available only when `CONFIG_PLATFORM_EC_ADC=y`. + +Kconfig sub-option | Default | Documentation +:----------------------------------------------- | :-----: | :------------ +`CONFIG_ADC_SHELL` | n | [CONFIG_ADC_SHELL] +`CONFIG_PLATFORM_EC_ADC_CMD` | y | [ADC cmd] +`CONFIG_PLATFORM_EC_ADC_RESOLUTION` | 10 | [ADC resolution] +`CONFIG_PLATFORM_EC_ADC_OVERSAMPLING` | 0 | [ADC oversampling] +`CONFIG_PLATFORM_EC_ADC_CHANNELS_RUNTIME_CONFIG` | n | [ADC runtime config] + +## Devicetree Nodes + +The EC chip disables all Analog-to-Digital Converters by default. Enable ADC +used on your design by changing the chip-specific ADC `status` property to +`"okay"`. + +ADC properties: + +Property | Description | Settings +:------- | :---------- | :------- +`status` | Enables or disables the ADC module | `"okay"`
`"disabled"` +`label` | Override the EC chip specific label. |`"ADC_"` + +Either Nuvoton NPCX and ITE IT8xxx2 ECs use single a devicetree node `adc0` to +describe ADC, but it supports multiple ADC channels. + +To enable the ADC set the `status` property to `"okay"`: +``` +&adc0 { + status = "okay"; +}; +``` + +### Mapping legacy ADC enums to ADC channels + +The legacy ADC API for the Chromium EC application uses an enumeration (e.g. +`ADC_VBUS`, `ADC_AMON_BMON`) to specify the ADC channel to measure voltage. + +The `named-adc-channels` node creates the mapping between the legacy ADC channels +enumeration and the Zephyr ADC driver's channel_id. +``` +named-adc-channels { + compatible = "named-adc-channels"; + vbus { + label = "VBUS"; + enum-name = "ADC_VBUS"; + io-channels = <&adc0 1>; + /* Measure VBUS through a 1/10 voltage divider */ + mul = <10>; + }; +}; +``` + +Refer to the [named-adc.yaml] child-binding file for details about each property. + +## Board Specific Code + +None required. + +## Threads + +ADC support does not enable any threads. + +## Testing and Debugging + +Unfortunately, the are two `adc` console commands: a [Zephyr](#zephyr-cc) command +and the one implemented in [CrosEC](#crosec-cc). +Only one of them can be enabled with `CONFIG_ADC_SHELL` or +`CONFIG_PLATFORM_EC_ADC_CMD` respectively. + +### Zephyr command {#zephyr-cc} + +The Zephyr `adc` includes the following subcommands: + +Subcommand | Description | Usage +:--------- | :---------- | :---- +`acq_time` | Configure acquisition time | `adc acq_time