From patchwork Wed Jan 10 03:47:42 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Viresh Kumar X-Patchwork-Id: 124001 Delivered-To: patch@linaro.org Received: by 10.140.22.227 with SMTP id 90csp4788713qgn; Tue, 9 Jan 2018 19:48:34 -0800 (PST) X-Google-Smtp-Source: ACJfBouqLwGLYKNo3F0/DRCsggwBVg6LwjkX68y3IF/gn+sEIcSn+Ht+iQm73C2nMbac2LWftA5O X-Received: by 10.98.17.7 with SMTP id z7mr15363641pfi.86.1515556113837; Tue, 09 Jan 2018 19:48:33 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1515556113; cv=none; d=google.com; s=arc-20160816; b=JA0JlpW2CBACiKfU5c+UvRqw5iDPmBnsCAST+OYxCmL6YE6k0+ezvQ/vtaVZtw4p4x fL145aQDuCe/ISSTSPCSsiEc6vrkEo3r/vwaG3iqMOF67kp7r8aks8lkHzplWUvZhH0z Ts4niDmAiQVLFkRcyUHjRsgVf/FJ2vGGrsJKDYS77Zpb3qzK/sAQj9hSM6uQSVOuNeR0 Q9GBFtHhVS5oxpjr8B2P6jyN3zdNuMYYjs70cGlb18fLwZOpNGRP2SWSZNdLSuhh5YBn i15n8O+Swj4lrgIsxDwzeNQxlWRwLnIjLzIjoz8YgpPxpNwjvlSaM6TDZCaZbSRFUZ5M Kc7A== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:references:in-reply-to:references :in-reply-to:message-id:date:subject:cc:to:from:dkim-signature :arc-authentication-results; bh=api11LEndXJusHFPvHzUNPAysLOMa4YH5yakyeuJ+c0=; b=vD7juDZKKBeGI1+ESd8UcEwQKNMlamtKPwr4mHvmNlK3xMNFB55n+12PnNLLyrKw24 yssU9IoZHCsQACKQDbHVRxG3grW1Hg88hngqCfUaYhEk6OWRSjprf5rUmRvQ+RFKu4Mu /GWmA0L8QnsuSOZUh+ytWOTJ0F6OsCRrOqZB+wgkaqK3rG4JCAVOMJ1bkdw1Hc+Idvyx b+bLCbVk1HXxAZQuTXBK4S3SqEJQQRU0MCnXbtY5KfPEA38zUUKs2S2tF5lbXvH2zCX2 ubsrrYv0Fc8Ien1wABNRTThlJxm3NteV5eA7LAqSXeraF/JB8ubP4heKq1gOkAvgbmGM Gj2g== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=b7y0m1J/; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id z10si2359910pgp.671.2018.01.09.19.48.33; Tue, 09 Jan 2018 19:48:33 -0800 (PST) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=b7y0m1J/; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S965262AbeAJDsc (ORCPT + 28 others); Tue, 9 Jan 2018 22:48:32 -0500 Received: from mail-pg0-f68.google.com ([74.125.83.68]:37921 "EHLO mail-pg0-f68.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S965232AbeAJDs1 (ORCPT ); Tue, 9 Jan 2018 22:48:27 -0500 Received: by mail-pg0-f68.google.com with SMTP id t67so9804880pgc.5 for ; Tue, 09 Jan 2018 19:48:27 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :in-reply-to:references; bh=api11LEndXJusHFPvHzUNPAysLOMa4YH5yakyeuJ+c0=; b=b7y0m1J/q5cAi7NO5rLe5gxp+0vJ/MXpOB44wDaIZcloDThKK4NtV4OLlXJEd2rGbQ OR49fV90RAESKxnXUaYtiCjVFYH9XOMRJy5NwijOUHJ+3exboPIizJJVc7b6idGJMB2v ozXIUtwbzyOcJb1V9GjA/5Luy9tBhQnszm+xI= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:in-reply-to:references; bh=api11LEndXJusHFPvHzUNPAysLOMa4YH5yakyeuJ+c0=; b=XjHFX89io9bLzNTos4swaYdq6kNv67H367wOZRaHjGjhZ/eBeQNv5cBwpvuX+U+hmn 7h1sdz8OGaVkWxQnm1BEInq4QCGriGDQIL5k/3WR1mvWTmu6qniH4kHfM5yA/q+YV2a1 S62JkqgKhSrt1wG2hJaA4rZYPe28+dwGQO2iRNlsxGblbPLzIDvb8LSDiNpU6gJGivKR 2FCIbZeSyVz8wbvje5oeWCR10NHAw2AVHdViMolJV1MoP/yIxEw0cJxdQXNLA/k4j0jT OPejCO0icVH/PJetkYputBtQpbHXU7vfrxe0JLTQ5Wchjd2et44Em7j8VWKjaeh8Ql9s FjEw== X-Gm-Message-State: AKGB3mKCTM/VKBuBo9Ow5VjC4Rl9Lk4DhwWOz2ybOy4T9Dxwvvd0xiKL JyQ5FU/oqHV3PD2vZ1GMpYzPAg== X-Received: by 10.98.163.131 with SMTP id q3mr6328624pfl.87.1515556106877; Tue, 09 Jan 2018 19:48:26 -0800 (PST) Received: from localhost ([122.172.19.39]) by smtp.gmail.com with ESMTPSA id k63sm33139898pfk.172.2018.01.09.19.48.26 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Tue, 09 Jan 2018 19:48:26 -0800 (PST) From: Viresh Kumar To: Greg Kroah-Hartman Cc: Viresh Kumar , Vincent Guittot , Stephen Boyd , Rajendra Nayak , linux-kernel@vger.kernel.org, linux-arm-kernel@lists.infradead.org, robdclark@gmail.com, s.hauer@pengutronix.de, l.stach@pengutronix.de, shawnguo@kernel.org, fabio.estevam@nxp.com, nm@ti.com, xuwei5@hisilicon.com, robh+dt@kernel.org Subject: [PATCH V6 13/13] boot_constraint: Add documentation Date: Wed, 10 Jan 2018 09:17:42 +0530 Message-Id: <000b848c02d4ef5d7d7bc06d3c30c9d27862ba60.1515554879.git.viresh.kumar@linaro.org> X-Mailer: git-send-email 2.15.0.194.g9af6a3dea062 In-Reply-To: References: In-Reply-To: References: Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org This adds boot constraint documentation. Signed-off-by: Viresh Kumar --- .../driver-api/boot-constraint/constraints.rst | 98 ++++++++++++++++++++++ Documentation/driver-api/boot-constraint/index.rst | 4 + Documentation/driver-api/index.rst | 1 + 3 files changed, 103 insertions(+) create mode 100644 Documentation/driver-api/boot-constraint/constraints.rst create mode 100644 Documentation/driver-api/boot-constraint/index.rst -- 2.15.0.194.g9af6a3dea062 diff --git a/Documentation/driver-api/boot-constraint/constraints.rst b/Documentation/driver-api/boot-constraint/constraints.rst new file mode 100644 index 000000000000..036bb77a26f9 --- /dev/null +++ b/Documentation/driver-api/boot-constraint/constraints.rst @@ -0,0 +1,98 @@ +.. include:: + +========================= +Boot Constraint Subsystem +========================= + +:Copyright: |copy| 2017 Viresh Kumar , Linaro Ltd. + +Introduction +============ + +A lot of devices are configured and powered ON by the bootloader before passing +on control to the operating system, Linux in our case. It is important for some +of them to keep working until the time a Linux device driver probes the device +and reconfigure it. + +A typical example of that can be the LCD controller, which is used by the +bootloaders to show image(s) while the platform boots Linux. The LCD controller +can be using resources like clk, regulators, etc, that are shared with other +devices. These shared resources should be configured in such a way that they +satisfy need of all the user devices. If another device's (X) driver gets +probed before the LCD controller driver, then it may end up disabling or +reconfiguring these resources to ranges satisfying only the current user (device +X) and that may make the LCD screen unstable and present a bad user experience. + +Another case can be a debug serial port (earlycon) enabled from the bootloader, +which may be used to debug early kernel oops. + +There are also cases where the resources may not be shared, but the kernel will +disable them forcefully as no users may have appeared until a certain point in +the kernel boot. + +Of course we can have more complex cases where the same resource is getting used +by multiple devices while the kernel boots and the order in which the devices +get probed wouldn't matter as the other devices may break because of the chosen +configuration of the first probed device. + +Adding boot constraints +======================= + +A boot constraint defines a configuration requirement set for the device by the +boot loader. For example, if a clock is enabled for a device by the bootloader +and we want the device to be working as is until the time the device is probed +by its driver, then keeping this clock enabled is one of the boot constraint. + +Following are the different type of boot constraints supported currently by the +core: + +.. kernel-doc:: include/linux/boot_constraint.h + :functions: dev_boot_constraint_type + + +A single boot constraint can be added using the following helper: + +.. kernel-doc:: drivers/boot_constraint/core.c + :functions: dev_boot_constraint_add + + +The second parameter to this routine describes the constraint to add and is +represented by following structures: + +.. kernel-doc:: include/linux/boot_constraint.h + :functions: dev_boot_constraint dev_boot_constraint_info + +The power domain boot constraint doesn't need any data, while the clock and +power supply boot constraint specific data is represented by following +structures: + +.. kernel-doc:: include/linux/boot_constraint.h + :functions: dev_boot_constraint_supply_info dev_boot_constraint_clk_info + + +In order to simplify adding multiple boot constraints for a platform, the boot +constraints core supplies another helper which can be used to add all +constraints for the platform. + +.. kernel-doc:: drivers/boot_constraint/deferrable_dev.c + :functions: dev_boot_constraint_add_deferrable_of + + +The argument of this routine is described by following structure: + +.. kernel-doc:: include/linux/boot_constraint.h + :functions: dev_boot_constraint_of + + +Removing boot constraints +========================= + +Once the boot constraints are added, they will be honored by the boot constraint +core until the time a driver tries to probe the device. The constraints are +removed by the driver core if either the driver successfully probed the device +or failed with an error value other than -EPROBE_DEFER. The constraints are kept +as is for deferred probe. The driver core removes the constraints using the +following helper, which must not be called directly by the platforms: + +.. kernel-doc:: drivers/boot_constraint/core.c + :functions: dev_boot_constraints_remove diff --git a/Documentation/driver-api/boot-constraint/index.rst b/Documentation/driver-api/boot-constraint/index.rst new file mode 100644 index 000000000000..d6fce17626a2 --- /dev/null +++ b/Documentation/driver-api/boot-constraint/index.rst @@ -0,0 +1,4 @@ +.. toctree:: + :maxdepth: 1 + + constraints diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index d17a9876b473..e591c172b5b5 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -47,6 +47,7 @@ available subsections can be seen below. gpio misc_devices dmaengine/index + boot-constraint/index .. only:: subproject and html