From patchwork Wed Mar 25 09:07:16 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Daniel Lezcano X-Patchwork-Id: 46313 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-la0-f70.google.com (mail-la0-f70.google.com [209.85.215.70]) by ip-10-151-82-157.ec2.internal (Postfix) with ESMTPS id D39782159D for ; Wed, 25 Mar 2015 09:08:28 +0000 (UTC) Received: by lamq1 with SMTP id q1sf3341854lam.3 for ; Wed, 25 Mar 2015 02:08:27 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:mime-version:delivered-to:from:to:cc:subject :date:message-id:in-reply-to:references:sender:precedence:list-id :x-original-sender:x-original-authentication-results:mailing-list :list-post:list-help:list-archive:list-unsubscribe; bh=ynHrLpENlami6fmK7s00QI6Ut+f0tmaUP2byRxLeUsE=; b=LgyDNdpPkuGgk9rSMJ+BZz6yTHDO4hqBXB2NquEjBLzOp2HxN1ZiZ4bR6JFm24WXG/ jAxoDT9jalCjA40MW+W0w+9d6Sy/mAn4n/aP0ZPSTzL45+uqtUaQbu8yh/bd6y4GsTs/ ezIbGywVHV5utM9agc2atu9dTzEMMv1uVndm4gKNC8qhElzm7xe+fdACnPBTLjAuFux1 AbFgJRt8P07aPsVk1J9o6fZMh8jGyFteiCzjA2R+9o390X8pwzUSiRLl6octBMDSIwAQ +w2FGR85Sn1VMWqN2JcIFKHn44LeB8ZizhvCDtrYokD6qnOn/tMMMo6fRDUZzL+L70ss rnKA== X-Gm-Message-State: ALoCoQnyHCI2wGkyq0Aj8WW3n8wOJNgMgkqYaxAGBdTAthH7Gmg02NZ9A0yvX8AmsmhsWqWkphBu X-Received: by 10.180.91.76 with SMTP id cc12mr4029401wib.7.1427274507802; Wed, 25 Mar 2015 02:08:27 -0700 (PDT) MIME-Version: 1.0 X-BeenThere: patchwork-forward@linaro.org Received: by 10.152.19.36 with SMTP id b4ls68663lae.46.gmail; Wed, 25 Mar 2015 02:08:27 -0700 (PDT) X-Received: by 10.152.37.164 with SMTP id z4mr7481973laj.5.1427274507542; Wed, 25 Mar 2015 02:08:27 -0700 (PDT) Received: from mail-la0-f44.google.com (mail-la0-f44.google.com. [209.85.215.44]) by mx.google.com with ESMTPS id s17si1498391lal.30.2015.03.25.02.08.27 for (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Wed, 25 Mar 2015 02:08:27 -0700 (PDT) Received-SPF: pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.215.44 as permitted sender) client-ip=209.85.215.44; Received: by labto5 with SMTP id to5so14539043lab.0 for ; Wed, 25 Mar 2015 02:08:27 -0700 (PDT) X-Received: by 10.112.141.202 with SMTP id rq10mr7599799lbb.88.1427274507433; Wed, 25 Mar 2015 02:08:27 -0700 (PDT) X-Forwarded-To: patchwork-forward@linaro.org X-Forwarded-For: patch@linaro.org patchwork-forward@linaro.org Delivered-To: patch@linaro.org Received: by 10.112.57.201 with SMTP id k9csp1959751lbq; Wed, 25 Mar 2015 02:08:26 -0700 (PDT) X-Received: by 10.70.53.170 with SMTP id c10mr15492709pdp.148.1427274499498; Wed, 25 Mar 2015 02:08:19 -0700 (PDT) Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id z12si2710047pas.241.2015.03.25.02.08.18; Wed, 25 Mar 2015 02:08:19 -0700 (PDT) Received-SPF: none (google.com: linux-kernel-owner@vger.kernel.org does not designate permitted sender hosts) client-ip=209.132.180.67; Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752677AbbCYJIQ (ORCPT + 27 others); Wed, 25 Mar 2015 05:08:16 -0400 Received: from mail-wi0-f171.google.com ([209.85.212.171]:37763 "EHLO mail-wi0-f171.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752507AbbCYJHf (ORCPT ); Wed, 25 Mar 2015 05:07:35 -0400 Received: by wixw10 with SMTP id w10so28763542wix.0 for ; Wed, 25 Mar 2015 02:07:34 -0700 (PDT) X-Received: by 10.180.160.226 with SMTP id xn2mr25957935wib.43.1427274454157; Wed, 25 Mar 2015 02:07:34 -0700 (PDT) Received: from mai.lan (135-224-190-109.dsl.ovh.fr. [109.190.224.135]) by mx.google.com with ESMTPSA id ge8sm2662696wjc.32.2015.03.25.02.07.32 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Wed, 25 Mar 2015 02:07:33 -0700 (PDT) From: Daniel Lezcano To: rjw@rjwysocki.net Cc: linux-kernel@vger.kernel.org, linux-arm-kernel@lists.infradead.org, linux-pm@vger.kernel.org, lina.iyer@linaro.org, Lorenzo.Pieralisi@arm.com Subject: [PATCH 8/8] ARM: cpuidle: Document the code Date: Wed, 25 Mar 2015 10:07:16 +0100 Message-Id: <1427274436-21916-8-git-send-email-daniel.lezcano@linaro.org> X-Mailer: git-send-email 1.9.1 In-Reply-To: <1427274436-21916-1-git-send-email-daniel.lezcano@linaro.org> References: <55127A53.8050206@linaro.org> <1427274436-21916-1-git-send-email-daniel.lezcano@linaro.org> Sender: linux-kernel-owner@vger.kernel.org Precedence: list List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-Removed-Original-Auth: Dkim didn't pass. X-Original-Sender: daniel.lezcano@linaro.org X-Original-Authentication-Results: mx.google.com; spf=pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.215.44 as permitted sender) smtp.mail=patch+caf_=patchwork-forward=linaro.org@linaro.org Mailing-list: list patchwork-forward@linaro.org; contact patchwork-forward+owners@linaro.org X-Google-Group-Id: 836684582541 List-Post: , List-Help: , List-Archive: List-Unsubscribe: , Add kernel-doc format documentation in the code. Signed-off-by: Daniel Lezcano --- arch/arm/kernel/cpuidle.c | 59 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/arch/arm/kernel/cpuidle.c b/arch/arm/kernel/cpuidle.c index 2b0dae3..318da33 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 pointer to a struct device node corresponding to a cpu node + * @cpu: the cpu identifier + * + * Get the method name defined in the 'enable-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 'enable-method' is defined, -EOPNOTSUPP if + * no cpuidle_ops is registered for the 'enable-method'. + */ static int __init arm_cpuidle_read_ops(struct device_node *dn, int cpu) { const char *enable_method; @@ -75,6 +118,22 @@ 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 an 'enable-method' property, + * -ENXIO if the HW reports a failure or a misconfiguration, + * -ENOMEM if the HW report an memory allocation failure + */ int __init arm_cpuidle_init(int cpu) { struct device_node *cpu_node = of_cpu_device_node_get(cpu);