From patchwork Tue Jan 17 13:03:10 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Linus Walleij X-Patchwork-Id: 13104620 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org 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 smtp.lore.kernel.org (Postfix) with ESMTPS id A8FF4C63797 for ; Tue, 17 Jan 2023 13:04:22 +0000 (UTC) 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: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:In-Reply-To:References: List-Owner; bh=kLrYekb9+9aFzCQf77N2V6i2kcItW5W0vX5DoxmICSE=; b=ERcl5n1mcYXnny 0TJLgIP9H3miWQvA2B+dr0y1jKzV344JcRAoGX8k8/MqqKF7067sSvqXesWSvfm8HOXXHNnePxqUm qpIy6XVqR53VwVcD4vI2BhOGhYlM6iSi3qgwdBMnbhROAvmX03mBoWnUdT+yU5UDA+kNX4qfzyyIY DO3QPKmCCevAzRgR3Bb+lHM97L28eE9bk53KG/EyvTg0E4YSPQkkyZhv8voj4wwKwO1f6qW2gfBX+ osOACP3D6GlIkvBS5uTTmrapxqTTa+u3PpSYarMraKXMF1KUBIaoMO9eYBG8X06AWXy05LPxXW9uA c6r4PhP88wJTgNPMLB/A==; Received: from localhost ([::1] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtp (Exim 4.94.2 #2 (Red Hat Linux)) id 1pHlcY-00EIY7-TM; Tue, 17 Jan 2023 13:03:23 +0000 Received: from mail-ej1-x634.google.com ([2a00:1450:4864:20::634]) by bombadil.infradead.org with esmtps (Exim 4.94.2 #2 (Red Hat Linux)) id 1pHlcW-00EIWW-04 for linux-arm-kernel@lists.infradead.org; Tue, 17 Jan 2023 13:03:21 +0000 Received: by mail-ej1-x634.google.com with SMTP id hw16so63320384ejc.10 for ; Tue, 17 Jan 2023 05:03:15 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=OmXta0hG9IG3vOI9E/aHz0mdhlyVuxkuOdnYHs1S1h4=; b=Ma2UqanvLKTHtwpjYdcMlNcPn8ydMlAnipu9gas+3bZRVXMFhdFdDZsKL6L8GN2T++ yUO4DEbREe/lvNxz033f4gYiFWs2D9UTOmPCN9xRFeCiDhQhb1HFxjlDz61pdZHenY4p 7qzPg4mlLml1UX0xb2pr4ZMao+lgqk887TA8LpJLw9hz8tkJqncPzM3vQrxHUmQt/ANr y26gz6UWRwqp4HYET9QcCChGNjUHIjm0w68BcDu2DBhVEsEHrOcbg1sbPzjiiW4iE1hd bglvRSBSJ+ORHIPRmHMT6xGV7Nr7xUlPKKB70NvOa7+kLrXNasFp9C5stlf1ltuQTHFO 1O4g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=OmXta0hG9IG3vOI9E/aHz0mdhlyVuxkuOdnYHs1S1h4=; b=kOW1pQoIdbSEw7RunyS9uniGA9EID9/9I2NrFOU36r1MH7PnTt9YAFiaNUZx6c4FOj wRupBDGZ387RdqRIvUNZejRl18A7smR6SM8OlqlcMk+sJ3iv0oj7WKNAkbAt7sysuc+1 5yq6wkTGCT4L0kPf3tdceXmlwaDJMn94LNB1c1f+CPtSSNyRI818QsCa2EA3PkOQs7om yZHVYulVv44jNzRuZyN4tOhGgeXN94jJMXcGROd2LtoTsEr0crYojtAZHA1YKBfdo4vS lk75pcNLvZh0ELsXJPsi5PfNRQa+Yg+A9GBbyYaJa+sGBgG0vbOP25uPYlEtnvhzuOt+ UlLQ== X-Gm-Message-State: AFqh2kqIydRELG6zBIIuCy4sZKOgObx5+yRI5HRmcQdSIydKwZC3SkWQ g7kLvP5FElHyBAtsl5u7X9NcUQ== X-Google-Smtp-Source: AMrXdXvMdGquDZtT9+mCDweLoMaex0nK82kV8ckSUV2z5y3DVyJyfFsWn1Yg4aaJT+2tlghsIze00w== X-Received: by 2002:a17:907:6d21:b0:805:1e6e:6777 with SMTP id sa33-20020a1709076d2100b008051e6e6777mr22055019ejc.23.1673960594648; Tue, 17 Jan 2023 05:03:14 -0800 (PST) Received: from fedora.. ([85.235.10.72]) by smtp.gmail.com with ESMTPSA id e20-20020a170906249400b0084d4cb00f0csm10327030ejb.99.2023.01.17.05.03.13 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 17 Jan 2023 05:03:14 -0800 (PST) From: Linus Walleij To: devicetree@vger.kernel.org, Rob Herring , Krzysztof Kozlowski Cc: linux-arm-kernel@lists.infradead.org, Linus Walleij , Grant Likely Subject: [PATCH] docs: dt: Make references and mention kernel abstractions Date: Tue, 17 Jan 2023 14:03:10 +0100 Message-Id: <20230117130310.493966-1-linus.walleij@linaro.org> X-Mailer: git-send-email 2.39.0 MIME-Version: 1.0 X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20230117_050320_058194_C037D726 X-CRM114-Status: GOOD ( 25.27 ) 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: , Sender: "linux-arm-kernel" Errors-To: linux-arm-kernel-bounces+linux-arm-kernel=archiver.kernel.org@lists.infradead.org This document is named "Linux and Devicetree" so I think we should write a bit more about how the device tree fits into the Linux kernel frameworks these days after we have created the fwnode and swnode. Cc: Grant Likely Signed-off-by: Linus Walleij --- I bet you get the idea but Rob and Krzysztof probably have some ideas on where this goes and what goes into it so it it at least a starting point for discussions. --- Documentation/devicetree/usage-model.rst | 45 +++++++++++++++++++++--- 1 file changed, 41 insertions(+), 4 deletions(-) diff --git a/Documentation/devicetree/usage-model.rst b/Documentation/devicetree/usage-model.rst index b6a287955ee5..789744b45ab2 100644 --- a/Documentation/devicetree/usage-model.rst +++ b/Documentation/devicetree/usage-model.rst @@ -75,7 +75,44 @@ out of mainline (nios) have some level of DT support. If you haven't already read the Device Tree Usage\ [1]_ page, then go read it now. It's okay, I'll wait.... -2.1 High Level View +2.1 Linux Kernel Firmware Abstractions +-------------------------------------- + +The Linux kernel supports sevaral different hardware description +frameworks and DT is just one of them. The closest sibling is the +:ref:`Documentation/firmware-guide/acpi/index.rst ACPI` +DSDT (Differentiated System Description Table). + +To make it possible to write a device driver that will adapt to DT +or other hardware description models, the kernel has grown some +abstractions, first and foremost the firmware node API, exposing +device properties. The firmware node "fwnode" internals can be found +in ```` while the device driver-facing API can be +found in ````. The idea is that if a driver is using +the firmware node API, it should be trivial to support DT and ACPI +DSDT alike in the same driver. + +The fwnode framework also makes it possible to modify and extend the +Linux in-kernel model with software-managed nodes "swnodes" to apply +quirks or manage registration of devices that cannot be handled any +other way. This API can also be found in ````. + +Further, when the DT core register devices these need to fold into the +Linux device driver model, which essentially means that some kind of +``struct device`` has to be created to match a corresponding +``struct device_driver``. This API can be explored in +detail in :ref:`Documentation/driver-api/driver-model/index.rst the driver API documentation` +but what you need to know is that the Linux DT parser code will on its +own mostly spawn platform devices and AMBA devices on the platform +and AMBA bus respectively, and apart from that it will augment devices +spawn on other buses where applicable. + +Every Linux kernel subsystem that want to supply additional data to +detected devices using the device tree, or that want to provide +resources to other devices in the DT, will need to implement calls into +the DT abstractions. + +2.2 High Level View ------------------- The most important thing to understand is that the DT is simply a data structure that describes the hardware. There is nothing magical about @@ -97,7 +134,7 @@ Linux uses DT data for three major purposes: 2) runtime configuration, and 3) device population. -2.2 Platform Identification +2.3 Platform Identification --------------------------- First and foremost, the kernel will use data in the DT to identify the specific machine. In a perfect world, the specific platform shouldn't @@ -180,7 +217,7 @@ However, this approach does not take into account the priority of the compatible list, and probably should be avoided for new architecture support. -2.3 Runtime configuration +2.4 Runtime configuration ------------------------- In most cases, a DT will be the sole method of communicating data from firmware to the kernel, so also gets used to pass in runtime and @@ -217,7 +254,7 @@ On ARM, the function setup_machine_fdt() is responsible for early scanning of the device tree after selecting the correct machine_desc that supports the board. -2.4 Device population +2.5 Device population --------------------- After the board has been identified, and after the early configuration data has been parsed, then kernel initialization can proceed in the normal