U-Boot ADC Single: The Same Environment Variable Can Contain Raw Counts or Microvolts

A boot-time ADC check can report success while changing the meaning
of its numeric result. In U-Boot v2025.01, adc single
stores microvolts when its conversion helper succeeds, but falls back to
the raw ADC code when that helper fails. Both paths return command
success after a successful acquisition.

If a manufacturing script compares that variable with a voltage
threshold, its first requirement is a stable unit contract. A plausible
number and a zero command status do not establish that contract.

Follow the value-selection
branch

The ADC
command implementation first calls
adc_channel_single_shot(). An acquisition error prints a
diagnostic and returns failure. After obtaining the sample, the command
looks up the ADC device and attempts adc_raw_to_uV().

On successful lookup and conversion, the selected value is the
converted voltage. The console prints both the raw sample and a value
explicitly labeled uV. Otherwise, the selected value is the
raw sample, and the console prints only that number. If an optional
environment-variable name was supplied, env_set_ulong()
receives whichever value the branch selected.

There is no separate unit variable, and conversion failure does not
change the final successful command return. This makes the environment
destination a conditional representation rather than a raw-sample API or
a guaranteed voltage API.

Identify what
conversion actually requires

The ADC
uclass implementation obtains the positive reference value first.
Failure at that step propagates out of the conversion helper. If the
negative reference is available, it is subtracted from the positive
reference; an unavailable negative-reference value is not itself
propagated as a conversion error there.

The helper then obtains the data mask and scales the raw sample by
the resulting reference span, using integer arithmetic. The public
ADC header identifies the output unit as microvolts and defines the
helper’s success/error result separately from that output.

For a conventional nonnegative ADC with valid reference configuration
and a nonzero mask, this explains where the command’s voltage value
comes from. It does not establish calibration accuracy, input settling,
or support for every signed encoding. Those require the actual driver
and electrical design. This article does not prescribe thresholds for
such configurations.

Separate three acceptance
conditions

A reliable qualification result needs three distinct answers:

• Did acquisition produce a new sample?
• Was that sample converted into the required unit?
• Was the intended output variable actually updated?

The command checks the first operation. It uses the second to select
a representation, rather than to reject the operation. It does not
inspect the return from env_set_ulong(). Consequently,
command success alone also cannot prove a fresh environment value was
stored.

A checked scratch sentinel can help detect a missing update, but
cannot identify the unit of a new numeric value. Giving the variable a
name ending in _uv does not change the fallback behavior.
Likewise, a previous successful adc info invocation does
not promise that every later reference lookup will succeed.

Qualify the
interface before using a threshold

For a controlled fixture, capture the raw console form, command
result and destination value together. Exercise a normal reference
configuration, a controlled conversion failure after successful
acquisition, and an acquisition failure. If the environment can reject
the scratch-variable update, cover that separately. These are proposed
cases, not performed tests.

For production automation that requires voltage, a small
board-specific wrapper can expose acquisition validity, conversion
validity and unit explicitly, rejecting an unavailable conversion
instead of silently substituting counts. Validate that wrapper against
the linked driver and reference configuration.

The useful boundary is the representation chosen after sampling.
Physical ADC accuracy can be excellent while a script still compares raw
counts with a microvolt threshold. Make the unit explicit before
deciding what the number means.