From patchwork Wed Mar 13 15:06:48 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Rob Herring X-Patchwork-Id: 160231 Delivered-To: patch@linaro.org Received: by 2002:a02:5cc1:0:0:0:0:0 with SMTP id w62csp14425636jad; Wed, 13 Mar 2019 08:06:52 -0700 (PDT) X-Google-Smtp-Source: APXvYqzxSc9W8e3E4urqmLW6SH6CDMb0gjTBAZn3XGwxje58sA4p5L80GMQFD7ubHF1j7UemHb9L X-Received: by 2002:a62:484:: with SMTP id 126mr44193261pfe.91.1552489612482; Wed, 13 Mar 2019 08:06:52 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1552489612; cv=none; d=google.com; s=arc-20160816; b=hpQeRA9YxWEWrL6HZ1mxZag6Va6iD1H0E2x4+jPw0ZDz+rFrQnfbhRqLB0RqHcAsEn Djp9HWw9ZIT1PkGuXeaQPgD5GKExES7ZIniMW3gpO5gGiUr4chOD1N2agZXsSnGvEF9r +BV+9UEMTtK4h0tc5g7OZpGA+HQAU2N6otFM2UeZQerKajsf+2//p/Rd8pFm5DtPVj/z xHbuFSpgTuC0PCVydoOj7tic1uNFLYKADX1Thmoj34kVxp05JgerL4n1UqUZbMVsrMlX 7SCVUakOOk91ECRkaab9xx/ACxbivlldaPPWjHA7c+Zo/ZYZpHtHd7nSItn4oVmHPTL0 Xxhg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:content-transfer-encoding:mime-version :message-id:date:subject:to:from; bh=MXVLhq9kpm2DZ6wvNbMETOIexe2mowMhAjdqPq0I9ZA=; b=xMnZJlMpyekvwVUZuk/N3ol/Da/Slb8GFS1eq1l4FIF05VvmIrQeNWI0J9jviHjmpR fNBWykzKNJ5q0IgxmtiDf+ucES0Si63l2r/h4aXL0JhUM5+c0YgxeDMTZ3gHRGhGPS2i Uh9eEbR1kAaaowuvoYUFZjz4HRWncf7LTPliTj1XMifVMJGCuSKj0MGE0ALcTZ3qDzoz CnyhKGwc4wrglUarshrgBnwlpnJkvTIk2hnqOqQq3l53psXZLzkru9JBGJlBXBGdPoWV WcaKbkIqdLz5zpuhZaFXLFkrpYzyA57su+zZ2vDl+LD6IOxpib6OVM/WjEJPpKMDBYkm CvTQ== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: best guess record for domain of devicetree-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=devicetree-owner@vger.kernel.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id y4si11100289plk.30.2019.03.13.08.06.52; Wed, 13 Mar 2019 08:06:52 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of devicetree-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of devicetree-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=devicetree-owner@vger.kernel.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726142AbfCMPGv (ORCPT + 7 others); Wed, 13 Mar 2019 11:06:51 -0400 Received: from mail-ot1-f66.google.com ([209.85.210.66]:33207 "EHLO mail-ot1-f66.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1725832AbfCMPGv (ORCPT ); Wed, 13 Mar 2019 11:06:51 -0400 Received: by mail-ot1-f66.google.com with SMTP id q24so2051384otk.0; Wed, 13 Mar 2019 08:06:51 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:subject:date:message-id:mime-version :content-transfer-encoding; bh=MXVLhq9kpm2DZ6wvNbMETOIexe2mowMhAjdqPq0I9ZA=; b=H0XCfEjJjRHOjK9IKWXU3Fa6zMjtWLAwp2pJ8K+FkrisxXwVqxCgRdsodEAMllcQv9 D3map5O4NNwvINKiJyWitnKpn04dIJpGzKzu/Xaxz4sfMBfk7mWAzDBD+6qj7RBJNfWA ziYygB9BFe+ynGnWMl3ujnk7Agv1NT6ulbb9YV9UGqjhDZzPFY7CkwiuLDJfkTFLcbsk +M9iDNCxwUqSdGwFGOWjWJTkQ+VGDbsz9VcLsmADc/kuBevD154zm+TPjLqmGLtQt9Rn B8rU5C7Ed9HyiznZINsdTVguFV3fdCch5oLm15sofZKVMaI5ZAYYoRUyUcM5Cf+B/JuR 6thA== X-Gm-Message-State: APjAAAVsIBu1faenyciTovPJA3A3xePeDfTmGNVKvSShhucUjS1QAhjK 7lnb/48xFl9G30bJbDDlJM4XSHE= X-Received: by 2002:a9d:7091:: with SMTP id l17mr29476943otj.198.1552489609679; Wed, 13 Mar 2019 08:06:49 -0700 (PDT) Received: from xps15.herring.priv (24-155-109-49.dyn.grandenetworks.net. [24.155.109.49]) by smtp.googlemail.com with ESMTPSA id y124sm4869409oie.57.2019.03.13.08.06.48 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Wed, 13 Mar 2019 08:06:49 -0700 (PDT) From: Rob Herring To: linux-kernel@vger.kernel.org, devicetree@vger.kernel.org Subject: [PATCH] dt-bindings: Add a guide of do's and don't's for writing bindings Date: Wed, 13 Mar 2019 10:06:48 -0500 Message-Id: <20190313150648.32404-1-robh@kernel.org> X-Mailer: git-send-email 2.19.1 MIME-Version: 1.0 Sender: devicetree-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: devicetree@vger.kernel.org Devicetree binding reviews have a lot of repeated review comments. Much of the guidelines aren't written down. This list of do's and don't's is by no means an exhaustive guide for how to write bindings, but at least the "rules" are written down in some form. Signed-off-by: Rob Herring --- .../devicetree/bindings/writing-bindings.txt | 60 +++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 Documentation/devicetree/bindings/writing-bindings.txt -- 2.19.1 diff --git a/Documentation/devicetree/bindings/writing-bindings.txt b/Documentation/devicetree/bindings/writing-bindings.txt new file mode 100644 index 000000000000..27dfd2d8016e --- /dev/null +++ b/Documentation/devicetree/bindings/writing-bindings.txt @@ -0,0 +1,60 @@ +DOs and DON'Ts for designing and writing Devicetree bindings + +This is a list of common review feedback items focused on binding design. With +every rule, there are exceptions and bindings have many gray areas. + +For guidelines related to patches, see +Documentation/devicetree/bindings/submitting-patches.txt + + +Overall design + +- DO attempt to make bindings complete even if a driver doesn't support some + features. For example, if a device has an interrupt, then include the + 'interrupts' property even if the driver is only polled mode. + +- DON'T refer to Linux or "device driver" in bindings. Bindings should be + based on what the hardware has, not what an OS and driver currently support. + +- DO use node names matching the class of the device. Many standard names are + defined in the DT Spec. If there isn't one, consider adding it. + +- DO check that the example matches the documentation especially after making + review changes. + +- DON'T create nodes just for the sake of instantiating drivers. Multi-function + devices only need child nodes when the child nodes have their own DT + resources. A single node can be multiple providers (e.g. clocks and resets). + +- DON'T use 'syscon' alone without a specific compatible string. A 'syscon' + hardware block should have a compatible string unique enough to infer the + register layout of the entire block (at a minimum). + + +Properties + +- DO make 'compatible' properties specific. DON'T use wildcards in compatible + strings. DO use fallback compatibles when devices are the same as or a subset + of prior implementations. DO add new compatibles in case there are new + features or bugs. + +- DO use a vendor prefix on device specific property names. Consider if + properties could be common among devices of the same class. Check other + existing bindings for similar devices. + +- DON'T redefine common properties. Just reference the definition and define + constraints specific to the device. + +- DO use common property unit suffixes for properties with scientific units. + See property-units.txt. + +- DO define properties in terms of constraints. How many entries? What are + possible values? What is the order? + + +Board/SoC .dts Files + +- DO put all MMIO devices under a bus node and not at the top-level. + +- DO use non-empty 'ranges' to limit the size of child buses/devices. 64-bit + platforms don't need all devices to have 64-bit address and size.