U-Boot SCMI Clocks: Separate Transport Errors, Firmware Status and Rate Readback

A clock-rate request can reach platform firmware and still be
rejected. It can also be accepted while the subsequent rate readback
fails. Treating every nonzero result as “the mailbox is broken” loses
the boundary that matters. U-Boot v2025.01’s SCMI clock driver exposes a
clear sequence for diagnosing these cases.

This article concerns the tagged SCMI clock-rate path used by a
product’s U-Boot build, including one produced through Buildroot. It
does not assume a particular SCMI transport or promise that a platform
supports every requested frequency. Firmware policy and physical clock
accuracy require their own evidence.

A rate change
contains more than one operation

scmi_clk_set_rate() constructs a
SCMI_CLOCK_RATE_SET message with the clock identifier, a
rate split into low and high words, and the
SCMI_CLK_RATE_ROUND_CLOSEST flag. It first calls
devm_scmi_process_msg(). Only after that returns without a
negative error does it interpret the response’s SCMI status. Tagged
clock driver.

The message-processing helper finds the SCMI protocol device and
routes the request through the agent’s transport operation. Failure can
occur before a meaningful firmware status is available, for example when
no appropriate protocol device is found or the agent has no
message-processing operation. That is a different observation from
receiving a valid response that refuses the request. SCMI
agent implementation.

Preserve the
firmware status as a distinct result

U-Boot maps SCMI status codes into ordinary error values. In this
release, SCMI_DENIED maps to -EACCES,
SCMI_OUT_OF_RANGE to -ERANGE, and
SCMI_NOT_SUPPORTED to -EOPNOTSUPP. An
unrecognized nonzero status becomes -EPROTO. Those mappings
are useful evidence, but they do not identify the underlying
platform-policy rule by themselves. Status
conversion table.

For instance, a denied response should prompt investigation of the
requested clock, agent context and firmware policy. Repeatedly adjusting
a transport timeout does not address an explicit denial. Conversely, a
transport failure supplies no basis for claiming that the firmware
evaluated and rejected the rate.

Capture the operation boundary alongside its code. A final generic
error message alone may hide whether the failure came from request
transport, the set response or the next readback. Instrumentation should
identify the clock ID and requested rate without collapsing these stages
into one “set failed” label.

The returned
rate is obtained by another message

After an accepted set response, scmi_clk_set_rate()
calls scmi_clk_get_rate(). That function sends
SCMI_CLOCK_RATE_GET, checks message-processing and
firmware-status errors, then combines the returned rate words. The final
result of the setter can therefore be a readback error even though the
preceding set request was accepted. The code does not roll back the rate
when that readback fails. Set
and get paths.

The request’s round-closest flag also means that requesting a value
is not an exact-frequency assertion. Compare the returned rate with the
peripheral’s acceptable range instead of assuming it must equal the
requested number. A firmware-reported rate is still not an independent
measurement of a pin or oscillator.

The clock API returns an unsigned-long rate while documenting
negative error codes as possible results. A caller must apply the API’s
error convention before formatting the value as hertz or calculating a
divisor. Otherwise an encoded error can appear as an implausibly large
positive frequency. The same type also makes the build’s integer width
relevant to representable rates. Clock
API contract.

Qualify
the sequence rather than only the target frequency

Use a firmware model or controlled platform fixture to distinguish
four outcomes: transport rejection, explicit firmware denial, accepted
set with a successful rounded readback, and accepted set followed by
readback failure. Check how the consumer handles each outcome. In the
last case, do not assume the old clock rate remains active merely
because the overall call reports an error.

These are proposed checks, not executed measurements. Their purpose
is to preserve enough evidence to choose the next investigation:
transport integration, firmware permissions, supported rates or
peripheral timing tolerance.