From patchwork Tue Dec 17 16:59:40 2013 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jason Cooper X-Patchwork-Id: 302295 Return-Path: X-Original-To: incoming-dt@patchwork.ozlabs.org Delivered-To: patchwork-incoming-dt@bilbo.ozlabs.org Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by ozlabs.org (Postfix) with ESMTP id D65982C0084 for ; Wed, 18 Dec 2013 03:59:58 +1100 (EST) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752452Ab3LQQ75 (ORCPT ); Tue, 17 Dec 2013 11:59:57 -0500 Received: from mho-03-ewr.mailhop.org ([204.13.248.66]:37314 "EHLO mho-01-ewr.mailhop.org" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1751279Ab3LQQ75 (ORCPT ); Tue, 17 Dec 2013 11:59:57 -0500 Received: from pool-108-39-110-144.nrflva.fios.verizon.net ([108.39.110.144] helo=titan) by mho-01-ewr.mailhop.org with esmtpsa (TLSv1:AES256-SHA:256) (Exim 4.72) (envelope-from ) id 1Vsxzs-000LU2-SF; Tue, 17 Dec 2013 16:59:53 +0000 Received: from triton.localdomain (triton.lakedaemon.net [10.16.5.78]) by titan (Postfix) with ESMTP id E67104F4FE4; Tue, 17 Dec 2013 11:59:49 -0500 (EST) X-Mail-Handler: Dyn Standard SMTP by Dyn X-Originating-IP: 108.39.110.144 X-Report-Abuse-To: abuse@dyndns.com (see http://www.dyndns.com/services/sendlabs/outbound_abuse.html for abuse reporting information) X-MHO-User: U2FsdGVkX18dleVKlxHPIiaooWty7Z8ZI2KsXsNHyHM= X-DKIM: OpenDKIM Filter v2.0.1 titan E67104F4FE4 From: Jason Cooper To: Rob Herring , Grant Likely , Pawel Moll , Mark Rutland , Stephen Warren , Ian Campbell , Rob Landley Cc: Jason Cooper , devicetree@vger.kernel.org Subject: [PATCH V2] dt: bindings: submitting patches and ABI documents Date: Tue, 17 Dec 2013 16:59:40 +0000 Message-Id: <1387299580-9100-1-git-send-email-jason@lakedaemon.net> X-Mailer: git-send-email 1.8.5.1 In-Reply-To: <1383759120-21571-1-git-send-email-jason@lakedaemon.net> References: <1383759120-21571-1-git-send-email-jason@lakedaemon.net> Sender: devicetree-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: devicetree@vger.kernel.org Signed-off-by: Jason Cooper --- Changes from RFC: - incorporated Grant's language - split patches/ABI into two documents Documentation/devicetree/bindings/ABI.txt | 39 ++++++++++++++++++++++ .../devicetree/bindings/submitting-patches.txt | 35 +++++++++++++++++++ 2 files changed, 74 insertions(+) create mode 100644 Documentation/devicetree/bindings/ABI.txt create mode 100644 Documentation/devicetree/bindings/submitting-patches.txt diff --git a/Documentation/devicetree/bindings/ABI.txt b/Documentation/devicetree/bindings/ABI.txt new file mode 100644 index 000000000000..d25f8d379680 --- /dev/null +++ b/Documentation/devicetree/bindings/ABI.txt @@ -0,0 +1,39 @@ + + Devicetree (DT) ABI + +I. Regarding stable bindings/ABI, we quote from the 2013 ARM mini-summit + summary document: + + "That still leaves the question of, what does a stable binding look + like? Certainly a stable binding means that a newer kernel will not + break on an older device tree, but that doesn't mean the binding is + frozen for all time. Grant said there are ways to change bindings that + don't result in breakage. For instance, if a new property is added, + then default to the previous behaviour if it is missing. If a binding + truly needs an incompatible change, then change the compatible string + at the same time. The driver can bind against both the old and the + new. These guidelines aren't new, but they desperately need to be + documented." + +II. General binding rules + + 1) Maintainers, don't let perfect be the enemy of good. Don't hold up a + binding because it isn't perfect. + + 2) Use specific compatible strings so that if we need to add a feature (DMA) + in the future, we can create a new compatible string. See I. + + 3) Bindings can be augmented, but the driver shouldn't break when given + the old binding. ie. add additional properties, but don't change the + meaning of an existing property. For drivers, default to the original + behaviour when a newly added property is missing. + + 4) Don't submit bindings for staging or unstable. That will be decided by + the devicetree maintainers *after* discussion on the mailinglist. + +III. Notes + + 1) This document is intended as a general familiarization with the process as + decided at the 2013 Kernel Summit. When in doubt, the current word of the + devicetree maintainers overrules this document. In that situation, a patch + updating this document would be appreciated. diff --git a/Documentation/devicetree/bindings/submitting-patches.txt b/Documentation/devicetree/bindings/submitting-patches.txt new file mode 100644 index 000000000000..5672cb46681d --- /dev/null +++ b/Documentation/devicetree/bindings/submitting-patches.txt @@ -0,0 +1,35 @@ + + Submitting devicetree (DT) binding patches + +I. For patch submitters + + 0) Normal patch submission rules from Documentation/SubmittingPatches + applies. + + 1) The Documentation/ portion of the patch should be a separate patch. + + 2) Submit the entire series to the devicetree mailinglist at + + devicetree@vger.kernel.org + +II. For kernel maintainers + + 1) If you aren't comfortable reviewing a given binding, reply to it and ask + the devicetree maintainers for guidance. This will help them prioritize + which ones to review and which ones are ok to let go. + + 2) For driver (not subsystem) bindings: If you are comfortable with the + binding, and it hasn't received an Acked-by from the devicetree + maintainers after a few weeks, go ahead and take it. + + 3) For a series going though multiple trees, the binding patch should be + kept with the driver using the binding. + +III. Notes + + 0) Please see ...bindings/ABI.txt for details regarding devicetree ABI. + + 1) This document is intended as a general familiarization with the process as + decided at the 2013 Kernel Summit. When in doubt, the current word of the + devicetree maintainers overrules this document. In that situation, a patch + updating this document would be appreciated.