leandrof/u-boot
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

clk: Add driver API to HTML docs

Browse Source 
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
This commit is contained in:
Sean Anderson 2021-12-22 12:11:13 -05:00
parent 9c88b13a90
commit a0abea867a
2 changed files with 115 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/api/clk.rst
View File

@ -11,3 +11,9 @@ Client API
.. kernel-doc:: include/clk.h
:internal:
Driver API
----------
.. kernel-doc:: include/clk-uclass.h
:internal:

101
include/clk-uclass.h
View File

@ -16,10 +16,36 @@ struct ofnode_phandle_args;
/**
* struct clk_ops - The functions that a clock driver must implement.
* @of_xlate: Translate a client's device-tree (OF) clock specifier.
* @request: Request a translated clock.
* @rfree: Free a previously requested clock.
* @round_rate: Adjust a rate to the exact rate a clock can provide.
* @get_rate: Get current clock rate.
* @set_rate: Set current clock rate.
* @set_parent: Set current clock parent
* @enable: Enable a clock.
* @disable: Disable a clock.
*
* The individual methods are described more fully below.
*/
struct clk_ops {
int (*of_xlate)(struct clk *clock,
struct ofnode_phandle_args *args);
int (*request)(struct clk *clock);
int (*rfree)(struct clk *clock);
ulong (*round_rate)(struct clk *clk, ulong rate);
ulong (*get_rate)(struct clk *clk);
ulong (*set_rate)(struct clk *clk, ulong rate);
int (*set_parent)(struct clk *clk, struct clk *parent);
int (*enable)(struct clk *clk);
int (*disable)(struct clk *clk);
};
#if 0 /* For documentation only */
/**
* of_xlate - Translate a client's device-tree (OF) clock specifier.
* of_xlate() - Translate a client's device-tree (OF) clock specifier.
* @clock: The clock struct to hold the translation result.
* @args: The clock specifier values from device tree.
*
* The clock core calls this function as the first step in implementing
* a client's clk_get_by_*() call.
@ -32,80 +58,85 @@ struct clk_ops {
* changes, other xxx_xlate() functions may be added to support those
* other mechanisms.
*
* @clock: The clock struct to hold the translation result.
* @args: The clock specifier values from device tree.
* @return 0 if OK, or a negative error code.
* Return: 0 if OK, or a negative error code.
*/
int (*of_xlate)(struct clk *clock,
struct ofnode_phandle_args *args);
int of_xlate(struct clk *clock, struct ofnode_phandle_args *args);
/**
* request - Request a translated clock.
* request() - Request a translated clock.
* @clock: The clock struct to request; this has been fille in by
* a previoux xxx_xlate() function call, or by the caller
* of clk_request().
*
* The clock core calls this function as the second step in
* implementing a client's clk_get_by_*() call, following a successful
* xxx_xlate() call, or as the only step in implementing a client's
* clk_request() call.
*
* @clock: The clock struct to request; this has been fille in by
* a previoux xxx_xlate() function call, or by the caller
* of clk_request().
* @return 0 if OK, or a negative error code.
* Return: 0 if OK, or a negative error code.
*/
int (*request)(struct clk *clock);
int request(struct clk *clock);
/**
* rfree - Free a previously requested clock.
* rfree() - Free a previously requested clock.
* @clock: The clock to free.
*
* This is the implementation of the client clk_free() API.
*
* @clock: The clock to free.
* @return 0 if OK, or a negative error code.
* Return: 0 if OK, or a negative error code.
*/
int (*rfree)(struct clk *clock);
int rfree(struct clk *clock);
/**
* round_rate() - Adjust a rate to the exact rate a clock can provide.
*
* @clk: The clock to manipulate.
* @rate: Desidered clock rate in Hz.
* @return rounded rate in Hz, or -ve error code.
*
* Return: rounded rate in Hz, or -ve error code.
*/
ulong (*round_rate)(struct clk *clk, ulong rate);
ulong round_rate(struct clk *clk, ulong rate);
/**
* get_rate() - Get current clock rate.
*
* @clk: The clock to query.
* @return clock rate in Hz, or -ve error code
*
* Return: clock rate in Hz, or -ve error code
*/
ulong (*get_rate)(struct clk *clk);
ulong get_rate(struct clk *clk);
/**
* set_rate() - Set current clock rate.
*
* @clk: The clock to manipulate.
* @rate: New clock rate in Hz.
* @return new rate, or -ve error code.
*
* Return: new rate, or -ve error code.
*/
ulong (*set_rate)(struct clk *clk, ulong rate);
ulong set_rate(struct clk *clk, ulong rate);
/**
* set_parent() - Set current clock parent
*
* @clk: The clock to manipulate.
* @parent: New clock parent.
* @return zero on success, or -ve error code.
*
* Return: zero on success, or -ve error code.
*/
int (*set_parent)(struct clk *clk, struct clk *parent);
int set_parent(struct clk *clk, struct clk *parent);
/**
* enable() - Enable a clock.
*
* @clk: The clock to manipulate.
* @return zero on success, or -ve error code.
*
* Return: zero on success, or -ve error code.
*/
int (*enable)(struct clk *clk);
int enable(struct clk *clk);
/**
* disable() - Disable a clock.
*
* @clk: The clock to manipulate.
* @return zero on success, or -ve error code.
*
* Return: zero on success, or -ve error code.
*/
int (*disable)(struct clk *clk);
};
int disable(struct clk *clk);
#endif
#endif