u-boot.git/include/clk-uclass.h, branch master

clk: Document clk_ops return codes and behavior

2024-01-30T03:35:02+00:00

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 
Link: https://lore.kernel.org/r/20231216193843.2463779-4-seanga2@gmail.com

clk: Remove rfree

2024-01-30T03:35:02+00:00

Nothing uses this function. Remove it. Since clk_free no longer does
anything, just stub it out.

Signed-off-by: Sean Anderson 
Link: https://lore.kernel.org/r/20231216193843.2463779-2-seanga2@gmail.com

clk: Add dump operation to clk_ops

2023-12-15T18:05:54+00:00

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 
Tested-by: Patrice Chotard 
Reviewed-by: Sean Anderson 
Signed-off-by: Igor Prusov 
[ Fixed parameter name in documentation ]
Signed-off-by: Sean Anderson 
Link: https://lore.kernel.org/r/20231109105516.24892-6-ivprusov@sberdevices.ru

clk: Fix typo in header comment

2023-08-19T02:12:53+00:00

Signed-off-by: Paul Barker 
Reviewed-by: Heinrich Schuchardt

clk: Make rfree return void

2022-03-30T17:02:55+00:00

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 
Reviewed-by: Simon Glass 
Link: https://lore.kernel.org/r/20220115222504.617013-2-seanga2@gmail.com

clk: Add driver API to HTML docs

2022-02-25T06:41:04+00:00

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 
Tested-by: Heinrich Schuchardt 
Reviewed-by: Simon Glass 
Link: https://lore.kernel.org/r/20211222171114.3091780-5-seanga2@gmail.com

clk: add clk_round_rate()

2021-01-12T05:28:04+00:00

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 
Reviewed-by: Simon Glass 
Reviewed-by: Sean Anderson

clk: Rename free() to rfree()

2020-02-06T02:33:46+00:00

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

SPDX: Convert all of our single license tags to Linux Kernel style

2018-05-07T13:34:12+00:00

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

clk: add clk_set_parent()

2018-01-28T16:12:35+00:00

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 
Tested-by: David Wu 

Series-changes: 2
- Fixed David's email address.