Currently, clock consumers cannot take any programmatic action based on the
return code of a clock function. This is because there is no
standardization, and generally no way of separating e.g. "there was a major
problem setting the rate for this clock" which usually should not be
recovered from, from "this clock doesn't support setting its rate" or "this
clock doesn't support *this* rate" which could be absolutely fine depending
on the driver.
This commit aims to standardize the acceptable codes which may be returned
from clock operations. In general,
- ENOSYS should be returned when an operation is not supported for a
particular clock.
- ENOENT may be returned if the clock ID is invalid. However, it is
encouraged to move any checks to request() to reduce code duplication.
- EINVAL should be returned for logical errors only (such as requesting an
invalid rate).
Each function has had specific guidance added for when to return each error
code. This is just guidance for now; most of the clock subsystem does not
yet conform to this standard. However, it is expected that new clock
drivers return these error codes.
Additionally, this commit adds expected behavior for each of the clock
operations. I believe these should be mostly straightforward and correspond
to existing behavior. I remember not understanding what the expected
invariants were for several clock functions, so hopefully this should help
out new driver authors. In the future, some of these invariants could be
checked via an optional config option.
Signed-off-by: Sean Anderson <seanga2@gmail.com>
Link: https://lore.kernel.org/r/20231216193843.2463779-4-seanga2@gmail.com
This adds dump function to struct clk_ops which should replace
soc_clk_dump. It allows clock drivers to provide custom dump
implementation without overriding generic CCF dump function.
Reviewed-by: Patrice Chotard <patrice.chotard@foss.st.com>
Tested-by: Patrice Chotard <patrice.chotard@foss.st.com>
Reviewed-by: Sean Anderson <seanga2@gmail.com>
Signed-off-by: Igor Prusov <ivprusov@sberdevices.ru>
[ Fixed parameter name in documentation ]
Signed-off-by: Sean Anderson <seanga2@gmail.com>
Link: https://lore.kernel.org/r/20231109105516.24892-6-ivprusov@sberdevices.ru
When freeing a clock there is not much we can do if there is an error, and
most callers do not actually check the return value. Even e.g. checking to
make sure that clk->id is valid should have been done in request() in the
first place (unless someone is messing with the driver behind our back).
Just return void and don't bother returning an error.
Signed-off-by: Sean Anderson <seanga2@gmail.com>
Reviewed-by: Simon Glass <sjg@chromium.org>
Link: https://lore.kernel.org/r/20220115222504.617013-2-seanga2@gmail.com
This converts the existing driver API docs (clk-uclass.h) to kernel doc
format and adds them to the HTML documentation. Because the kernel doc
sphinx converter does not handle functions in structs very well, the
individual methods are documented separately. This is primarily inspired by
the phylink documentation [1], which uses this trick extensively.
[1] https://www.kernel.org/doc/html/latest/networking/kapi.html#c.phylink_mac_ops
Signed-off-by: Sean Anderson <seanga2@gmail.com>
Tested-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Reviewed-by: Simon Glass <sjg@chromium.org>
Link: https://lore.kernel.org/r/20211222171114.3091780-5-seanga2@gmail.com
It returns the rate which will be set if you ask clk_set_rate() to set
that rate. It provides a way to query exactly what rate you'll get if
you call clk_set_rate() with that same argument.
So essentially, clk_round_rate() and clk_set_rate() are equivalent
except the former does not modify the clock hardware in any way.
Signed-off-by: Dario Binacchi <dariobin@libero.it>
Reviewed-by: Simon Glass <sjg@chromium.org>
Reviewed-by: Sean Anderson <seanga2@gmail.com>
This function name conflicts with our desire to #define free() to
something else on sandbox. Since it deals with resources, rename it to
rfree().
Signed-off-by: Simon Glass <sjg@chromium.org>
When U-Boot started using SPDX tags we were among the early adopters and
there weren't a lot of other examples to borrow from. So we picked the
area of the file that usually had a full license text and replaced it
with an appropriate SPDX-License-Identifier: entry. Since then, the
Linux Kernel has adopted SPDX tags and they place it as the very first
line in a file (except where shebangs are used, then it's second line)
and with slightly different comment styles than us.
In part due to community overlap, in part due to better tag visibility
and in part for other minor reasons, switch over to that style.
This commit changes all instances where we have a single declared
license in the tag as both the before and after are identical in tag
contents. There's also a few places where I found we did not have a tag
and have introduced one.
Signed-off-by: Tom Rini <trini@konsulko.com>
Clocks may support multiple parents: this change introduces an
optional operation on the clk-uclass to set a clock's parent.
Signed-off-by: Philipp Tomsich <philipp.tomsich@theobroma-systems.com>
Tested-by: David Wu <david.wu@rock-chips.com>
Series-changes: 2
- Fixed David's email address.
Update the xlate() method to use ofnode_phandle_args instead of the fdtdec
variant. This will allow drivers to support a live device tree.
Signed-off-by: Simon Glass <sjg@chromium.org>
The following changes are made to the clock API:
* The concept of "clocks" and "peripheral clocks" are unified; each clock
provider now implements a single set of clocks. This provides a simpler
conceptual interface to clients, and better aligns with device tree
clock bindings.
* Clocks are now identified with a single "struct clk", rather than
requiring clients to store the clock provider device and clock identity
values separately. For simple clock consumers, this isolates clients
from internal details of the clock API.
* clk.h is split so it only contains the client/consumer API, whereas
clk-uclass.h contains the provider API. This aligns with the recently
added reset and mailbox APIs.
* clk_ops .of_xlate(), .request(), and .free() are added so providers
can customize these operations if needed. This also aligns with the
recently added reset and mailbox APIs.
* clk_disable() is added.
* All users of the current clock APIs are updated.
* Sandbox clock tests are updated to exercise clock lookup via DT, and
clock enable/disable.
* rkclk_get_clk() is removed and replaced with standard APIs.
Buildman shows no clock-related errors for any board for which buildman
can download a toolchain.
test/py passes for sandbox (which invokes the dm clk test amongst
others).
Signed-off-by: Stephen Warren <swarren@nvidia.com>
Acked-by: Simon Glass <sjg@chromium.org>
