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 X-Spam-Level: X-Spam-Status: No, score=-16.7 required=3.0 tests=BAYES_00, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 5F571C4320A for ; Thu, 12 Aug 2021 17:00:52 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 3E9456109D for ; Thu, 12 Aug 2021 17:00:52 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S234048AbhHLRBQ (ORCPT ); Thu, 12 Aug 2021 13:01:16 -0400 Received: from mga05.intel.com ([192.55.52.43]:1108 "EHLO mga05.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233901AbhHLRBQ (ORCPT ); Thu, 12 Aug 2021 13:01:16 -0400 X-IronPort-AV: E=McAfee;i="6200,9189,10074"; a="300986774" X-IronPort-AV: E=Sophos;i="5.84,316,1620716400"; d="scan'208";a="300986774" Received: from fmsmga003.fm.intel.com ([10.253.24.29]) by fmsmga105.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 12 Aug 2021 10:00:38 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.84,316,1620716400"; d="scan'208";a="517527485" Received: from black.fi.intel.com ([10.237.72.28]) by FMSMGA003.fm.intel.com with ESMTP; 12 Aug 2021 10:00:29 -0700 Received: by black.fi.intel.com (Postfix, from userid 1003) id 30EA5238; Thu, 12 Aug 2021 20:00:29 +0300 (EEST) From: Andy Shevchenko To: "Rafael J. Wysocki" , Andy Shevchenko , Heiko Stuebner , Elaine Zhang , Stephen Boyd , linux-kernel@vger.kernel.org, linux-acpi@vger.kernel.org, linux-clk@vger.kernel.org, linux-imx@nxp.com, linux-arm-kernel@lists.infradead.org, linux-rockchip@lists.infradead.org Cc: "Rafael J. Wysocki" , Len Brown , Michael Turquette , Abel Vesa , Shawn Guo , Sascha Hauer , Pengutronix Kernel Team , Fabio Estevam , Lee Jones , Liu Ying Subject: [PATCH v4 4/4] clk: fractional-divider: Document the arithmetics used behind the code Date: Thu, 12 Aug 2021 20:00:25 +0300 Message-Id: <20210812170025.67074-4-andriy.shevchenko@linux.intel.com> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20210812170025.67074-1-andriy.shevchenko@linux.intel.com> References: <20210812170025.67074-1-andriy.shevchenko@linux.intel.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Precedence: bulk List-ID: X-Mailing-List: linux-acpi@vger.kernel.org It appears that some code lines raise the question why they are needed and how they are participated in the calculus of the resulting values. Document this in a form of the top comment in the module file. Reported-by: Liu Ying Signed-off-by: Andy Shevchenko --- v4: rebased on top of latest CLK codebase drivers/clk/clk-fractional-divider.c | 35 +++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/drivers/clk/clk-fractional-divider.c b/drivers/clk/clk-fractional-divider.c index 6a3ed82fdae9..b4f365d97bd0 100644 --- a/drivers/clk/clk-fractional-divider.c +++ b/drivers/clk/clk-fractional-divider.c @@ -3,8 +3,39 @@ * Copyright (C) 2014 Intel Corporation * * Adjustable fractional divider clock implementation. - * Output rate = (m / n) * parent_rate. * Uses rational best approximation algorithm. + * + * Output is calculated as + * + * rate = (m / n) * parent_rate (1) + * + * This is useful when on die we have a prescaler block which asks for + * m (numerator) and n (denominator) values to be provided to satisfy + * the (1) as much as possible. + * + * Since m and n have the limitation by a range, e.g. + * + * n >= 1, n < N_width, where N_width = 2^nwidth (2) + * + * for some cases the output may be saturated. Hence, from (1) and (2), + * assuming the worst case when m = 1, the inequality + * + * floor(log2(parent_rate / rate)) <= nwidth (3) + * + * may be derived. Thus, in cases when + * + * (parent_rate / rate) >> N_width (4) + * + * we might scale up the rate by 2^scale (see the description of + * CLK_FRAC_DIVIDER_POWER_OF_TWO_PS for additional information), where + * + * scale = floor(log2(parent_rate / rate)) - nwidth (5) + * + * and assume that the IP, that needs m and n, has also its own + * prescaler, which is capable to divide by 2^scale. In this way + * we get the denominator to satisfy the desired range (2) and + * at the same time much much better result of m and n than simple + * saturated values. */ #include @@ -81,6 +112,8 @@ void clk_fractional_divider_general_approximation(struct clk_hw *hw, * Get rate closer to *parent_rate to guarantee there is no overflow * for m and n. In the result it will be the nearest rate left shifted * by (scale - fd->nwidth) bits. + * + * For the detailed explanation see the top comment in this file. */ if (fd->flags & CLK_FRAC_DIVIDER_POWER_OF_TWO_PS) { unsigned long scale = fls_long(*parent_rate / rate - 1); -- 2.30.2 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 X-Spam-Level: X-Spam-Status: No, score=-17.4 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER, INCLUDES_PATCH,MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED, USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id C5E9FC4338F for ; Thu, 12 Aug 2021 17:01:18 +0000 (UTC) Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 5B9226023E for ; Thu, 12 Aug 2021 17:01:18 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org 5B9226023E Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=linux.intel.com Authentication-Results: mail.kernel.org; spf=none smtp.mailfrom=lists.infradead.org DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=bombadil.20210309; h=Sender: Content-Transfer-Encoding:Content-Type:List-Subscribe:List-Help:List-Post: List-Archive:List-Unsubscribe:List-Id:MIME-Version:References:In-Reply-To: Message-Id:Date:Subject:Cc:To:From:Reply-To:Content-ID:Content-Description: Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID: List-Owner; bh=iT0eYTyh6YrR9eJemOk/rFCYL8U6wjsgS+mO0W1ZiP4=; b=FCua0B8ItpajpO gHtbaCqe5a8vOtVqvl3pI3wnrDvI2nTHDZHdEt+37A4WMlnDVajnNhzRh+Uap3aU/+Vt/quUGqWq9 xIuc27eRHHoTj3gKvbI/EizqAKB9NW1B8+TXQcUijfEsbh2E4Ij0pvs+2L864RgflHtQVfQaZOMjU mBoiYNL8WeCUi27W1G7pHCnIJVCPnxq0w9d8q6m0iHXxKAYVZBLHY9IodnB/IUAoL6+UCLtWt/f7h +s9Oe7pGoU69gbN8xi8DRw2Dr6PG5tHBuqajdh0vcjJaUdgCQUHiVR1OMjgbgHPzbPMR68hcVzwsz OnsfDdcbN4J2FGTNaAoA==; Received: from localhost ([::1] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtp (Exim 4.94.2 #2 (Red Hat Linux)) id 1mEE4v-00AhHz-0p; Thu, 12 Aug 2021 17:01:13 +0000 Received: from mga06.intel.com ([134.134.136.31]) by bombadil.infradead.org with esmtps (Exim 4.94.2 #2 (Red Hat Linux)) id 1mEE4O-00AhAK-Oj; Thu, 12 Aug 2021 17:00:42 +0000 X-IronPort-AV: E=McAfee;i="6200,9189,10074"; a="276435240" X-IronPort-AV: E=Sophos;i="5.84,316,1620716400"; d="scan'208";a="276435240" Received: from fmsmga003.fm.intel.com ([10.253.24.29]) by orsmga104.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 12 Aug 2021 10:00:38 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.84,316,1620716400"; d="scan'208";a="517527485" Received: from black.fi.intel.com ([10.237.72.28]) by FMSMGA003.fm.intel.com with ESMTP; 12 Aug 2021 10:00:29 -0700 Received: by black.fi.intel.com (Postfix, from userid 1003) id 30EA5238; Thu, 12 Aug 2021 20:00:29 +0300 (EEST) From: Andy Shevchenko To: "Rafael J. Wysocki" , Andy Shevchenko , Heiko Stuebner , Elaine Zhang , Stephen Boyd , linux-kernel@vger.kernel.org, linux-acpi@vger.kernel.org, linux-clk@vger.kernel.org, linux-imx@nxp.com, linux-arm-kernel@lists.infradead.org, linux-rockchip@lists.infradead.org Cc: "Rafael J. Wysocki" , Len Brown , Michael Turquette , Abel Vesa , Shawn Guo , Sascha Hauer , Pengutronix Kernel Team , Fabio Estevam , Lee Jones , Liu Ying Subject: [PATCH v4 4/4] clk: fractional-divider: Document the arithmetics used behind the code Date: Thu, 12 Aug 2021 20:00:25 +0300 Message-Id: <20210812170025.67074-4-andriy.shevchenko@linux.intel.com> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20210812170025.67074-1-andriy.shevchenko@linux.intel.com> References: <20210812170025.67074-1-andriy.shevchenko@linux.intel.com> MIME-Version: 1.0 X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20210812_100040_919315_717CE72E X-CRM114-Status: GOOD ( 17.06 ) X-BeenThere: linux-rockchip@lists.infradead.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: Upstream kernel work for Rockchip platforms List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Sender: "Linux-rockchip" Errors-To: linux-rockchip-bounces+linux-rockchip=archiver.kernel.org@lists.infradead.org It appears that some code lines raise the question why they are needed and how they are participated in the calculus of the resulting values. Document this in a form of the top comment in the module file. Reported-by: Liu Ying Signed-off-by: Andy Shevchenko --- v4: rebased on top of latest CLK codebase drivers/clk/clk-fractional-divider.c | 35 +++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/drivers/clk/clk-fractional-divider.c b/drivers/clk/clk-fractional-divider.c index 6a3ed82fdae9..b4f365d97bd0 100644 --- a/drivers/clk/clk-fractional-divider.c +++ b/drivers/clk/clk-fractional-divider.c @@ -3,8 +3,39 @@ * Copyright (C) 2014 Intel Corporation * * Adjustable fractional divider clock implementation. - * Output rate = (m / n) * parent_rate. * Uses rational best approximation algorithm. + * + * Output is calculated as + * + * rate = (m / n) * parent_rate (1) + * + * This is useful when on die we have a prescaler block which asks for + * m (numerator) and n (denominator) values to be provided to satisfy + * the (1) as much as possible. + * + * Since m and n have the limitation by a range, e.g. + * + * n >= 1, n < N_width, where N_width = 2^nwidth (2) + * + * for some cases the output may be saturated. Hence, from (1) and (2), + * assuming the worst case when m = 1, the inequality + * + * floor(log2(parent_rate / rate)) <= nwidth (3) + * + * may be derived. Thus, in cases when + * + * (parent_rate / rate) >> N_width (4) + * + * we might scale up the rate by 2^scale (see the description of + * CLK_FRAC_DIVIDER_POWER_OF_TWO_PS for additional information), where + * + * scale = floor(log2(parent_rate / rate)) - nwidth (5) + * + * and assume that the IP, that needs m and n, has also its own + * prescaler, which is capable to divide by 2^scale. In this way + * we get the denominator to satisfy the desired range (2) and + * at the same time much much better result of m and n than simple + * saturated values. */ #include @@ -81,6 +112,8 @@ void clk_fractional_divider_general_approximation(struct clk_hw *hw, * Get rate closer to *parent_rate to guarantee there is no overflow * for m and n. In the result it will be the nearest rate left shifted * by (scale - fd->nwidth) bits. + * + * For the detailed explanation see the top comment in this file. */ if (fd->flags & CLK_FRAC_DIVIDER_POWER_OF_TWO_PS) { unsigned long scale = fls_long(*parent_rate / rate - 1); -- 2.30.2 _______________________________________________ Linux-rockchip mailing list Linux-rockchip@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-rockchip 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 X-Spam-Level: X-Spam-Status: No, score=-17.4 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER, INCLUDES_PATCH,MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED, USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 97180C4338F for ; Thu, 12 Aug 2021 17:03:51 +0000 (UTC) Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 1C67F60527 for ; Thu, 12 Aug 2021 17:03:50 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org 1C67F60527 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=linux.intel.com Authentication-Results: mail.kernel.org; spf=none smtp.mailfrom=lists.infradead.org DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=bombadil.20210309; h=Sender: Content-Transfer-Encoding:Content-Type:List-Subscribe:List-Help:List-Post: List-Archive:List-Unsubscribe:List-Id:MIME-Version:References:In-Reply-To: Message-Id:Date:Subject:Cc:To:From:Reply-To:Content-ID:Content-Description: Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID: List-Owner; bh=GJ5zBor1E93G6UudIL5CJyx2IFCLW4dgepT0Wyq3wrg=; b=QufIFSpFMyM6bj PxM3Bqrhkuz+BeWoSWBosAsQrtfqY9Kw1zr3cntMods08bFwfPNFONlEhLCQ4dIo1JqwpdOEgz9rI Y4bSWSPBdVruj6PMwMkDDT7Nl+noY1gNGKr6ME1lnsOlbc7E9OFDTTXJM1oyUUcXaKwj8cqSqfNIA OXdeMeIUo6kSOs2Cmt6iG1fDCaf6RZ1P2tnnTEd2BTf+8RQzEAvsPHYhkl5C13wYKMF1nDEa7khbE 3Gt5lB1g2qnKo++GjGrqJyeAlFVvNx2LSnioMiCLi1rLSD/HfTlpF0hBAbfH8RKTjNX+fpuJ2xRCC XW5v1e0uaqDCainZgAhg==; Received: from localhost ([::1] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtp (Exim 4.94.2 #2 (Red Hat Linux)) id 1mEE4l-00AhFb-S3; Thu, 12 Aug 2021 17:01:04 +0000 Received: from mga06.intel.com ([134.134.136.31]) by bombadil.infradead.org with esmtps (Exim 4.94.2 #2 (Red Hat Linux)) id 1mEE4O-00AhAK-Oj; Thu, 12 Aug 2021 17:00:42 +0000 X-IronPort-AV: E=McAfee;i="6200,9189,10074"; a="276435240" X-IronPort-AV: E=Sophos;i="5.84,316,1620716400"; d="scan'208";a="276435240" Received: from fmsmga003.fm.intel.com ([10.253.24.29]) by orsmga104.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 12 Aug 2021 10:00:38 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.84,316,1620716400"; d="scan'208";a="517527485" Received: from black.fi.intel.com ([10.237.72.28]) by FMSMGA003.fm.intel.com with ESMTP; 12 Aug 2021 10:00:29 -0700 Received: by black.fi.intel.com (Postfix, from userid 1003) id 30EA5238; Thu, 12 Aug 2021 20:00:29 +0300 (EEST) From: Andy Shevchenko To: "Rafael J. Wysocki" , Andy Shevchenko , Heiko Stuebner , Elaine Zhang , Stephen Boyd , linux-kernel@vger.kernel.org, linux-acpi@vger.kernel.org, linux-clk@vger.kernel.org, linux-imx@nxp.com, linux-arm-kernel@lists.infradead.org, linux-rockchip@lists.infradead.org Cc: "Rafael J. Wysocki" , Len Brown , Michael Turquette , Abel Vesa , Shawn Guo , Sascha Hauer , Pengutronix Kernel Team , Fabio Estevam , Lee Jones , Liu Ying Subject: [PATCH v4 4/4] clk: fractional-divider: Document the arithmetics used behind the code Date: Thu, 12 Aug 2021 20:00:25 +0300 Message-Id: <20210812170025.67074-4-andriy.shevchenko@linux.intel.com> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20210812170025.67074-1-andriy.shevchenko@linux.intel.com> References: <20210812170025.67074-1-andriy.shevchenko@linux.intel.com> MIME-Version: 1.0 X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20210812_100040_919315_717CE72E X-CRM114-Status: GOOD ( 17.06 ) X-BeenThere: linux-arm-kernel@lists.infradead.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Sender: "linux-arm-kernel" Errors-To: linux-arm-kernel-bounces+linux-arm-kernel=archiver.kernel.org@lists.infradead.org It appears that some code lines raise the question why they are needed and how they are participated in the calculus of the resulting values. Document this in a form of the top comment in the module file. Reported-by: Liu Ying Signed-off-by: Andy Shevchenko --- v4: rebased on top of latest CLK codebase drivers/clk/clk-fractional-divider.c | 35 +++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/drivers/clk/clk-fractional-divider.c b/drivers/clk/clk-fractional-divider.c index 6a3ed82fdae9..b4f365d97bd0 100644 --- a/drivers/clk/clk-fractional-divider.c +++ b/drivers/clk/clk-fractional-divider.c @@ -3,8 +3,39 @@ * Copyright (C) 2014 Intel Corporation * * Adjustable fractional divider clock implementation. - * Output rate = (m / n) * parent_rate. * Uses rational best approximation algorithm. + * + * Output is calculated as + * + * rate = (m / n) * parent_rate (1) + * + * This is useful when on die we have a prescaler block which asks for + * m (numerator) and n (denominator) values to be provided to satisfy + * the (1) as much as possible. + * + * Since m and n have the limitation by a range, e.g. + * + * n >= 1, n < N_width, where N_width = 2^nwidth (2) + * + * for some cases the output may be saturated. Hence, from (1) and (2), + * assuming the worst case when m = 1, the inequality + * + * floor(log2(parent_rate / rate)) <= nwidth (3) + * + * may be derived. Thus, in cases when + * + * (parent_rate / rate) >> N_width (4) + * + * we might scale up the rate by 2^scale (see the description of + * CLK_FRAC_DIVIDER_POWER_OF_TWO_PS for additional information), where + * + * scale = floor(log2(parent_rate / rate)) - nwidth (5) + * + * and assume that the IP, that needs m and n, has also its own + * prescaler, which is capable to divide by 2^scale. In this way + * we get the denominator to satisfy the desired range (2) and + * at the same time much much better result of m and n than simple + * saturated values. */ #include @@ -81,6 +112,8 @@ void clk_fractional_divider_general_approximation(struct clk_hw *hw, * Get rate closer to *parent_rate to guarantee there is no overflow * for m and n. In the result it will be the nearest rate left shifted * by (scale - fd->nwidth) bits. + * + * For the detailed explanation see the top comment in this file. */ if (fd->flags & CLK_FRAC_DIVIDER_POWER_OF_TWO_PS) { unsigned long scale = fls_long(*parent_rate / rate - 1); -- 2.30.2 _______________________________________________ linux-arm-kernel mailing list linux-arm-kernel@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-arm-kernel