From nobody Sat Jul 25 00:59:18 2026 Received: from mx0b-0031df01.pphosted.com (mx0b-0031df01.pphosted.com [205.220.180.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 5B97A47A0A9 for ; Tue, 21 Jul 2026 10:30:38 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=205.220.180.131 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1784629839; cv=none; b=pPk1UeJj7sIfPudWmPXEO1Uqpz7Ev2TI5UfLlqrGrAFRzCOnUj5nnjGZ3VALj/96aHG5CBd4GYhi6oGIq/V1grk7xmQVBaI5DHQAmxXKX5yV7ucFLHgLoej7oq5Rh7KJPSO90eUbl3EgfSWjzOwXJz/epWRZOASn8mr3v4RdFmg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1784629839; c=relaxed/simple; bh=VXp3k0UXGtS2N774D+8ONtRUpSpEedS/ekIRBur6ZRs=; h=From:To:Cc:Subject:Date:Message-ID:MIME-Version; b=FR5np9Op6OpU6pU1xW8tsGYRrpZVDm2NQWmYQ2/CaLk0BFZ+lnaOR0HZpuVCAZ/lGhxHuAi0Hkjp5J8z8XO4BIhZltFc1ZX9edpc2WZ+vs+Uw+EQL7YdBwJgGtv4FevtAmDpSV0tUgFpQt2XtnOQgUVAricUZ7u988VMlOuSKH4= 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=GMZvn52p; dkim=pass (2048-bit key) header.d=oss.qualcomm.com header.i=@oss.qualcomm.com header.b=gCGPUQoc; arc=none smtp.client-ip=205.220.180.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="GMZvn52p"; dkim=pass (2048-bit key) header.d=oss.qualcomm.com header.i=@oss.qualcomm.com header.b="gCGPUQoc" Received: from pps.filterd (m0279872.ppops.net [127.0.0.1]) by mx0a-0031df01.pphosted.com (8.18.1.11/8.18.1.11) with ESMTP id 66LARutB1252097 for ; Tue, 21 Jul 2026 10:30:37 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=jtMUteilMGu16R/fI7SwZkhUF5xp6JcX/GI sEXTTNGE=; b=GMZvn52pNSCassQX2C8hvvGt7b8w9CFDtKYAtUzuL9xnkpgwiYL +CwDK1VA9s3aCvj3FERGWUXZNAWlTdhm2hNNEGWo/QD5DFCS6OA5ms9ChgvCjdO4 zNJWRUb3oiwN4NAP/ZUU1nk0NV9eKEWXngxs5b3iES6s7cRKkvv17vW9n9Fc38ZN yK4Ye7IQxukAYr/7Rnn3eJlab0AVbPm/cTo1iV9VXQRU4psZqkMiUauoLvrSn/1e +AjGhWojzGY8vZKhCYISPqoa48kELH3rBoFACJ+TumW5QLS0g6SjFkYJeFejL1Jf BwCBxdNYZ90aeXun3eeqsJSH7WW+OMeZjQw== 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 4fhqvcbxk6-1 (version=TLSv1.3 cipher=TLS_AES_128_GCM_SHA256 bits=128 verify=NOT) for ; Tue, 21 Jul 2026 10:30:37 +0000 (GMT) Received: by mail-qt1-f199.google.com with SMTP id d75a77b69052e-51c1a97644aso7223451cf.2 for ; Tue, 21 Jul 2026 03:30:37 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oss.qualcomm.com; s=google; t=1784629836; x=1785234636; 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=jtMUteilMGu16R/fI7SwZkhUF5xp6JcX/GIsEXTTNGE=; b=gCGPUQocHju+PPd833BkObUz8KlrPBRtJob9TBDvPoRHsJjRBl1oT4/pU405lBtI2H 31yfLbimuQauJcq0US26vMaUqMd3R8fn4LQBgluMTuuP191Ygu6kcr9ujofTX1YJ8Vw5 RFfPUtPRpA+VEpE5JdAke0uXpobicY6mI4skYPa/jLT/6gxF23OP+BYPKTyfFO8if9Mr +pwX7zAk0nYPhs28vjLQ0PFjqc1MnFTrI3NjwncpX1k8xb6M/NHH3gOS+s1LcCYmUALy X6lU+xwEofiPKSztoGoVYrInQzJMKDcr8KGYdD3HqjTxStoPHBBOJ8wNNWsGL+fY2PxV GM8Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1784629836; x=1785234636; 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=jtMUteilMGu16R/fI7SwZkhUF5xp6JcX/GIsEXTTNGE=; b=tHtFcyoo8e0CWxlNfriIcvYKWcOADK7HCwxokVp5cGbolsG+S7ITTGDDWfQjV5HSZG XlFOdnImuR7MqUc2lKnqVIBgmV1h5yFXBBxsD7HGWKVjopNRmwVqvgEigXFUz96QthWQ Q7cO2lgMYSe8EnQIFJL0hz1Y3DTsZNhPDFxBW1hjbuN1W265EUmCOPhrCF6OcnuuDwAa jeec7MCnOPliCNRPLN+BUxJBMlUc+yurLgKZyhtv8DhJ2+CCuTk5tvtrPYGtpl+reEzb f60LpS+OTQDUiAq7DoNPec8tW5asXk1KhUyJ/LDRf4DU6hvoE+rda7h5s5rIzXwRNPkQ 884w== X-Forwarded-Encrypted: i=1; AHgh+RpD2J5a3yZg9wS5ODyrUIU/jQ3PN8da9t/nUH9z4zYUUtlZSHt8ITrXGX3hbRBEpnLUkSgT1EPwm68Ql1Y=@vger.kernel.org X-Gm-Message-State: AOJu0Ywx7eAbxFDRm2VPDKTUxoBaGKJgq51DezNk7vPJExxJFZBwYnfl yYsk/By8eYm2+c47aDCiUdxi3NrcN+dlo78LXKcr+NMkr8Td8sR5hHM/9ijyoHXsYp8KtdtaYNG +vwzSPgDGqtgwTo2Wa9cGuDQaiFhEwcQgPrCDrKyL0TdSGsZtTB/diOYy1ylpA5qzFkg8AHUNJO Q= X-Gm-Gg: AfdE7cmMahthY6GDykwrSNVgZrXUkln4BQWbGBc1LV3cQqbpU6yUepol304IU9EgkGt mQ1jk3veJei7WflCnT9cqHij/VD+Rew7mtkypmE8NG/0yNivoc08AExq6AagoGccs77u+knGa+V JUgW83QSpwNw74l1lWJFOAQpkBlpJFuVMln0O3/qiIOM2XLQaBSI5lk+850CbiVgDyh/k1pSlKs YafSWajaofhPmSMxmiwC+rXYamHsjCH6+VnoQUe1heg1U4X91bxcPQJ9ChC80QQ19dukRZovTG7 jFWzfc+H6lbrzhvgaHg2tSBlf5j721zEkZHXsLslAVdv84LiWZuFbPGFopwbj9V474q1UvqZQUn 0g3Zw+RogvixHEMLu X-Received: by 2002:a05:622a:909:b0:51c:99b:d668 with SMTP id d75a77b69052e-5213e28f16dmr176176861cf.49.1784629836486; Tue, 21 Jul 2026 03:30:36 -0700 (PDT) X-Received: by 2002:a05:622a:909:b0:51c:99b:d668 with SMTP id d75a77b69052e-5213e28f16dmr176176671cf.49.1784629836035; Tue, 21 Jul 2026 03:30:36 -0700 (PDT) Received: from quoll ([178.197.223.174]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4956546de4fsm60985945e9.1.2026.07.21.03.30.34 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 21 Jul 2026 03:30:35 -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] docs: dt: writing-schema: Extend expectations about example part of binding Date: Tue, 21 Jul 2026 12:30:32 +0200 Message-ID: <20260721103031.82188-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=2038; i=krzysztof.kozlowski@oss.qualcomm.com; h=from:subject; bh=VXp3k0UXGtS2N774D+8ONtRUpSpEedS/ekIRBur6ZRs=; b=owEBbQKS/ZANAwAKAcE3ZuaGi4PXAcsmYgBqX0pHkve/+xqHHTTD2HdrWaQKC6N/d//LaQnV9 BZb3PkTbuuJAjMEAAEKAB0WIQTd0mIoPREbIztuuKjBN2bmhouD1wUCal9KRwAKCRDBN2bmhouD 1wwvEACPF56K6PzBBwDigmC6CoX5DB/xE4b+zLdKsT/PZmYRTC2NTPT0bOnajOsTJ7O2v6PLZlT wHNUXyc+lROl+CLv9l3SQ+eN4Cg81DxJ7mvCAo6xxTq1pzDIKyhnahvNr6TgNU2ZRzmxTFHqSyA gtGGx6zweexs7Q8DH2KefOm/fJ+PPG4W4wZns1pjebqO80MxpAR5mzila0VMuyoo+J8y84U7BvI PG6hJBzc/8q/ylJ9HcS/lJdfPEMkkGh1DvlIfyT3Ojs2Vbk6eDxsyCEKQV1+GodyEuLNM/SC7zp R8s5H3kE9f8BPfpeUXuOR9zW26OK81rYIlhygvjKOPmCvfw2hT1CCNe8inn79G9T8l9vSP9fsg1 5K5QKyqtqRexA/OFmqJwKT//6D7sixt/pWQH2t0uyMuIRNz0M0qJairSb2S3uT73B/nq/fyLVsZ JlN08wOnFeoMEuxcrC8lDGv5GVglVzKifXVMYd3I3xjHQa0UFpZ0fjcnH+o1CezHKT3toAJ0dax xx9CRnPJ3FLBOjDQihwxJFrn3lMGd60CN7hT7KJOvcg+kxCHpavyDlIYav9W5h71cI2R003lmQz HPLVs4ArOTg0d0FK5JU5QSXUBIDZ8h+AGvPTvNJvU5GPeCbnnD5PrC1C4TFBeGH19xhRGcdt7Pe u8WxrQuvKmp3gzA== X-Developer-Key: i=krzysztof.kozlowski@oss.qualcomm.com; a=openpgp; fpr=9BD07E0E0C51F8D59677B7541B93437D3B41629B Content-Transfer-Encoding: quoted-printable X-Proofpoint-Spam-Info: AW1haW4tMjYwNzIxMDExMCBTYWx0ZWRfX55ap/CpSBOI9 HH6d3A4c6qMVgaHHJBeqqsCX1kvV83L1Z9K2m1+P4n2CoXluUbzCWQkwtDPbaIcjL1nTQEutdoe e6URj01R33IZWT+DSegQeyBNOAPmq34= X-Proofpoint-GUID: wngVq6BQeQCoN1kOH2RG8uWNI1TUO27y X-Authority-Analysis: v=2.4 cv=OMYXGyaB c=1 sm=1 tr=0 ts=6a5f4a4d 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=yx91gb_oNiZeI1HMLzn7:22 a=EUspDBNiAAAA:8 a=e1H8DJF7dWPT80t_t4YA:9 a=kacYvNCVWA4VmyqE58fU:22 X-Proofpoint-ORIG-GUID: wngVq6BQeQCoN1kOH2RG8uWNI1TUO27y X-Proofpoint-Spam-Details-Enc: AW1haW4tMjYwNzIxMDExMCBTYWx0ZWRfXxypwU31cEPbf Qwydh0pHD2Vslfvo+P5vQBqRai0sM3tVWIJ1vpomgm4o09zW6Wg9AwLN01+4f2xMhtzAgs7aVP0 xP1eZN2KCjf7bF5frlvGR/0IDz5QyYHjbZvn4KswXCKTDH5kl16C01bAe16b65GZNWqTj42Z12q 7KPEUG55oK1KSzay0a8PI1b//wcDp/jsjpbdQ3gytms++Dt0vbpmlrRpGZB+n227xKkD4QbblSe idTDVBnjNTeRD+yKcIeeYtpOMn+IQ6A1207GOP4E3GK294UHDuC2bAT4oP0a9M6YYWas50yRaKK 0GnVHFMmGsmCZFSbdN8XGJUXWvc4CPt/gApJUfc9PhZjtc/DU06PeoEkGITlby79SrlgbtMR1PY vJrbDmTBkE1u100pXdYg6P5YuwQygzpm4YK3ES7z7SIw0yNtZQ7WeJPBrkh+273y0J6OfPZTI18 PvFq4frrKZCumy4IwYg== 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-21_01,2026-07-20_03,2025-10-01_01 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 spamscore=0 adultscore=0 priorityscore=1501 suspectscore=0 lowpriorityscore=0 bulkscore=0 malwarescore=0 clxscore=1015 impostorscore=0 phishscore=0 classifier=typeunknown authscore=0 authtc= authcc= route=outbound adjust=0 reason=mlx scancount=1 engine=8.22.0-2606150000 definitions=main-2607210110 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 --- .../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..0f665b13c126 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 in every device binding. A list of one or mo= re + DTS hunks implementing this binding only. Example should not contain + unrelated device nodes, e.g. consumer nodes in a provider binding, other + nodes referenced by phandles or node labels which are not directly refer= enced + in the example itself. Phandles in the example do not have to be resolva= ble. + The example 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 normal cases. + 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