From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1161203AbbENU0v (ORCPT ); Thu, 14 May 2015 16:26:51 -0400 Received: from mail-ob0-f182.google.com ([209.85.214.182]:33562 "EHLO mail-ob0-f182.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1161164AbbENU0n (ORCPT ); Thu, 14 May 2015 16:26:43 -0400 MIME-Version: 1.0 In-Reply-To: <5554DF5E.4020802@wwwdotorg.org> References: <1431624773-4165-1-git-send-email-computersforpeace@gmail.com> <5554DF5E.4020802@wwwdotorg.org> Date: Thu, 14 May 2015 22:26:41 +0200 X-Google-Sender-Auth: fAvhGLkp6KM8pGZTIHvtNYP2FyY Message-ID: Subject: Re: [PATCH] Documentation: dt: mtd: replace "nor-jedec" binding with "jedec,spi-nor" From: Geert Uytterhoeven To: Brian Norris Cc: Stephen Warren , Rob Herring , Pawel Moll , Mark Rutland , Ian Campbell , Kumar Gala , MTD Maling List , "devicetree@vger.kernel.org" , "linux-kernel@vger.kernel.org" , Marek Vasut , =?UTF-8?B?UmFmYcWCIE1pxYJlY2tp?= Content-Type: text/plain; charset=UTF-8 Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Thu, May 14, 2015 at 7:46 PM, Stephen Warren wrote: > On 05/14/2015 11:32 AM, Brian Norris wrote: >> In commit 8ff16cf77ce3 ("Documentation: devicetree: m25p80: add >> "nor-jedec" >> binding"), we added a generic "nor-jedec" binding to catch all >> mostly-compatible SPI NOR flash which can be detected via the READ ID >> opcode (0x9F). This was discussed and reviewed at the time, however >> objections have come up since then as part of this discussion: >> >> http://lkml.kernel.org/g/20150511224646.GJ32500@ld-irv-0074 >> >> It seems the parties involved agree that "jedec,spi-nor" does a better >> job of capturing the fact that this is SPI-specific, not just any NOR >> flash. >> >> This binding was only merged for v4.1-rc1, so it's still OK to change >> the naming. >> >> At the same time, let's move the documentation to a better name. >> >> Next up: prune the m25p_ids[] table to the minimal necessary listing, so >> we can stop referring to code (drivers/mtd/devices/m25p80.c) from the >> documentation. > > There's no need to change the code to update the documentation. Simply paste > the list of valid device IDs into the documentation. The binding > documentation needs to be completely standalone anyway. Binding > documentation should never refer to Linux driver code as part of their > definition. > > You can never remove the currently-supported device-specific IDs from the > driver, since existing DTs need to continue working forever, even with > future drivers/kernels. > > The binding document should also always include a complete list of supported > flash devices. Standard practice is that the DT compatible property contains > a list of compatible values, starting with the device-specific value, and > followed by any generic values. All of those values should be standardized > and specified in the DT documentation, even if the DT binding is written in > such a way that a compliant driver need only actively match on the generic > value. The device-specific values may not be used today, but are present in > case some device-specific workaround needs to be retro-actively > implemented/enabled, since that needs to happen for existing DTs too. Indeed, all supported flash devices should be listed in the DT binding documentation, so checkpatch can validate dts changes: $ scripts/checkpatch.pl -f arch/arm/boot/dts/r8a7791-koelsch.dts [...] WARNING: DT compatible string "spansion,s25fl512s" appears un-documented -- check ./Documentation/devicetree/bindings/ #493: FILE: arch/arm/boot/dts/r8a7791-koelsch.dts:493: + compatible = "spansion,s25fl512s", "nor-jedec"; >> I'd *really* like to get an 'ack' from a DT maintainer for this, those >> those >> are apparently very hard to come by. And I'd really not like to have to >> revisit >> this again in a few weeks. We have patches getting queued up for 4.2 that >> are >> using the "nor-jedec" binding, and I'd like to nip those in the bud ASAP. > > > I am not a DT maintainer, but the DT documentation part of this change: > Acked-by: Stephen Warren Likewise, Acked-by: Geert Uytterhoeven Gr{oetje,eeting}s, Geert -- Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org In personal conversations with technical people, I call myself a hacker. But when I'm talking to journalists I just say "programmer" or something like that. -- Linus Torvalds From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-ob0-x236.google.com ([2607:f8b0:4003:c01::236]) by bombadil.infradead.org with esmtps (Exim 4.80.1 #2 (Red Hat Linux)) id 1Yszih-0002rf-8b for linux-mtd@lists.infradead.org; Thu, 14 May 2015 20:27:04 +0000 Received: by obcus9 with SMTP id us9so61732293obc.2 for ; Thu, 14 May 2015 13:26:42 -0700 (PDT) MIME-Version: 1.0 Sender: geert.uytterhoeven@gmail.com In-Reply-To: <5554DF5E.4020802@wwwdotorg.org> References: <1431624773-4165-1-git-send-email-computersforpeace@gmail.com> <5554DF5E.4020802@wwwdotorg.org> Date: Thu, 14 May 2015 22:26:41 +0200 Message-ID: Subject: Re: [PATCH] Documentation: dt: mtd: replace "nor-jedec" binding with "jedec, spi-nor" From: Geert Uytterhoeven To: Brian Norris Content-Type: text/plain; charset=UTF-8 Cc: Mark Rutland , "devicetree@vger.kernel.org" , Marek Vasut , Pawel Moll , Ian Campbell , Stephen Warren , "linux-kernel@vger.kernel.org" , Rob Herring , MTD Maling List , =?UTF-8?B?UmFmYcWCIE1pxYJlY2tp?= , Kumar Gala List-Id: Linux MTD discussion mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , On Thu, May 14, 2015 at 7:46 PM, Stephen Warren wrote: > On 05/14/2015 11:32 AM, Brian Norris wrote: >> In commit 8ff16cf77ce3 ("Documentation: devicetree: m25p80: add >> "nor-jedec" >> binding"), we added a generic "nor-jedec" binding to catch all >> mostly-compatible SPI NOR flash which can be detected via the READ ID >> opcode (0x9F). This was discussed and reviewed at the time, however >> objections have come up since then as part of this discussion: >> >> http://lkml.kernel.org/g/20150511224646.GJ32500@ld-irv-0074 >> >> It seems the parties involved agree that "jedec,spi-nor" does a better >> job of capturing the fact that this is SPI-specific, not just any NOR >> flash. >> >> This binding was only merged for v4.1-rc1, so it's still OK to change >> the naming. >> >> At the same time, let's move the documentation to a better name. >> >> Next up: prune the m25p_ids[] table to the minimal necessary listing, so >> we can stop referring to code (drivers/mtd/devices/m25p80.c) from the >> documentation. > > There's no need to change the code to update the documentation. Simply paste > the list of valid device IDs into the documentation. The binding > documentation needs to be completely standalone anyway. Binding > documentation should never refer to Linux driver code as part of their > definition. > > You can never remove the currently-supported device-specific IDs from the > driver, since existing DTs need to continue working forever, even with > future drivers/kernels. > > The binding document should also always include a complete list of supported > flash devices. Standard practice is that the DT compatible property contains > a list of compatible values, starting with the device-specific value, and > followed by any generic values. All of those values should be standardized > and specified in the DT documentation, even if the DT binding is written in > such a way that a compliant driver need only actively match on the generic > value. The device-specific values may not be used today, but are present in > case some device-specific workaround needs to be retro-actively > implemented/enabled, since that needs to happen for existing DTs too. Indeed, all supported flash devices should be listed in the DT binding documentation, so checkpatch can validate dts changes: $ scripts/checkpatch.pl -f arch/arm/boot/dts/r8a7791-koelsch.dts [...] WARNING: DT compatible string "spansion,s25fl512s" appears un-documented -- check ./Documentation/devicetree/bindings/ #493: FILE: arch/arm/boot/dts/r8a7791-koelsch.dts:493: + compatible = "spansion,s25fl512s", "nor-jedec"; >> I'd *really* like to get an 'ack' from a DT maintainer for this, those >> those >> are apparently very hard to come by. And I'd really not like to have to >> revisit >> this again in a few weeks. We have patches getting queued up for 4.2 that >> are >> using the "nor-jedec" binding, and I'd like to nip those in the bud ASAP. > > > I am not a DT maintainer, but the DT documentation part of this change: > Acked-by: Stephen Warren Likewise, Acked-by: Geert Uytterhoeven Gr{oetje,eeting}s, Geert -- Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org In personal conversations with technical people, I call myself a hacker. But when I'm talking to journalists I just say "programmer" or something like that. -- Linus Torvalds