From nobody Fri Jul 24 23:35:26 2026 Received: from mx0a-0031df01.pphosted.com (mx0a-0031df01.pphosted.com [205.220.168.131]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id B66792EA75E for ; Wed, 22 Jul 2026 06:22:49 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=205.220.168.131 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1784701370; cv=none; b=OptF+I/KXlDmkkkAKZIAjzYc4D5UIVKkBXDpZWYBeuY0Nt2USQNy2yigKOojRmpWqnFe37Qr78jivcFGzz0gYRL7xSNA4U2qTtUXF6MGeH0pod6QNdAzUG7OR8t6h/psl7RSEUi2mvw8j9tC1Vm0EcoRPBBr+mwxuNSXRHH2/JU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1784701370; c=relaxed/simple; bh=OIx4wh2CtIAOIh+YltX8TMvP2J5GYPy71LnZDuty8dY=; h=From:To:Cc:Subject:Date:Message-ID:MIME-Version; b=Gm4wV6EepRyYuhkw4IvXh7QfNtDqhnKHZYKkjAYbd0/wgMdGPI6nHq3H4S63wjz5FXZckGTjSKPTy398uLayN16N+cm4aOlit5o69hB7UwyfNwmccZgAMVl0orNOFiLSLn2RWhj8xV8zS7cxQ9WAOua1ag+TW6y8Td3+FZEYSFM= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=oss.qualcomm.com; spf=pass smtp.mailfrom=oss.qualcomm.com; dkim=pass (2048-bit key) header.d=qualcomm.com header.i=@qualcomm.com header.b=QDuy4X3d; dkim=pass (2048-bit key) header.d=oss.qualcomm.com header.i=@oss.qualcomm.com header.b=BimwHl3Q; arc=none smtp.client-ip=205.220.168.131 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=oss.qualcomm.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=oss.qualcomm.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=qualcomm.com header.i=@qualcomm.com header.b="QDuy4X3d"; dkim=pass (2048-bit key) header.d=oss.qualcomm.com header.i=@oss.qualcomm.com header.b="BimwHl3Q" Received: from pps.filterd (m0279864.ppops.net [127.0.0.1]) by mx0a-0031df01.pphosted.com (8.18.1.11/8.18.1.11) with ESMTP id 66M54G8m3474603 for ; Wed, 22 Jul 2026 06:22:49 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=qualcomm.com; h= cc:content-transfer-encoding:date:from:message-id:mime-version :subject:to; s=qcppdkim1; bh=Pi2jq6VI0YK4T8L0Ox3TFJViHrhjp/ljuhL yyaW44P0=; b=QDuy4X3d4g9BL0Kaj+fZXqaME8m1N/u1olL6dnHcfzb5ivVsRyJ qe672oJJEjHr3dmId5TAPUCbsRJlq5jyMRREys+Qr4I38neOM3IbdQ03yuGF75LZ 6q5Rj6Dn7SjgZXY7+g56FoA70P0Hx3s0z/HtmKhZ0K1eaRSUPm+KDooXWE09mOF4 6sl1PTpiwYOI++Y7tIdCM9TA3JQXUZRmV3A3uuH/fhQLEXg9F+6bJvnjA0VwH33W 3zcSsFXUYufVw5jsYRgNVvxJ7uGnCVqDoRu/iQ2Xf/E1trnQBykmeEOkaTVLZcmx B5sELhN+/dJVEnRZgmYBW022fRon2MwEMLg== Received: from mail-qt1-f199.google.com (mail-qt1-f199.google.com [209.85.160.199]) by mx0a-0031df01.pphosted.com (PPS) with ESMTPS id 4fjd6ftjgx-1 (version=TLSv1.3 cipher=TLS_AES_128_GCM_SHA256 bits=128 verify=NOT) for ; Wed, 22 Jul 2026 06:22:49 +0000 (GMT) Received: by mail-qt1-f199.google.com with SMTP id d75a77b69052e-51c1d137a68so332749381cf.3 for ; Tue, 21 Jul 2026 23:22:48 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oss.qualcomm.com; s=google; t=1784701368; x=1785306168; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to:content-type; bh=Pi2jq6VI0YK4T8L0Ox3TFJViHrhjp/ljuhLyyaW44P0=; b=BimwHl3QuxdfrDHS3L4QHSL0AnEbyEhy9pcxGRmmF9QB9hweC2TMm2oHE+SFAC9OFW wLA69cR3BuIohK7KV4P5PsUpZLUesgKNP/R4CsZrsq6iSIeFGLyyEvp6u2fMHonTPo6u /fZkRvdWxlMfK5Clk/QjpeiuT8d4996UqlgMX6iqpHlRubQuMlQjb74TapPsZEPw2EO1 99XODqF6nILZKhZ21MndSInR8Dp3LcGWqoqCw0PrPp8RdhLFASoXcYA/4n8svXIYtjVp 8I+09yUOvYgsB3wcPU0wspE8SjMyitySTB1DdvJ8iRmfqOqLDsBtUqEVWRWCmcwINI/O yx1w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1784701368; x=1785306168; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-gg:x-gm-message-state:from:to:cc:subject:date :message-id:reply-to:content-type; bh=Pi2jq6VI0YK4T8L0Ox3TFJViHrhjp/ljuhLyyaW44P0=; b=ovVgN+jt0OIuOFSQHGqSqX/Mo5iILX2HcLP/S/cvI3UwfLlacr9MXkhoCLgqjUeUZe PsEqSCd8Z5OGoDMOewcsZkLvSWEqq/++StY/l3mQk0oS31BM7ER8WfQ/OgHYolnk//bT GwCGUuK+HKegJ0h6IOj6F+1RSLDkWpAqGncBQAO83I9lRmIigqJTjMQA0QnjJ18b3Q2x wulc/k37oFxkMz4I94CDmMwGw7iHJ9USs72BmkBCHAouFiUQYaxeOnkVK3RJfRbBITl6 cwJ5rprQvESsY1/znuj7b/WYYFu/b53L31wR1CO9pR5ZYTl/2k2MrwLkNWE5NC2CVPBq yNuw== X-Forwarded-Encrypted: i=1; AHgh+RqNX084eVwucTkZlNw484mxsRsFDexfD4dkdG/g+Oa9eguPfHRUhr1q5rXhkwWBk/zoeREHYAtDn5UCd9A=@vger.kernel.org X-Gm-Message-State: AOJu0YyOsYjyalPbUe3xSytXpHx9RS64ERWH9pfn0JJdO0v+FG38LMtb aEyyoY/27VREGkll5+vSIgJVpJlmFbab5t9x2e+dV/u861ElmM6rKAzZ3duuFDE5Hn7Xxlc5PgJ cFqmXmcjAlBRMLYqqQYGw6uSzIJfW4MmS6vLQOHMAIsGfptRP1oIzDgvs1VcCetR8Xb87OmR5Gc Q= X-Gm-Gg: AR+sD10PwPh3G6TN5pRg3Heqzy9XjC+LPVx1BwCaDLm55QzQaNRJ+fkBqzg2i9MfZlN CSP6kPcBQcdBZ6VeYFXdcyWoOYrI3vyydPreqaDPzw0C4YedN0GkKRv9SutHmcoH7Q39qfOxdAa L9+bsGAdnHzur7upK+QLGR/kVpdAizpDTYrecMXAMyNxmYv1nfJmJjdbTprMl8vVGuGMH/h/S0p /rF509RQC3aPNwcvxdOUz/+OJ71fRpIqvRkny9CRMeFxKj/9G2GaLey4nnTM6fbCjXv3i7e86oQ hKA1sbx0IDrMCCyuZGvTsrP4X53PkxvcXffNhEFKi4b+ITkoGTlrMs/HWvtfq425LxE6rGtnQE6 D/gmDLYUdiJ/AyEEv X-Received: by 2002:a05:622a:5d1:b0:51c:7b11:41a1 with SMTP id d75a77b69052e-5213f46e365mr204032721cf.78.1784701368128; Tue, 21 Jul 2026 23:22:48 -0700 (PDT) X-Received: by 2002:a05:622a:5d1:b0:51c:7b11:41a1 with SMTP id d75a77b69052e-5213f46e365mr204032491cf.78.1784701367539; Tue, 21 Jul 2026 23:22:47 -0700 (PDT) Received: from quoll ([178.197.223.174]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-47f85bb5127sm3257224f8f.10.2026.07.21.23.22.46 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 21 Jul 2026 23:22:46 -0700 (PDT) From: Krzysztof Kozlowski To: Rob Herring , Krzysztof Kozlowski , Conor Dooley , devicetree@vger.kernel.org, linux-kernel@vger.kernel.org Cc: Krzysztof Kozlowski Subject: [PATCH v2] docs: dt: writing-schema: Extend expectations about example part of binding Date: Wed, 22 Jul 2026 08:22:41 +0200 Message-ID: <20260722062240.19382-2-krzysztof.kozlowski@oss.qualcomm.com> X-Mailer: git-send-email 2.53.0 Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-Developer-Signature: v=1; a=openpgp-sha256; l=2239; i=krzysztof.kozlowski@oss.qualcomm.com; h=from:subject; bh=OIx4wh2CtIAOIh+YltX8TMvP2J5GYPy71LnZDuty8dY=; b=owEBbQKS/ZANAwAKAcE3ZuaGi4PXAcsmYgBqYGGwv59oZWRp09y2oIN0/hjUth0QVHMXxkxnn 080qBhYMZqJAjMEAAEKAB0WIQTd0mIoPREbIztuuKjBN2bmhouD1wUCamBhsAAKCRDBN2bmhouD 11RJD/wNNQ6r/pTqDCzHrT1kyFGCvGoOHl10eK4ztGuLly624kydOuNRF7ONdJk9EOgOGM4wIpQ zmassz4qX2tv4N7UEIGUmrkCQQxSLXnxBADHR59jgAtmlWEmr+wn309u/VLpLgOEATGXwd5RYmw Ltih1TESQ3VKgvoWJ63G9suIGB8Yzf4Q7UmaTvOtYaumxgxhT0jDhQNBvB0ePfvCSI42apYwoid EPrvYFo+BCG8oAqSe+Uu5a0qn2LJwZZlqPsbJioJ5hxG5lzhWiDNiLod1oi2YEPxP8FSw5SEmd2 cVikEdoBgwObrSAYf2BVO7u9QB3Nu3mr39PumJWZQx7bM1SEKTEMwMANfsH3NkglKPTtq1lLq59 bIoglC2OTUK8h+Fw3Mr4VNfxo+ywqb6e9YKas8jnAgECpqtJP9h8pPqPzMJMX0tyQdYuSVBZQA2 oda9DZ6XRzmV6t0yu8vlg4m1XIiCPi3lh8eDtexBDyNdaU2WZD47TWdet6qZQHyel2048V/jTOU VuP9Rd44WHaZe0ZAdn8WYbCxpGC1bwDxnwALfV5De1ZFh2EU9OlglyexXzcCIX+DuvlzpwrCp9P qNsI6P/i4C8EbCnvb+rt6//zzz48VuHRpzj1dEfn80s7Tj5Lm1p8sKciW6EmNLP+G7cLxYzGrYD WSMlPOEQE5haadg== X-Developer-Key: i=krzysztof.kozlowski@oss.qualcomm.com; a=openpgp; fpr=9BD07E0E0C51F8D59677B7541B93437D3B41629B Content-Transfer-Encoding: quoted-printable X-Proofpoint-GUID: S4-qfkhzsi9kQwpQeHXenkHtCJ3jfvAQ X-Proofpoint-Spam-Details-Enc: AW1haW4tMjYwNzIyMDA1NyBTYWx0ZWRfX0mb4e9JO9A1N vIGUjpAe+hNX+nVkN/O21E7SY38eYSp2t1wadGTafouxfTNyhQCHB2CfjB7hsWEtPucLXAHIh36 /mExG75tMzZ/Zr5looeEzDR1k4/+xLA52eVvPJvACgQhTjIoUptrbbX+kbq2c1o6x+90y1V9s0u SEGVINkSNxsVoen7rgKxUcHVSfq4llFQ/lCXRmxUdCESFczgp1is30wK42VJGmUy/afY1OapoPV wWKniAzVslCVkU7BLNHRtHkA1Pk8hH6O99+MfjyfTGJDPbrWhscy3li9Q0CP0YVuI2SjvkmJPC2 rHZgZztXganL0TEBYU1GssPaGtIADIfiAQTfqf7eNi3SSOXqeyZV69ENmUXRlNCwJLEWH9RVfUQ PLs81kx77fcQcKhaU9ZW4H8vGtLFD5Z4ZwySfD7u3ulV6hYKjqMfduNeKpkK6a+omFuxJ2eMFjP k/DjdmN3pLw398QhlkA== X-Authority-Analysis: v=2.4 cv=e/o2j6p/ c=1 sm=1 tr=0 ts=6a6061b9 cx=c_pps a=WeENfcodrlLV9YRTxbY/uA==:117 a=N6niishs+lR9UBL1FN3Qrw==:17 a=RAioF0-LDSMA:10 a=s4-Qcg_JpJYA:10 a=VkNPw1HP01LnGYTKEx00:22 a=u7WPNUs3qKkmUXheDGA7:22 a=DJpcGTmdVt4CTyJn9g5Z:22 a=EUspDBNiAAAA:8 a=L8bdGj0wTZrxn9lFt18A:9 a=kacYvNCVWA4VmyqE58fU:22 X-Proofpoint-ORIG-GUID: S4-qfkhzsi9kQwpQeHXenkHtCJ3jfvAQ X-Proofpoint-Spam-Info: AW1haW4tMjYwNzIyMDA1NyBTYWx0ZWRfX/qdE7QDp7m8V O8idfJ6EoPa3PvzUbuaBs8y8740LPIrKyjrBfacWkHxBCg6WBaVfdKcRtvfm4nZu4O+nWMuTTzd zGaxutFBvmx+u0/StnjlWMVF56a6xOs= X-Proofpoint-Virus-Version: vendor=baseguard engine=ICAP:2.0.293,Aquarius:18.0.1143,Hydra:6.1.134,FMLib:17.12.100.49 definitions=2026-07-22_02,2026-07-21_01,2025-10-01_01 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 malwarescore=0 suspectscore=0 spamscore=0 bulkscore=0 priorityscore=1501 impostorscore=0 lowpriorityscore=0 phishscore=0 clxscore=1015 adultscore=0 classifier=typeunknown authscore=0 authtc= authcc= route=outbound adjust=0 reason=mlx scancount=1 engine=8.22.0-2606150000 definitions=main-2607220057 Content-Type: text/plain; charset="utf-8" Document already used rules about example DTS in the binding: - All final device bindings (except sub-block of more complex devices) should have an example. - Phandles do not need to be resolvable - Sashiko already provided incorrect review, so this might help it to understand the concept. - Example should be complete, readable (use known defines), without 'status' property. Signed-off-by: Krzysztof Kozlowski --- Changes in v2: 1. Rewrite "optional" exception, as Conor suggested. 2. "normal" -> "typical" in last sentence about status. --- .../devicetree/bindings/writing-schema.rst | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/Documentation/devicetree/bindings/writing-schema.rst b/Documen= tation/devicetree/bindings/writing-schema.rst index 3ffd0828617a..d31b94300f46 100644 --- a/Documentation/devicetree/bindings/writing-schema.rst +++ b/Documentation/devicetree/bindings/writing-schema.rst @@ -127,9 +127,16 @@ additionalProperties / unevaluatedProperties two above cases ('false'). =20 examples - Optional. A list of one or more DTS hunks implementing this binding only. - Example should not contain unrelated device nodes, e.g. consumer nodes i= n a - provider binding, other nodes referenced by phandle. + Optional, although expected outside of bindings describing common proper= ties + or sub-blocks of more complex devices. A list of one or more DTS hunks + implementing this binding only. Example should not contain unrelated de= vice + nodes, e.g. consumer nodes in a provider binding, other nodes referenced= by + phandles or node labels which are not directly referenced in the example + itself. Phandles in the example do not have to be resolvable. The examp= le + must be complete as much as possible - have most of the properties - and= look + readable to developers, thus for example use known defines for interrupt= or + GPIO flags. Example should not contain 'status' property in typical case= s. + Note: YAML doesn't allow leading tabs, so spaces must be used instead. =20 Unless noted otherwise, all above schema properties are required. --=20 2.53.0