From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 716D5C77B75 for ; Tue, 16 May 2023 08:58:29 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=bombadil.20210309; h=Sender:Content-Type: List-Subscribe:List-Help:List-Post:List-Archive:List-Unsubscribe:List-Id: In-Reply-To:MIME-Version:References:Message-ID:Subject:CC:To:From:Date: Reply-To:Content-Transfer-Encoding:Content-ID:Content-Description:Resent-Date :Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Owner; bh=cUilTlREisgPb7WTIk/FDhP+GFkC0HmmlGAe+HcDNr0=; b=Z2L96l+UeWDE1GzOniuLL1Xv20 LvCV25xrxsQMe64JObtqX7UZlj9fqlkp9LreammJeedVEE+XcXcYb1GjgRU3nYmjE/VChLUWAhJGY hjtekXAyYklI3DrDW2re7Tk2dEHAHavWULEMbNB5CGkecxWCJG15+N2DMCulySLuBnygg/aSWhmqN a6xf1hLqxT18RsK+ohqoacsuWI19RnV+YMW7CcV0+cEq9D+er4iLMQO6i+pl0ETMldbrFjiPP4eIR 154o51RE9vLkrHOPeJNZZ3gZ5XVo4+9ObcuVH/GiSdIf3kYShI3H1M0pYzjhZdLJOyp1Jb9+YcSa8 u78WqDRQ==; Received: from localhost ([::1] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtp (Exim 4.96 #2 (Red Hat Linux)) id 1pyqVP-004xKL-2j; Tue, 16 May 2023 08:58:03 +0000 Received: from esa.microchip.iphmx.com ([68.232.154.123]) by bombadil.infradead.org with esmtps (Exim 4.96 #2 (Red Hat Linux)) id 1pyqVK-004xH3-2D; Tue, 16 May 2023 08:58:01 +0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=microchip.com; i=@microchip.com; q=dns/txt; s=mchp; t=1684227478; x=1715763478; h=date:from:to:cc:subject:message-id:references: mime-version:in-reply-to; bh=CSTRf/cqcWQ463WIW8qgz8myBeaHEA91KTcTMocyp20=; b=UGA2vCm6ip9BiQzIvmvMcELBEm/N7c8JvjKr8eQ8Qp652HK93Mv67c9M NO4Ma9bGw9wtFqEq8GMcHrxPV3Y7+9EqqcgbaOOufRS6T8xy6f7DDNIuh Bt/Tf9gnQmdai9YzilW4QNrTlRC0RmIVrO3nrEHCQVpyAWQc9lhcwdkNC PBAs05azcZQl9OjhsvnYgdukieqxy0jGO4/SvHh2N+coAjOaW80ClsAQl BE7uR8Ma6Q8uyhCnN5BBVxwF1rBwGDWKOOa5eI7uPpFuWq8he4/CddBKv tvA8zuDqOHGy8m4d6IXxjUKlai9MX0UDDiMiqwZQbGhsLY1Ff4pBWSZU0 g==; X-IronPort-AV: E=Sophos;i="5.99,278,1677567600"; d="asc'?scan'208";a="152279664" X-Amp-Result: UNKNOWN X-Amp-Original-Verdict: FILE UNKNOWN Received: from unknown (HELO email.microchip.com) ([170.129.1.10]) by esa6.microchip.iphmx.com with ESMTP/TLS/AES256-SHA256; 16 May 2023 01:57:52 -0700 Received: from chn-vm-ex03.mchp-main.com (10.10.85.151) by chn-vm-ex02.mchp-main.com (10.10.85.144) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2507.21; Tue, 16 May 2023 01:57:52 -0700 Received: from wendy (10.10.115.15) by chn-vm-ex03.mchp-main.com (10.10.85.151) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2507.21 via Frontend Transport; Tue, 16 May 2023 01:57:50 -0700 Date: Tue, 16 May 2023 09:57:29 +0100 From: Conor Dooley To: Krzysztof Kozlowski CC: Conor Dooley , , Arnd Bergmann , Rob Herring , Krzysztof Kozlowski , Conor Dooley , Jonathan Corbet , Olof Johansson , Palmer Dabbelt , , , , , Subject: Re: [PATCH v1] Documentation/process: add soc maintainer handbook Message-ID: <20230516-grader-dejected-df65cdc584b3@wendy> References: <20230515-geometry-olympics-b0556ff8a5f7@spud> MIME-Version: 1.0 In-Reply-To: X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20230516_015759_010894_7782A3FE X-CRM114-Status: GOOD ( 41.42 ) X-BeenThere: linux-arm-kernel@lists.infradead.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Content-Type: multipart/mixed; boundary="===============0125387512618571507==" Sender: "linux-arm-kernel" Errors-To: linux-arm-kernel-bounces+linux-arm-kernel=archiver.kernel.org@lists.infradead.org --===============0125387512618571507== Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="4AsXPhTNlfzE8BRW" Content-Disposition: inline --4AsXPhTNlfzE8BRW Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Tue, May 16, 2023 at 10:31:19AM +0200, Krzysztof Kozlowski wrote: > On 15/05/2023 21:20, Conor Dooley wrote: > > From: Conor Dooley > >=20 > > Arnd suggested that adding maintainer handbook for the SoC "subsystem" > > would be helpful in trying to bring on board maintainers for the various > > new platforms cropping up in RISC-V land. > >=20 > > Add a document briefly describing the role of the SoC subsystem and some > > basic advice for (new) platform maintainers. > >=20 > > Suggested-by: Arnd Bergmann > > Signed-off-by: Conor Dooley > > +devicetree ABI stability > > +~~~~~~~~~~~~~~~~~~~~~~~~ > > + > > +Perhaps one of the most important things to highlight is that dt-bindi= ngs > > +document the ABI between the devicetree and the kernel. Once dt-bindi= ngs have > > +been merged (and appear in a release of the kernel) they are set in st= one, and > > +any changes made must be compatible with existing devicetrees. This m= eans that, > > +when changing properties, a "new" kernel must still be able to handle = an old > > +devicetree. For many systems the devicetree is provided by firmware, = and > > +upgrading to a newer kernel cannot cause regressions. Ideally, the in= verse is > > +also true, and a new devicetree will also be compatible with an old ke= rnel, > > +although this is often not possible. >=20 > I would prefer to skip it and instead: enhance > Documentation/devicetree/bindings/ABI.rst and then reference it here. Sure. > > +Driver branch dependencies > > +~~~~~~~~~~~~~~~~~~~~~~~~~~ > > + > > +A common problem is synchronizing changes between device drivers and d= evicetree > > +files, even if a change is compatible in both directions, this may req= uire > > +coordinating how the changes get merged through different maintainer t= rees. > > + > > +Usually the branch that includes a driver change will also include the > > +corresponding change to the devicetree binding description, to ensure = they are > > +in fact compatible. This means that the devicetree branch can end up = causing > > +warnings in the "make dtbs_check" step. If a devicetree change depend= s on > > +missing additions to a header file in include/dt-bindings/, it will fa= il the > > +"make dtbs" step and not get merged. > > + > > +There are multiple ways to deal with this: > > + > > + - Avoid defining custom macros in include/dt-bindings/ for hardware c= onstants > > + that can be derived from a datasheet -- binding macros in header fi= le should > > + only be used as a last resort if there is no natural way to define = a binding > > + > > + - Use literal values in the devicetree file in place of macros even w= hen a > > + header is required, and change them to the named representation in a > > + following release >=20 > I actually prefer such solution: >=20 > - Duplicate defines in the devicetree file hidden by #ifndef section > and remove them later in a following release >=20 > We can keep both, but mine above leads to cleaner changes in DTS file. I think all of the options involved are either a bit ugly, or a bit of a pain in the hole. > > + - Defer the devicetree changes to a release after the binding and dri= ver have > > + already been merged > > + > > + - Change the bindings in a shared immutable branch that is used as th= e base for > > + both the driver change and the devicetree changes >=20 > The policy told to me some time ago was that no merges from driver > branch or tree are allowed towards DTS branch, even if they come only > with binding header change. There are exceptions for this, e.g. [1], but > that would mean we need to express here rules for cross-tree merges. I've got away with having an immutable branch for dt-binding headers! That said, Arnd did actually have a look at this (and suggested some changes) before I sent it & did not cry fowl about this section. IIRC, this is actually his wording, not mine. > > +Branches and Pull Requests > > +~~~~~~~~~~~~~~~~~~~~~~~~~~ > > +The subject line of a pull request should begin with "[GIT PULL]" and = made using > > +a tag, rather than a branch. This tag should contain a short descript= ion >=20 > a signed tag I initially had that explicit wording, but I dropped it when I added the ref to the pull requests doc since that talks about signing. It's probably better to be explicit & re-adding it is trivial. Thanks, Conor. --4AsXPhTNlfzE8BRW Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iHUEABYIAB0WIQRh246EGq/8RLhDjO14tDGHoIJi0gUCZGNFeQAKCRB4tDGHoIJi 0pVzAQDd5V7DgF90rg528xBUxStaRxmF6i407yxUeQeYhn6oLAEA3Y5P0rASKrya rg86ohacmT7OJLEcXa37wLmEIY0TnAI= =GTpg -----END PGP SIGNATURE----- --4AsXPhTNlfzE8BRW-- --===============0125387512618571507== Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline _______________________________________________ linux-arm-kernel mailing list linux-arm-kernel@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-arm-kernel --===============0125387512618571507==--