From patchwork Fri Feb 23 10:23:52 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Viresh Kumar X-Patchwork-Id: 10237409 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id E00B960209 for ; Fri, 23 Feb 2018 10:55:19 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id D28E129519 for ; Fri, 23 Feb 2018 10:55:19 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id C508F2951B; Fri, 23 Feb 2018 10:55:19 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-1.9 required=2.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID autolearn=unavailable version=3.3.1 Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (using TLSv1.2 with cipher AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id 2EA8429519 for ; Fri, 23 Feb 2018 10:55:19 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=bombadil.20170209; h=Sender: Content-Transfer-Encoding:Content-Type:MIME-Version:Cc:List-Subscribe: List-Help:List-Post:List-Archive:List-Unsubscribe:List-Id:References: In-Reply-To:Message-Id:Date:Subject:To:From:Reply-To:Content-ID: Content-Description:Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc :Resent-Message-ID:List-Owner; bh=gpC2x4AEEOyC/ayghuW2GUFDi8RDmD3oG2ZbZ77NdOA=; b=Fl5PRuHp7zImAmClSmde0Z3yAo X6CSjgDI8DLhOd14eculBpFci9dEib6uvSVBsEhOhzjYK4czkcdnGIrvCh1aE40fD9fv0mOyrnVf2 ueEzSJGPp0vj+XG3aVjU1q/an8/4O7oUhg6MQ0S66XVkbymPsYnxkxCvxlhQc6TzwtLZkFKkl38Vz 1cksICTPegQwvV1qA/XRt2Jro/m0TWkaq4wZTOcyuWMro10NGnOESs1WhKo+oZ/nxsC2u2fkN3pSN HvuHjrCsinD7crEAb7Ty49jYIq1riaIMqFvgyhZAGWxKq7ezH7dI9LgvC3nxJrsCONZT7rvDcfDhn aCiHrmBQ==; Received: from localhost ([127.0.0.1] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtp (Exim 4.89 #1 (Red Hat Linux)) id 1epB0V-0002Ib-Gb; Fri, 23 Feb 2018 10:55:15 +0000 Received: from merlin.infradead.org ([2001:8b0:10b:1231::1]) by bombadil.infradead.org with esmtps (Exim 4.89 #1 (Red Hat Linux)) id 1epAnM-0002ym-I5 for linux-arm-kernel@bombadil.infradead.org; Fri, 23 Feb 2018 10:41:40 +0000 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=merlin.20170209; h=References:In-Reply-To:Message-Id:Date: Subject:Cc:To:From:Sender:Reply-To:MIME-Version:Content-Type: Content-Transfer-Encoding:Content-ID:Content-Description:Resent-Date: Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id: List-Help:List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=yTtftKTuyk9mvnahI37UwUVpztG3niifWNi5R55vYwI=; b=zjQe4eMD+pi46vSZUdeFzs6my XiCD0g8btrtoNa9DPJxtmX3oJwFX8ALQo/o/l3XrBosoeFNgU+tN9IYBHpviED78H3B2n19qXkTcg ym7c9z1jKCCobDrRvZXxl+K4HcuAHhIirvaGUM4CQUgsrQP3P1w5GviPm933Jx/GCnZsPzRFiyv4p +N65iNZ/YSuTfIkUHhtLN2BsgtBx7lyfCfMCLy7UB820ouPYl584XqStX8nlOK35EZIrlkpflJxpg R1GbiQsZ6Mn+ndiTiSGeDJpQ/It5HReCqUKYzjrT0bpQIEpf/B1JXB4AMrgls4xYegUSm0Rxe3g1M wr7IXskPA==; Received: from mail-pl0-x242.google.com ([2607:f8b0:400e:c01::242]) by merlin.infradead.org with esmtps (Exim 4.89 #1 (Red Hat Linux)) id 1epAX5-0007B1-RD for linux-arm-kernel@lists.infradead.org; Fri, 23 Feb 2018 10:24:52 +0000 Received: by mail-pl0-x242.google.com with SMTP id s13so4661437plq.6 for ; Fri, 23 Feb 2018 02:24:41 -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=yTtftKTuyk9mvnahI37UwUVpztG3niifWNi5R55vYwI=; b=OUG+LoH8dIsk1gv/hPWAUqThZ6jFunNwSAMOP/vLHr2rHBGLfb1VWieOGTY8nkRF5h uOItBja6pCKV2ThPCNPZhRKWXMkScaDDQNxERbgQIzzKBcj8VHcufLZZeoRVUSTJMJth sE6dGur2xKS+yuhmizA/Px5Ztv+izbse4IfUg= 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=yTtftKTuyk9mvnahI37UwUVpztG3niifWNi5R55vYwI=; b=KmKzxlezFTL7g9w1UjimN7yV6HtIfu2KChdlz2oW+eVqqxBkVoM4Dh+ypKJ+cmSLHn n3I3JNHilAeRSKG9v7Q/G5D2WYCYbh8xuyVvI/U/qAizkGWhLYrQPxCqxj+dCWP337Xs A0fccvOk4NFJdX9cpD8eRtyEFfUH16JX5upwZXBwdnPt8QuenfdNEh5b5NfwXC2ACV7c 65Tzg197vIhFI77FOaONiupN0Gz0Jub2Zu79hZtBpkXjtA75PlfwlGzD805e2orK134/ WOwOahdezanXlHQtK/cV9vJzcW1KYgqRYMEfy6tjkrxvUdWJHf1JMRjWyIt51MIIW5pq TSvw== X-Gm-Message-State: APf1xPCtXFsDdVMOQ2gdFukrMJO8nPspdhzjO1D6K47sQtvnIIoZiBpV gM90uzvq30u5ar+sbzkjBWdbOQ== X-Google-Smtp-Source: AH8x227imSka2VRMFskrF7A/zwSmDyC9X4xwb3euugyFAfMT8pdqEopnjyg6U3ZmCrhzpsLMLccgpQ== X-Received: by 2002:a17:902:6116:: with SMTP id t22-v6mr1249503plj.307.1519381479586; Fri, 23 Feb 2018 02:24:39 -0800 (PST) Received: from localhost ([122.167.232.138]) by smtp.gmail.com with ESMTPSA id z17sm3923443pfh.183.2018.02.23.02.24.38 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 23 Feb 2018 02:24:39 -0800 (PST) From: Viresh Kumar To: Greg Kroah-Hartman Subject: [PATCH V7 13/13] boot_constraint: Add documentation Date: Fri, 23 Feb 2018 15:53:52 +0530 Message-Id: <6b17ffecd9917ff4a1fad848839ea667e92d715f.1519380923.git.viresh.kumar@linaro.org> X-Mailer: git-send-email 2.15.0.194.g9af6a3dea062 In-Reply-To: References: In-Reply-To: References: X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20180223_052451_893511_25165B8E X-CRM114-Status: GOOD ( 24.73 ) X-BeenThere: linux-arm-kernel@lists.infradead.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: nm@ti.com, Rajendra Nayak , Stephen Boyd , Viresh Kumar , s.hauer@pengutronix.de, linux-kernel@vger.kernel.org, xuwei5@hisilicon.com, olof@lixom.net, robdclark@gmail.com, robh+dt@kernel.org, fabio.estevam@nxp.com, Vincent Guittot , shawnguo@kernel.org, linux-arm-kernel@lists.infradead.org, l.stach@pengutronix.de MIME-Version: 1.0 Sender: "linux-arm-kernel" Errors-To: linux-arm-kernel-bounces+patchwork-linux-arm=patchwork.kernel.org@lists.infradead.org X-Virus-Scanned: ClamAV using ClamSMTP 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 diff --git a/Documentation/driver-api/boot-constraint/constraints.rst b/Documentation/driver-api/boot-constraint/constraints.rst new file mode 100644 index 000000000000..6da2df33f2c9 --- /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/bootconstraint/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/bootconstraint/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/bootconstraint/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 e9b41b1634f3..f982e71efb73 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -49,6 +49,7 @@ available subsections can be seen below. dmaengine/index slimbus soundwire/index + boot-constraint/index .. only:: subproject and html