From patchwork Tue Mar 24 09:54:02 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Daniel Lezcano X-Patchwork-Id: 6077751 Return-Path: X-Original-To: patchwork-linux-pm@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork1.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork1.web.kernel.org (Postfix) with ESMTP id 2AEC19F350 for ; Tue, 24 Mar 2015 09:54:29 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 2DF9E201FA for ; Tue, 24 Mar 2015 09:54:28 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 36B10201CE for ; Tue, 24 Mar 2015 09:54:27 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752379AbbCXJyZ (ORCPT ); Tue, 24 Mar 2015 05:54:25 -0400 Received: from mail-we0-f169.google.com ([74.125.82.169]:33201 "EHLO mail-we0-f169.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752189AbbCXJyI (ORCPT ); Tue, 24 Mar 2015 05:54:08 -0400 Received: by weop45 with SMTP id p45so158852217weo.0 for ; Tue, 24 Mar 2015 02:54:07 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=lXTS9gByiTDO/DGSzzj7RVD3IblF+HHYMsjB5bdj/Bk=; b=BAbugPUtU7UTI7wp+6JE6pQCVJeQq6RHTUPNeNthtVIF37uOLiuJbfLtLw1l/3VF8J 9ao4ic/s+seJGuItLwMP7ay3ZS8oNaxs4UpTHZFtbAnMv6AvnMyMWEIMwFmr5BRBGwNY h+Xn3Q4O/o7HygSRvTw1mrWVjAk3bTcfL85UJkWY8TqRtAQyEmY8EIBmnFgo25tOPOBU pJOjuyI4oyBh5k7BuP9AJyVe/V86yZlo2kDuZ0Xp7vOrf7cZOJNvgB5tCI70k+ohyR0F yAEYf5ofyCV6rLm7BmXPZXgOAGYpkvZl8fBi/gxsmwf/FW9bPYT61ejRNQCHKLrO+pXS tyxQ== X-Gm-Message-State: ALoCoQlphUPVwrAFi2XJb0knmqFo/hpzsuzNepGofyS2vFSyqjRGHcPG8SlcH1WCJiNKsV+eFfTr X-Received: by 10.180.82.169 with SMTP id j9mr16961504wiy.40.1427190847649; Tue, 24 Mar 2015 02:54:07 -0700 (PDT) Received: from mai.lan (135-224-190-109.dsl.ovh.fr. [109.190.224.135]) by mx.google.com with ESMTPSA id ey10sm10328649wib.2.2015.03.24.02.54.05 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Tue, 24 Mar 2015 02:54:07 -0700 (PDT) From: Daniel Lezcano To: lorenzo.pieralisi@arm.com Cc: rjw@rjwysocki.net, linux-pm@vger.kernel.org, linux-kernel@vger.kernel.org, Catalin.Marinas@arm.com, robherring2@gmail.com, arnd@arndb.de, devicetree@vger.kernel.org, linux-arm-kernel@lists.infradead.org, lina.iyer@linaro.org, sboyd@codeaurora.org Subject: [PATCH 2/2] ARM: cpuidle: Document the code Date: Tue, 24 Mar 2015 10:54:02 +0100 Message-Id: <1427190842-30675-2-git-send-email-daniel.lezcano@linaro.org> X-Mailer: git-send-email 1.9.1 In-Reply-To: <1427190842-30675-1-git-send-email-daniel.lezcano@linaro.org> References: <20150323225828.GC15435@e102568-lin.cambridge.arm.com> <1427190842-30675-1-git-send-email-daniel.lezcano@linaro.org> Sender: linux-pm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-pm@vger.kernel.org X-Spam-Status: No, score=-6.9 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_HI, T_RP_MATCHES_RCVD, UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Add kernel-doc format documentation in the code. Signed-off-by: Daniel Lezcano Acked-by: Lorenzo Pieralisi --- arch/arm/kernel/cpuidle.c | 58 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/arch/arm/kernel/cpuidle.c b/arch/arm/kernel/cpuidle.c index 2b0dae3..9219613 100644 --- a/arch/arm/kernel/cpuidle.c +++ b/arch/arm/kernel/cpuidle.c @@ -21,6 +21,17 @@ static const struct of_cpuidle_method __cpuidle_method_of_table_sentinel static struct cpuidle_ops cpuidle_ops[NR_CPUS]; +/* + * arm_cpuidle_simple_enter() - a wrapper to cpu_do_idle() + * @dev: not used + * @drv: not used + * @index: not used + * + * A trivial wrapper to allow the cpu_do_idle function to be assigned as a + * cpuidle callback by matching the function signature. + * + * Returns the index passed as parameter + */ int arm_cpuidle_simple_enter(struct cpuidle_device *dev, struct cpuidle_driver *drv, int index) { @@ -29,6 +40,16 @@ int arm_cpuidle_simple_enter(struct cpuidle_device *dev, return index; } +/* + * arm_cpuidle_suspend() - function to enter low power idle states + * @index: an integer used as an identifier for the low level PM callbacks + * + * This function calls the underlying arch specific low level PM code as + * registered at the init time. + * + * Returns -EOPNOTSUPP if no suspend callback is defined, the result of the + * callback otherwise. + */ int arm_cpuidle_suspend(int index) { int ret = -EOPNOTSUPP; @@ -40,6 +61,15 @@ int arm_cpuidle_suspend(int index) return ret; } +/* + * arm_cpuidle_get_ops() - find a registered cpuidle_ops by name + * @method: the method name + * + * Search in the __cpuidle_method_of_table array the cpuidle ops matching the + * method name. + * + * Returns a struct cpuidle_ops pointer, NULL if not found. + */ static struct cpuidle_ops *__init arm_cpuidle_get_ops(const char *method) { struct of_cpuidle_method *m = __cpuidle_method_of_table; @@ -51,6 +81,19 @@ static struct cpuidle_ops *__init arm_cpuidle_get_ops(const char *method) return NULL; } +/* + * arm_cpuidle_read_ops() - Initialize the cpuidle ops with the device tree + * @dn: a struct device node corresponding to a cpu node + * @cpu: the cpu identifier + * + * Get the method name defined in the 'enabled-method' property, retrieve the + * associated cpuidle_ops and do a struct copy. This copy is needed because all + * cpuidle_ops are tagged __initdata and will be unloaded after the init + * process. + * + * Return 0 on sucess, -ENOENT if no enabled-method is defined, -EOPNOTSUPP if + * no cpuidle_ops is registered for the enabled-method. + */ static int __init arm_cpuidle_read_ops(struct device_node *dn, int cpu) { const char *enable_method; @@ -75,6 +118,21 @@ static int __init arm_cpuidle_read_ops(struct device_node *dn, int cpu) return 0; } +/* + * arm_cpuidle_init() - Initialize cpuidle_ops for a specific cpu + * @cpu: the cpu to be initialized + * + * Initialize the cpuidle ops with the device for the cpu and then call + * the cpu's idle initialization callback. This may fail if the underlying HW + * is not operational. + * + * Returns: + * 0 on success, + * -ENODEV if it fails to find the cpu node in the device tree, + * -EOPNOTSUPP if it does not find a registered cpuidle_ops for this cpu, + * -ENOENT if it fails to find a enabled-method property, + * -ENXIO if the HW reports a failure or a misconfiguration + */ int __init arm_cpuidle_init(int cpu) { struct device_node *cpu_node = of_cpu_device_node_get(cpu);