From patchwork Wed Jan 16 19:40:18 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Simon Goldschmidt X-Patchwork-Id: 1026152 X-Patchwork-Delegate: sjg@chromium.org Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=none (mailfrom) smtp.mailfrom=lists.denx.de (client-ip=81.169.180.215; helo=lists.denx.de; envelope-from=u-boot-bounces@lists.denx.de; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=gmail.com Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.b="B0vXmnHj"; dkim-atps=neutral Received: from lists.denx.de (dione.denx.de [81.169.180.215]) by ozlabs.org (Postfix) with ESMTP id 43fyHJ3t6dz9sDX for ; Thu, 17 Jan 2019 06:40:39 +1100 (AEDT) Received: by lists.denx.de (Postfix, from userid 105) id 58762C22119; Wed, 16 Jan 2019 19:40:34 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on lists.denx.de X-Spam-Level: X-Spam-Status: No, score=0.0 required=5.0 tests=FREEMAIL_FROM, RCVD_IN_MSPIKE_H2, T_DKIM_INVALID autolearn=unavailable autolearn_force=no version=3.4.0 Received: from lists.denx.de (localhost [IPv6:::1]) by lists.denx.de (Postfix) with ESMTP id 41061C21E75; Wed, 16 Jan 2019 19:40:32 +0000 (UTC) Received: by lists.denx.de (Postfix, from userid 105) id 977A2C21E75; Wed, 16 Jan 2019 19:40:30 +0000 (UTC) Received: from mail-wr1-f66.google.com (mail-wr1-f66.google.com [209.85.221.66]) by lists.denx.de (Postfix) with ESMTPS id 42ADEC21C29 for ; Wed, 16 Jan 2019 19:40:30 +0000 (UTC) Received: by mail-wr1-f66.google.com with SMTP id q18so8310135wrx.9 for ; Wed, 16 Jan 2019 11:40:30 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id; bh=GM0RY8urP1vpEUm1Ys8NttmMuDyMSupLNVgsMzgMK0o=; b=B0vXmnHjmMwszSMMyL7cHt5+yDmNoUpA4oO6ZKuAeIQP/NV7/ICacEfDJsomi5IBJi AbtPpRchE9E1zQ9g1zjXdzLfUUhfhWZaRUDVxqXIqPaPH+DRyMVWmqyUiN0bjW9lqzyN CvJOmQ1B3R7HjrKBwJaejnVnvn9jObq3GWFP+NgI50LT0JhElT/wzE/7RPxVDoGWcv9a 7NvRM32O8osIMBRdP/a+b4OuvRgbsuKent6hDi15rGEBDxQbB+Ncy11hykkDvqObi9+L 0gFUm8b9h3flAYrd9l/rkuDQFdA5CrTOo4fVUXOw7XUaSb0Gut8D83rwc4DmLH0IEtZL e+Rg== 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; bh=GM0RY8urP1vpEUm1Ys8NttmMuDyMSupLNVgsMzgMK0o=; b=cgSp9WBA626jyb4xhhsuSGqemx5LQNNjQrY0zoMzlx92VP7JbPJFh70qQU5mS/hVO+ 7jES4G4+060ovSYv4iWKFW6rVAWgwwmW95sLsftEmhlDPzbgjL2y4gdG0nxq3sZtzC6T Up4C86RLvk/Onhf9tdxs1zEPJ3IDpgtbJrc9dGQQRjnjD90izAboo4fcy+wqg3p7lfPX DRE5J1q1zUvndhqB16JuoSAQ96xrmG9WhJTlw8SfkXy6WB4zntzIDiuJWLtU183ASbxz W/uX5zD8CXQ0cIk89tsIfJheHWlADPSRxMABWeyNRH+Pj/1iEkCiYkm+7voTkzH6xk7P Ugtw== X-Gm-Message-State: AJcUukfyt9j2lW4LNx90wxkMUFORzPzqTWUBylEj3sU6kwskxTcN6DRz oRfo43fR7O3m5E1ZU9U/ILE= X-Google-Smtp-Source: ALg8bN4R5vmvlSbNxMeDa3jwcaub+a4QqkSjiwp7lIrbJrP4EKW8DkKJ3lE7wLCYVMwIG0KVuqWEVQ== X-Received: by 2002:a5d:4e82:: with SMTP id e2mr8663516wru.291.1547667629671; Wed, 16 Jan 2019 11:40:29 -0800 (PST) Received: from ubuntu.home ([2a02:8071:6a3:700:8c22:ee0c:efc8:ed86]) by smtp.gmail.com with ESMTPSA id n5sm80912488wrr.94.2019.01.16.11.40.24 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Wed, 16 Jan 2019 11:40:25 -0800 (PST) From: Simon Goldschmidt To: Simon Glass , Lukasz Majewski Date: Wed, 16 Jan 2019 20:40:18 +0100 Message-Id: <20190116194018.6278-1-simon.k.r.goldschmidt@gmail.com> X-Mailer: git-send-email 2.17.1 Cc: u-boot@lists.denx.de, Michal Simek Subject: [U-Boot] [PATCH v2] of-platdata: improve documentation X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.18 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: u-boot-bounces@lists.denx.de Sender: "U-Boot" Improve some things in the documentation of OF_PLATDATA that I found while porting socfgpa_gen5 to it. Signed-off-by: Simon Goldschmidt Reviewed-by: Simon Glass Reviewed-by: Simon Glass --- Changes in v2: - further fixes noted by Simon Glass - added info about missing node relations - moved the passage about phandles into section 'caveats' doc/driver-model/of-plat.txt | 31 ++++++++++++++++++++----------- dts/Kconfig | 6 ++---- 2 files changed, 22 insertions(+), 15 deletions(-) diff --git a/doc/driver-model/of-plat.txt b/doc/driver-model/of-plat.txt index 732bc34f06..0109ec56c3 100644 --- a/doc/driver-model/of-plat.txt +++ b/doc/driver-model/of-plat.txt @@ -64,17 +64,24 @@ strictly necessary. Notable problems include: normally also supports device tree it must use #ifdef to separate out this code, since the structures are only available in SPL. + - Correct relations between nodes are not implemented. This means that + parent/child relations (like bus device iteration) do not work yet. + Some phandles (those that are recognised as such) are converted into + a pointer to platform data. This pointer can potentially be used to + access the referenced device (by searching for the pointer value). + This feature is not yet implemented, however. + How it works ------------ -The feature is enabled by CONFIG SPL_OF_PLATDATA. This is only available -in SPL and should be tested with: +The feature is enabled by CONFIG OF_PLATDATA. This is only available in +SPL/TPL and should be tested with: - #if CONFIG_IS_ENABLED(SPL_OF_PLATDATA) + #if CONFIG_IS_ENABLED(OF_PLATDATA) A new tool called 'dtoc' converts a device tree file either into a set of -struct declarations, one for each compatible node, or a set of +struct declarations, one for each compatible node, and a set of U_BOOT_DEVICE() declarations along with the actual platform data for each device. As an example, consider this MMC node: @@ -156,6 +163,13 @@ This avoids the code overhead of converting the device tree data to platform data in the driver. The ofdata_to_platdata() method should therefore do nothing in such a driver. +Note that for the platform data to be matched with a driver, the 'name' +property of the U_BOOT_DEVICE() declaration has to match a driver declared +via U_BOOT_DRIVER(). This effectively means that a U_BOOT_DRIVER() with a +'name' corresponding to the devicetree 'compatible' string (after converting +it to a valid name for C) is needed, so a dedicated driver is required for +each 'compatible' string. + Where a node has multiple compatible strings, a #define is used to make them equivalent, e.g.: @@ -165,8 +179,8 @@ equivalent, e.g.: Converting of-platdata to a useful form --------------------------------------- -Of course it would be possible use the of-platdata directly in your driver -whenever configuration information is required. However this meands that the +Of course it would be possible to use the of-platdata directly in your driver +whenever configuration information is required. However this means that the driver will not be able to support device tree, since the of-platdata structure is not available when device tree is used. It would make no sense to use this structure if device tree were available, since the structure has @@ -282,11 +296,6 @@ prevents them being used inadvertently. All usage must be bracketed with The dt-platdata.c file contains the device declarations and is is built in spl/dt-platdata.c. -Some phandles (thsoe that are recognised as such) are converted into -points to platform data. This pointer can potentially be used to access the -referenced device (by searching for the pointer value). This feature is not -yet implemented, however. - The beginnings of a libfdt Python module are provided. So far this only implements a subset of the features. diff --git a/dts/Kconfig b/dts/Kconfig index 8917f42444..3e85914d11 100644 --- a/dts/Kconfig +++ b/dts/Kconfig @@ -265,8 +265,7 @@ config SPL_OF_PLATDATA This option works by generating C structure declarations for each compatible string, then adding platform data and U_BOOT_DEVICE - declarations for each node. See README.platdata for more - information. + declarations for each node. See of-plat.txt for more information. config TPL_OF_PLATDATA bool "Generate platform data for use in TPL" @@ -287,8 +286,7 @@ config TPL_OF_PLATDATA This option works by generating C structure declarations for each compatible string, then adding platform data and U_BOOT_DEVICE - declarations for each node. See README.platdata for more - information. + declarations for each node. See of-plat.txt for more information. endmenu