From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from phobos.denx.de (phobos.denx.de [85.214.62.61]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 53079C433F5 for ; Wed, 1 Dec 2021 18:44:28 +0000 (UTC) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 4052183092; Wed, 1 Dec 2021 19:44:06 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Authentication-Results: phobos.denx.de; dkim=pass (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.b="b4o57kuG"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id EE7D0830BA; Wed, 1 Dec 2021 19:43:56 +0100 (CET) Received: from mail-qv1-xf2a.google.com (mail-qv1-xf2a.google.com [IPv6:2607:f8b0:4864:20::f2a]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id AAF0F81294 for ; Wed, 1 Dec 2021 19:43:47 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=seanga2@gmail.com Received: by mail-qv1-xf2a.google.com with SMTP id m17so22612152qvx.8 for ; Wed, 01 Dec 2021 10:43:47 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=lsDCWlzHhFyPvvdrapBTweoQ9X+fxk8PpiRAIv8ul+E=; b=b4o57kuGZJx+ZRX7WkyMGu9CUYM+j2nZtnm56fJQixajgeuIRnCCf1H9dHejdFJrBL 9zKFhIxPSoxNZWi+fhhIdw9AAePfRkCSg5nqGAt1OnA9Q7rvxpTYSpbHvOSAEoSsJmHq HcoHRBX5oR/Gu+PGxDZrEc25GoqU4lLEbyMvfZMm9W8qxXkM8FtjFm7M5Z3jmdy14ZCH 4lcBcHd3wIUqJ6hbE30W611fsznFx42DJxeHU6URKhkiBF2dgzQQroHDC3lNxdappPeB /riq3OLfrEC02IHJj0tLlBlpN2Yubhi1BxKmmbFNV5BGwxNai69q5BuZv5etw6GVB24L 8vUw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=lsDCWlzHhFyPvvdrapBTweoQ9X+fxk8PpiRAIv8ul+E=; b=JGsVbn2xyop2MZs3cXTEOcI16DMWKw/PDegytL+WTgc45ip0lGmrpsrrdncA6rWxVj +zzqsGWgfKrAaFDnNEIZ0G+0SxM7HsFxsOE1/GyIu5LCMRU041OF5Im0oJdkEfXAOiuZ BRCm7cgBpnfA86C/GM2Y7TkfecLOqCbhRA/XmrSR89IwiW/FV6CWgBZSNdEQ1Mb/P4/o 2SmRdvR4/nDACQDAovt7C9vBVZPZ5jLps0d4ExVGOmdYfI6pSqirQMnKWUc23EOzYSXi F9wcX1bakHhuQlTz5B7hlbUmN9GJySDwWcYQFPU9aW+T9KEg5YknSbfGSlxRR43YjVsZ 44UQ== X-Gm-Message-State: AOAM530ln7yvyFf3/dG/VgDM6wkO8PaxVY5GASZyOLXql2ih7oLcftaE MJ5bmPE/gQ5a8eh/d8aU7FwD99xOIE0= X-Google-Smtp-Source: ABdhPJx90X2rwLxHYm4F3OU6U/nEd3k5k808tOLkj3zA3Wpr1+Ru3ZBH/gFU/7JWy7xcCr2Yj0zbpA== X-Received: by 2002:ad4:5aa4:: with SMTP id u4mr8507853qvg.7.1638384225929; Wed, 01 Dec 2021 10:43:45 -0800 (PST) Received: from godwin.fios-router.home (pool-108-18-207-184.washdc.fios.verizon.net. [108.18.207.184]) by smtp.gmail.com with ESMTPSA id u10sm310138qkp.104.2021.12.01.10.43.45 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 01 Dec 2021 10:43:45 -0800 (PST) From: Sean Anderson To: u-boot@lists.denx.de Cc: Dario Binacchi , Simon Glass , Lukasz Majewski , Sean Anderson , Heinrich Schuchardt Subject: [PATCH 4/5] clk: Add driver API to HTML docs Date: Wed, 1 Dec 2021 13:43:31 -0500 Message-Id: <20211201184332.2166897-5-seanga2@gmail.com> X-Mailer: git-send-email 2.33.0 In-Reply-To: <20211201184332.2166897-1-seanga2@gmail.com> References: <20211201184332.2166897-1-seanga2@gmail.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.37 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: u-boot-bounces@lists.denx.de Sender: "U-Boot" X-Virus-Scanned: clamav-milter 0.103.2 at phobos.denx.de X-Virus-Status: Clean 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 --- doc/api/clk.rst | 6 ++ include/clk-uclass.h | 187 +++++++++++++++++++++++++------------------ 2 files changed, 115 insertions(+), 78 deletions(-) diff --git a/doc/api/clk.rst b/doc/api/clk.rst index 7eb3b5645a..7c27066928 100644 --- a/doc/api/clk.rst +++ b/doc/api/clk.rst @@ -11,3 +11,9 @@ Client API .. kernel-doc:: include/clk.h :internal: + +Driver API +---------- + +.. kernel-doc:: include/clk-uclass.h + :internal: diff --git a/include/clk-uclass.h b/include/clk-uclass.h index 50e8681b55..c18ecfdf5f 100644 --- a/include/clk-uclass.h +++ b/include/clk-uclass.h @@ -16,96 +16,127 @@ 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 { - /** - * of_xlate - Translate a client's device-tree (OF) clock specifier. - * - * The clock core calls this function as the first step in implementing - * a client's clk_get_by_*() call. - * - * If this function pointer is set to NULL, the clock core will use a - * default implementation, which assumes #clock-cells = <1>, and that - * the DT cell contains a simple integer clock ID. - * - * At present, the clock API solely supports device-tree. If this - * 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. - */ int (*of_xlate)(struct clk *clock, struct ofnode_phandle_args *args); - /** - * request - Request a translated clock. - * - * 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. - */ int (*request)(struct clk *clock); - /** - * rfree - Free a previously requested clock. - * - * This is the implementation of the client clk_free() API. - * - * @clock: The clock to free. - * @return 0 if OK, or a negative error code. - */ 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. - */ 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 - */ 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. - */ 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. - */ 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. - */ int (*enable)(struct clk *clk); - /** - * disable() - Disable a clock. - * - * @clk: The clock to manipulate. - * @return zero on success, or -ve error code. - */ int (*disable)(struct clk *clk); }; +#if 0 /* For documentation only */ +/** + * 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. + * + * If this function pointer is set to NULL, the clock core will use a + * default implementation, which assumes #clock-cells = <1>, and that + * the DT cell contains a simple integer clock ID. + * + * At present, the clock API solely supports device-tree. If this + * changes, other xxx_xlate() functions may be added to support those + * other mechanisms. + * + * Return: 0 if OK, or a negative error code. + */ +int of_xlate(struct clk *clock, struct ofnode_phandle_args *args); + +/** + * request() - Request a translated clock. + * + * 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. + */ +int request(struct clk *clock); + +/** + * rfree() - Free a previously requested clock. + * + * This is the implementation of the client clk_free() API. + * + * @clock: The clock to free. + * Return: 0 if OK, or a negative error code. + */ +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. + */ +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 + */ +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. + */ +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. + */ +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. + */ +int enable(struct clk *clk); + +/** + * disable() - Disable a clock. + * + * @clk: The clock to manipulate. + * Return: zero on success, or -ve error code. + */ +int disable(struct clk *clk); +#endif + #endif -- 2.33.0