Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/808219/?format=api
{ "id": 808219, "url": "http://patchwork.ozlabs.org/api/patches/808219/?format=api", "web_url": "http://patchwork.ozlabs.org/project/uboot/patch/20170831115955.56669-1-sjg@chromium.org/", "project": { "id": 18, "url": "http://patchwork.ozlabs.org/api/projects/18/?format=api", "name": "U-Boot", "link_name": "uboot", "list_id": "u-boot.lists.denx.de", "list_email": "u-boot@lists.denx.de", "web_url": null, "scm_url": null, "webscm_url": null, "list_archive_url": "", "list_archive_url_format": "", "commit_url_format": "" }, "msgid": "<20170831115955.56669-1-sjg@chromium.org>", "list_archive_url": null, "date": "2017-08-31T11:59:55", "name": "[U-Boot,v2] dm: core: Add livetree documentation", "commit_ref": "d944bf6b5e5c0248eebb035d3f6a67dec70d7dd9", "pull_url": null, "state": "accepted", "archived": false, "hash": "cd2c25ab9ad34163f5e3d13c605cbe0bb3d56e86", "submitter": { "id": 6170, "url": "http://patchwork.ozlabs.org/api/people/6170/?format=api", "name": "Simon Glass", "email": "sjg@chromium.org" }, "delegate": { "id": 3184, "url": "http://patchwork.ozlabs.org/api/users/3184/?format=api", "username": "sjg", "first_name": "Simon", "last_name": "Glass", "email": "sjg@chromium.org" }, "mbox": "http://patchwork.ozlabs.org/project/uboot/patch/20170831115955.56669-1-sjg@chromium.org/mbox/", "series": [ { "id": 809, "url": "http://patchwork.ozlabs.org/api/series/809/?format=api", "web_url": "http://patchwork.ozlabs.org/project/uboot/list/?series=809", "date": "2017-08-31T11:59:55", "name": "[U-Boot,v2] dm: core: Add livetree documentation", "version": 2, "mbox": "http://patchwork.ozlabs.org/series/809/mbox/" } ], "comments": "http://patchwork.ozlabs.org/api/patches/808219/comments/", "check": "pending", "checks": "http://patchwork.ozlabs.org/api/patches/808219/checks/", "tags": {}, "related": [], "headers": { "Return-Path": "<u-boot-bounces@lists.denx.de>", "X-Original-To": "incoming@patchwork.ozlabs.org", "Delivered-To": "patchwork-incoming@bilbo.ozlabs.org", "Authentication-Results": [ "ozlabs.org;\n\tspf=none (mailfrom) smtp.mailfrom=lists.denx.de\n\t(client-ip=81.169.180.215; helo=lists.denx.de;\n\tenvelope-from=u-boot-bounces@lists.denx.de;\n\treceiver=<UNKNOWN>)", "ozlabs.org;\n\tdkim=fail reason=\"signature verification failed\" (2048-bit key;\n\tunprotected) header.d=google.com header.i=@google.com\n\theader.b=\"WZdVmZln\"; dkim-atps=neutral" ], "Received": [ "from lists.denx.de (dione.denx.de [81.169.180.215])\n\tby ozlabs.org (Postfix) with ESMTP id 3xjgt25BXKz9t16\n\tfor <incoming@patchwork.ozlabs.org>;\n\tThu, 31 Aug 2017 22:00:10 +1000 (AEST)", "by lists.denx.de (Postfix, from userid 105)\n\tid 7ECA0C21DCB; Thu, 31 Aug 2017 12:00:07 +0000 (UTC)", "from lists.denx.de (localhost [IPv6:::1])\n\tby lists.denx.de (Postfix) with ESMTP id 8AD95C21C62;\n\tThu, 31 Aug 2017 12:00:03 +0000 (UTC)", "by lists.denx.de (Postfix, from userid 105)\n\tid 4A80DC21C62; Thu, 31 Aug 2017 12:00:01 +0000 (UTC)", "from mail-oi0-f46.google.com (mail-oi0-f46.google.com\n\t[209.85.218.46])\n\tby lists.denx.de (Postfix) with ESMTPS id 7EB98C21C51\n\tfor <u-boot@lists.denx.de>; Thu, 31 Aug 2017 12:00:00 +0000 (UTC)", "by mail-oi0-f46.google.com with SMTP id k77so3555981oib.2\n\tfor <u-boot@lists.denx.de>; Thu, 31 Aug 2017 05:00:00 -0700 (PDT)", "from kiwi.bld.corp.google.com ([100.101.164.89])\n\tby smtp.gmail.com with ESMTPSA id\n\tb186sm7288545oia.29.2017.08.31.04.59.57\n\t(version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128);\n\tThu, 31 Aug 2017 04:59:57 -0700 (PDT)", "by kiwi.bld.corp.google.com (Postfix, from userid 121222)\n\tid 8BC601404BE; Thu, 31 Aug 2017 05:59:56 -0600 (MDT)" ], "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=RCVD_IN_DNSWL_NONE,\n\tRCVD_IN_MSPIKE_H3, RCVD_IN_MSPIKE_WL,\n\tT_DKIM_INVALID autolearn=unavailable\n\tautolearn_force=no version=3.4.0", "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com;\n\ts=20161025; h=sender:from:to:cc:subject:date:message-id;\n\tbh=Mrx5jUSnzrTZmBhNcu+35QmIMBDJFy809zGebqGjAfw=;\n\tb=WZdVmZlnx6VLHXuFDlHZZq9zvsN6ect+YjZqavoOQwBtaCCoi/5nq/yTaMkEW6TAx7\n\tjUnCBamI9v8w5j8u7EKrAmLtFXomO8WfKfxPCubGugiPp8q++fkhf1OB0mMTRgdS4hdL\n\tWlr+VGGrjnQSBhaFmpHf4fpG0ZAmdK319CxTULsfIrUk3WIWTVPjIrNChCEWkwthfHeR\n\t3j/U9qFQQVfheRvwmJOceswauplMHZ4RK8y+CzDuaoDp8kQarZBTsUUkxixyOKmrsVj+\n\tv+nU22VU0Bwqtk0suTdplxpxs1Ku9eMnrKbiOyC4G0fwp0Ywuxbkt2qF2sg2WIKmF2u4\n\t45mA==", "X-Google-DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed;\n\td=1e100.net; s=20161025;\n\th=x-gm-message-state:sender:from:to:cc:subject:date:message-id;\n\tbh=Mrx5jUSnzrTZmBhNcu+35QmIMBDJFy809zGebqGjAfw=;\n\tb=iindWuAoej1uDo5jN6Q7UrAqgJAcWcV1CHpXPPXoPD4P1nKdLkVDCDo4RDiAp6ddhU\n\tOLaxRiB8VXHltR9ktSJkBIv4ochBTZc1RIi8NWzo+MfWPFGFa5WMJjZT/NAoSutxLY95\n\tAoEAfIIx9o3D+LMcsPWqlsZ4Umy8IYLMm74Y4LOOu71Ltqs31ZhptbVy1VbtmS4BgB2G\n\tDAm703ArwxWV5mqum6zSuPKVQj+0N4nNiOS/ltuF7xilsKHyJQbysPF1GL8uXa9TWftr\n\thaDJbXYeEEw1ARILaYgB9IHkX5bX+qrS8RyPLBGhc8s0UsspIQJhFmjaPWzEJUkP8eNT\n\toWZQ==", "X-Gm-Message-State": "AHYfb5h9+ZZW10Md8eNeyxivhnRmICh995fc4uhEhfh6qS8SxBjHxhXL\n\teBKRM8Rm8MOZlKhp", "X-Google-Smtp-Source": "ADKCNb4bIgcLUvEzf25T3DlyGPScOO4X9axyQrxi1rMMmbuWchFPv6WyvwgPhBkIrqfbFtQw9dnvKA==", "X-Received": "by 10.202.170.20 with SMTP id t20mr4884520oie.38.1504180798674; \n\tThu, 31 Aug 2017 04:59:58 -0700 (PDT)", "From": "Simon Glass <sjg@chromium.org>", "To": "U-Boot Mailing List <u-boot@lists.denx.de>", "Date": "Thu, 31 Aug 2017 05:59:55 -0600", "Message-Id": "<20170831115955.56669-1-sjg@chromium.org>", "X-Mailer": "git-send-email 2.14.1.581.gf28d330327-goog", "Cc": "Tom Rini <trini@konsulko.com>", "Subject": "[U-Boot] [PATCH v2] dm: core: Add livetree documentation", "X-BeenThere": "u-boot@lists.denx.de", "X-Mailman-Version": "2.1.18", "Precedence": "list", "List-Id": "U-Boot discussion <u-boot.lists.denx.de>", "List-Unsubscribe": "<https://lists.denx.de/options/u-boot>,\n\t<mailto:u-boot-request@lists.denx.de?subject=unsubscribe>", "List-Archive": "<http://lists.denx.de/pipermail/u-boot/>", "List-Post": "<mailto:u-boot@lists.denx.de>", "List-Help": "<mailto:u-boot-request@lists.denx.de?subject=help>", "List-Subscribe": "<https://lists.denx.de/listinfo/u-boot>,\n\t<mailto:u-boot-request@lists.denx.de?subject=subscribe>", "MIME-Version": "1.0", "Content-Type": "text/plain; charset=\"utf-8\"", "Content-Transfer-Encoding": "base64", "Errors-To": "u-boot-bounces@lists.denx.de", "Sender": "\"U-Boot\" <u-boot-bounces@lists.denx.de>" }, "content": "Add some documentation for the live device tree support in U-Boot. This\nwas missing from the initial series.\n\nSigned-off-by: Simon Glass <sjg@chromium.org>\nSuggested-by: Lukasz Majewski <lukma@denx.de>\n---\n\nChanges in v2:\n- Fix several typos\n\n doc/driver-model/livetree.txt | 272 ++++++++++++++++++++++++++++++++++++++++++\n 1 file changed, 272 insertions(+)\n create mode 100644 doc/driver-model/livetree.txt", "diff": "diff --git a/doc/driver-model/livetree.txt b/doc/driver-model/livetree.txt\nnew file mode 100644\nindex 0000000000..01d4488c60\n--- /dev/null\n+++ b/doc/driver-model/livetree.txt\n@@ -0,0 +1,272 @@\n+Driver Model with Live Device Tree\n+==================================\n+\n+\n+Introduction\n+------------\n+\n+Traditionally U-Boot has used a 'flat' device tree. This means that it\n+reads directly from the device tree binary structure. It is called a flat\n+device tree because nodes are listed one after the other, with the\n+hierarchy detected by tags in the format.\n+\n+This document describes U-Boot's support for a 'live' device tree, meaning\n+that the tree is loaded into a hierarchical data structure within U-Boot.\n+\n+\n+Motivation\n+----------\n+\n+The flat device tree has several advantages:\n+\n+- it is the format produced by the device tree compiler, so no translation\n+is needed\n+\n+- it is fairly compact (e.g. there is no need for pointers)\n+\n+- it is accessed by the libfdt library, which is well tested and stable\n+\n+\n+However the flat device tree does have some limitations. Adding new\n+properties can involve copying large amounts of data around to make room.\n+The overall tree has a fixed maximum size so sometimes the tree must be\n+rebuilt in a new location to create more space. Even if not adding new\n+properties or nodes, scanning the tree can be slow. For example, finding\n+the parent of a node is a slow process. Reading from nodes involves a\n+small amount parsing which takes a little time.\n+\n+Driver model scans the entire device tree sequentially on start-up which\n+avoids the worst of the flat tree's limitations. But if the tree is to be\n+modified at run-time, a live tree is much faster. Even if no modification\n+is necessary, parsing the tree once and using a live tree from then on\n+seems to save a little time.\n+\n+\n+Implementation\n+--------------\n+\n+In U-Boot a live device tree ('livetree') is currently supported only\n+after relocation. Therefore we need a mechanism to specify a device\n+tree node regardless of whether it is in the flat tree or livetree.\n+\n+The 'ofnode' type provides this. An ofnode can point to either a flat tree\n+node (when the live tree node is not yet set up) or a livetree node. The\n+caller of an ofnode function does not need to worry about these details.\n+\n+The main users of the information in a device tree are drivers. These have\n+a 'struct udevice *' which is attached to a device tree node. Therefore it\n+makes sense to be able to read device tree properties using the\n+'struct udevice *', rather than having to obtain the ofnode first.\n+\n+The 'dev_read_...()' interface provides this. It allows properties to be\n+easily read from the device tree using only a device pointer. Under the\n+hood it uses ofnode so it works with both flat and live device trees.\n+\n+\n+Enabling livetree\n+-----------------\n+\n+CONFIG_OF_LIVE enables livetree. When this option is enabled, the flat\n+tree will be used in SPL and before relocation in U-Boot proper. Just\n+before relocation a livetree is built, and this is used for U-Boot proper\n+after relocation.\n+\n+Most checks for livetree use CONFIG_IS_ENABLED(OF_LIVE). This means that\n+for SPL, the CONFIG_SPL_OF_LIVE option is checked. At present this does\n+not exist, since SPL does not support livetree.\n+\n+\n+Porting drivers\n+---------------\n+\n+Many existing drivers use the fdtdec interface to read device tree\n+properties. This only works with a flat device tree. The drivers should be\n+converted to use the dev_read_() interface.\n+\n+For example, the old code may be like this:\n+\n+ struct udevice *bus;\n+ const void *blob = gd->fdt_blob;\n+ int node = dev_of_offset(bus);\n+\n+ i2c_bus->regs = (struct i2c_ctlr *)devfdt_get_addr(dev);\n+ plat->frequency = fdtdec_get_int(blob, node, \"spi-max-frequency\", 500000);\n+\n+The new code is:\n+\n+ struct udevice *bus;\n+\n+ i2c_bus->regs = (struct i2c_ctlr *)dev_read_addr(dev);\n+ plat->frequency = dev_read_u32_default(bus, \"spi-max-frequency\", 500000);\n+\n+The dev_read_...() interface is more convenient and works with both the\n+flat and live device trees. See include/dm/read.h for a list of functions.\n+\n+Where properties must be read from sub-nodes or other nodes, you must fall\n+back to using ofnode. For example, for old code like this:\n+\n+ const void *blob = gd->fdt_blob;\n+ int subnode;\n+\n+ fdt_for_each_subnode(subnode, blob, dev_of_offset(dev)) {\n+ freq = fdtdec_get_int(blob, node, \"spi-max-frequency\", 500000);\n+ ...\n+ }\n+\n+you should use:\n+\n+ ofnode subnode;\n+\n+ ofnode_for_each_subnode(subnode, dev_ofnode(dev)) {\n+ freq = ofnode_read_u32(node, \"spi-max-frequency\", 500000);\n+ ...\n+ }\n+\n+\n+Useful ofnode functions\n+-----------------------\n+\n+The internal data structures of the livetree are defined in include/dm/of.h :\n+\n+ struct device_node - holds information about a device tree node\n+ struct property - holds information about a property within a node\n+\n+Nodes have pointers to their first property, their parent, their first child\n+and their sibling. This allows nodes to be linked together in a hierarchical\n+tree.\n+\n+Properties have pointers to the next property. This allows all properties of\n+a node to be linked together in a chain.\n+\n+It should not be necessary to use these data structures in normal code. In\n+particular, you should refrain from using functions which access the livetree\n+directly, such as of_read_u32(). Use ofnode functions instead, to allow your\n+code to work with a flat tree also.\n+\n+Some conversion functions are used internally. Generally these are not needed\n+for driver code. Note that they will not work if called in the wrong context.\n+For example it is invalid to call ofnode_to_no() when a flat tree is being\n+used. Similarly it is not possible to call ofnode_to_offset() on a livetree\n+node.\n+\n+ ofnode_to_np() - converts ofnode to struct device_node *\n+ ofnode_to_offset() - converts ofnode to offset\n+\n+ no_to_ofnode() - converts node pointer to ofnode\n+ offset_to_ofnode() - converts offset to ofnode\n+\n+\n+Other useful functions:\n+\n+ of_live_active() returns true if livetree is in use, false if flat tree\n+ ofnode_valid() return true if a given node is valid\n+ ofnode_is_np() returns true if a given node is a livetree node\n+ ofnode_equal() compares two ofnodes\n+ ofnode_null() returns a null ofnode (for which ofnode_valid() returns false)\n+\n+\n+Phandles\n+--------\n+\n+There is full phandle support for live tree. All functions make use of\n+struct ofnode_phandle_args, which has an ofnode within it. This supports both\n+livetree and flat tree transparently. See for example\n+ofnode_parse_phandle_with_args().\n+\n+\n+Reading addresses\n+-----------------\n+\n+You should use dev_read_addr() and friends to read addresses from device-tree\n+nodes.\n+\n+\n+fdtdec\n+------\n+\n+The existing fdtdec interface will eventually be retired. Please try to avoid\n+using it in new code.\n+\n+\n+Modifying the livetree\n+----------------------\n+\n+This is not currently supported. Once implemented it should provide a much\n+more efficient implementation for modification of the device tree than using\n+the flat tree.\n+\n+\n+Internal implementation\n+-----------------------\n+\n+The dev_read_...() functions have two implementations. When\n+CONFIG_DM_DEV_READ_INLINE is enabled, these functions simply call the ofnode\n+functions directly. This is useful when livetree is not enabled. The ofnode\n+functions call ofnode_is_np(node) which will always return false if livetree\n+is disabled, just falling back to flat tree code.\n+\n+This optimisation means that without livetree enabled, the dev_read_...() and\n+ofnode interfaces do not noticeably add to code size.\n+\n+The CONFIG_DM_DEV_READ_INLINE option defaults to enabled when livetree is\n+disabled.\n+\n+Most livetree code comes directly from Linux and is modified as little as\n+possible. This is deliberate since this code is fairly stable and does what\n+we want. Some features (such as get/put) are not supported. Internal macros\n+take care of removing these features silently.\n+\n+Within the of_access.c file there are pointers to the alias node, the chosen\n+node and the stdout-path alias.\n+\n+\n+Errors\n+------\n+\n+With a flat device tree, libfdt errors are returned (e.g. -FDT_ERR_NOTFOUND).\n+For livetree normal 'errno' errors are returned (e.g. -ENOTFOUND). At present\n+the ofnode and dev_read_...() functions return either one or other type of\n+error. This is clearly not desirable. Once tests are added for all the\n+functions this can be tidied up.\n+\n+\n+Adding new access functions\n+---------------------------\n+\n+Adding a new function for device-tree access involves the following steps:\n+\n+ - Add two dev_read() functions:\n+\t- inline version in the read.h header file, which calls an ofnode\n+\t\tfunction\n+\t- standard version in the read.c file (or perhaps another file), which\n+\t\talso calls an ofnode function\n+\n+\tThe implementations of these functions can be the same. The purpose\n+\tof the inline version is purely to reduce code size impact.\n+\n+ - Add an ofnode function. This should call ofnode_is_np() to work out\n+\twhether a livetree or flat tree is used. For the livetree it should\n+\tcall an of_...() function. For the flat tree it should call an\n+\tfdt_...() function. The livetree version will be optimised out at\n+\tcompile time if livetree is not enabled.\n+\n+ - Add an of_...() function for the livetree implementation. If a similar\n+\tfunction is available in Linux, the implementation should be taken\n+\tfrom there and modified as little as possible (generally not at all).\n+\n+\n+Future work\n+-----------\n+\n+Live tree support was introduced in U-Boot 2017.07. There is still quite a bit\n+of work to do to flesh this out:\n+\n+- tests for all access functions\n+- support for livetree modification\n+- addition of more access functions as needed\n+- support for livetree in SPL and before relocation (if desired)\n+\n+\n+--\n+Simon Glass <sjg@chromium.org>\n+5-Aug-17\n", "prefixes": [ "U-Boot", "v2" ] }