Received: by 2002:ac0:aa62:0:0:0:0:0 with SMTP id w31-v6csp2448449ima; Mon, 22 Oct 2018 09:55:02 -0700 (PDT) X-Google-Smtp-Source: ACcGV63Ghk8zhIhttrQJ1Y3LNX43qPaMTjJbnM30Np56R5KiAyrLuymRqaFoiiASqMgzWF+nfj0f X-Received: by 2002:a63:145f:: with SMTP id 31-v6mr42555783pgu.35.1540227302483; Mon, 22 Oct 2018 09:55:02 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1540227302; cv=none; d=google.com; s=arc-20160816; b=u8VQ2I/Xea9BOQcmunTv/NSNQ5TVSk58zJZn9u1z7sMTda5YZJ4JaEl+1DEZps/wgA P9APNbhwg0xnmdrwGeDZJpDU/RHsJc7KzIpYd8ijmcaqRzlNHKrfBzP9JNnmXStsskWI Fqqd7OA3lDkBZkc/gx4JQC7rciVp2JZ1zS298aL/Ckb2aLokmJIdXf2Pqdi8m73Mtetc I3FOnGIumicNo6uhxsKrAJ8tBB/mY9+6ZiR6AE8QVLgY5YloFHxiNGVGcEUvtVaB9Mbz CNWznJXqCwsEvoRJyIrwcOS4/zDZitVSeLdwXEunaPUwaPx06EUoSkOWoeR3H/8VQeYq C7iA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:content-transfer-encoding:mime-version :message-id:to:from:cc:in-reply-to:subject:date:dkim-signature; bh=ou0XepXjkzvDYW0kG4OS6ZSNPTOhZGtmWZRLSrbu6ds=; b=e9M2QrvlMAtq1Fy592ZL/q1GEnW60Wi3Cq6mREutHuuX+8wUCR3ySEdHr/+EU1Xf+A LlRtE3SbwaOtJyJ7sZ7rTYIYJ3bEPMqCYZS1c4RqB4ljfNF9wsfkdPEMukuQMHpjiL7J nHwX9aq9IgYmFxmhU3dKAq5RcNg9vca5KasymGo4V9GVKYFQtDfbjlbtNAmyNYbOFT07 AigeSVUH9fYM6YRq2BEMakKRbkZiiTrhN5wIPONbcPl9PkegA7MWKxlp0wN2yTQWkncg OJioOW81Eu+aviUNeJS4fygvuqgvHxM7g8KicHq31lRsKmqwhzpmAsTK6aPPN2FOk8v9 uq5Q== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@sifive.com header.s=google header.b=SyuSQPT+; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id f34-v6si34884950plf.161.2018.10.22.09.54.47; Mon, 22 Oct 2018 09:55:02 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; dkim=pass header.i=@sifive.com header.s=google header.b=SyuSQPT+; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1728478AbeJWBBM (ORCPT + 99 others); Mon, 22 Oct 2018 21:01:12 -0400 Received: from mail-pl1-f193.google.com ([209.85.214.193]:44409 "EHLO mail-pl1-f193.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727943AbeJWBBM (ORCPT ); Mon, 22 Oct 2018 21:01:12 -0400 Received: by mail-pl1-f193.google.com with SMTP id d23-v6so5889207pls.11 for ; Mon, 22 Oct 2018 09:41:57 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sifive.com; s=google; h=date:subject:in-reply-to:cc:from:to:message-id:mime-version :content-transfer-encoding; bh=ou0XepXjkzvDYW0kG4OS6ZSNPTOhZGtmWZRLSrbu6ds=; b=SyuSQPT+39l7kciaLFcqZczw1tlXekOARqgLBXoAeZCRDysrARiEAyQG66+p95TIXv 689M8DdtzvyxrvrlbZLtalmBFKT4k7iU03uXG+nRl2ssRy6a8Uj3NHDq6kQ3m8+8w/rq 3fn5CPDWebee/n/3x+O0DVzBRWrVeCMqm3rn2HNdxcGcZqTEqNODTjI7c4smksLhwDOd VVriGRFLcuBXTECQUG42O4gncmDfesEh2BOLwG3qzysX1z3352AL9KSE088fM1SKVsGo 7FRDc3uzpHwwJGfK9gpL5st2WXeKTnoNwEIRzPBTVOgyzg2PO2kXpnX9lfxLCN34mWKd bQUQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:subject:in-reply-to:cc:from:to:message-id :mime-version:content-transfer-encoding; bh=ou0XepXjkzvDYW0kG4OS6ZSNPTOhZGtmWZRLSrbu6ds=; b=TBaXLccxJTleCV9Gqg80iVKYXCInH/0XNcU+Z6n/8ty7OZ/hrFUb8IXfZjgVfsualp XFmI7xDUqWhYvtEIDGyZ34gkRCuH3JWaOVq6jlffrdBTMEALI7YW3O5T5uSSSpntRmZL KzJFH0okrL1vHl0j40rBnsklw7vZ9PDVbxFlMWLHIZPNzI2pKjRT2B62JjRpNU6Alunm HvwelY6EenPCxM43XLL6mSeinimhm2Uo72MDoUndll6txpVOX3KRfIW9eL1UdBKtyPwt Oo+KEEInCPUmI9sUjwbMvfp+fUWL7ckqnRpBKAsdxYvkLlqoYFqUaBwiXd7UDW82NWWZ lTLw== X-Gm-Message-State: ABuFfohqWg4OMTRXlk6ld9qkzwXVxDWtRTaclnAm5/U6CPoGTb6Sga/7 z5diP4qPe7jUxnhYfhiUtnHUYQ== X-Received: by 2002:a17:902:507:: with SMTP id 7-v6mr35686908plf.272.1540226512597; Mon, 22 Oct 2018 09:41:52 -0700 (PDT) Received: from localhost ([12.206.222.5]) by smtp.gmail.com with ESMTPSA id x19-v6sm4120148pga.15.2018.10.22.09.41.51 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Mon, 22 Oct 2018 09:41:51 -0700 (PDT) Date: Mon, 22 Oct 2018 09:41:51 -0700 (PDT) X-Google-Original-Date: Mon, 22 Oct 2018 09:31:29 PDT (-0700) Subject: Re: [PATCH v2 1/2] dt-bindings: serial: add documentation for the SiFive UART driver In-Reply-To: CC: Paul Walmsley , linux-serial@vger.kernel.org, devicetree@vger.kernel.org, linux-riscv@lists.infradead.org, linux-kernel@vger.kernel.org, Greg KH , mark.rutland@arm.com, paul@pwsan.com From: Palmer Dabbelt To: robh+dt@kernel.org Message-ID: Mime-Version: 1.0 (MHng) Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 8bit Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Fri, 19 Oct 2018 13:45:57 PDT (-0700), robh+dt@kernel.org wrote: > On Fri, Oct 19, 2018 at 1:48 PM Paul Walmsley wrote: >> >> Add DT binding documentation for the Linux driver for the SiFive >> asynchronous serial IP block. Nothing too exotic. >> >> Cc: linux-serial@vger.kernel.org >> Cc: devicetree@vger.kernel.org >> Cc: linux-riscv@lists.infradead.org >> Cc: linux-kernel@vger.kernel.org >> Cc: Greg Kroah-Hartman >> Cc: Rob Herring >> Cc: Mark Rutland >> Cc: Palmer Dabbelt >> Reviewed-by: Palmer Dabbelt >> Signed-off-by: Paul Walmsley >> Signed-off-by: Paul Walmsley >> --- >> .../bindings/serial/sifive-serial.txt | 21 +++++++++++++++++++ >> 1 file changed, 21 insertions(+) >> create mode 100644 Documentation/devicetree/bindings/serial/sifive-serial.txt >> >> diff --git a/Documentation/devicetree/bindings/serial/sifive-serial.txt b/Documentation/devicetree/bindings/serial/sifive-serial.txt >> new file mode 100644 >> index 000000000000..8982338512f5 >> --- /dev/null >> +++ b/Documentation/devicetree/bindings/serial/sifive-serial.txt >> @@ -0,0 +1,21 @@ >> +SiFive asynchronous serial interface (UART) >> + >> +Required properties: >> + >> +- compatible: should be "sifive,fu540-c000-uart0" or "sifive,uart0" > > I assume once again, the last '0' is a version? As I mentioned for the > intc and now the pwm block bindings, if you are going to do version > numbers please document the versioning scheme. Palmer mentioned the > compatible string is part of the IP block repository? Where does the > number come from? What's the next version? Major vs. minor versions? > ECO fixes? Is the version s/w readable? How do you ensure it gets > updated? All that should be addressed. The RISC-V ecosystem is a bit different than that of ARM, MIPS, or Intel in that the ISA is an royalty-free open standard that anyone can implement (ie, without even signing a license agreement), with only the "RISC-V" trademark being held behind a pay+conformance wall. As a result, we don't actually have any control over who builds a RISC-V chip so all we at SiFive can really to is try to demonstrate good practices in software land and go from there. As far as SiFive's codebase is concerned, the version number is embedded in the RTL generator, and a device tree is generated along with the RTL. This device tree is then embedded into a mask ROM on the chip, which allows the earliest stage of boot to proceed. As I'm sure you know, boot is a very complicated process and as a result the device tree passed to Linux doesn't necessarily look like what's in the ROM, but the intent is to keep iterating until we can get these as similar as possible -- that's why we're submitting every devicetree binding to the standard. Specifically as far as the UART is concerned, the compat string that's not chip-specific lives here (the "sifive,fu540-c000-uart" string lives in an internal chip repo that I can't point to): https://github.com/sifive/sifive-blocks/blob/master/src/main/scala/devices/uart/UART.scala#L43 The version numbering scheme right now is pretty simple: I try to pay as much attention as possible to how the hardware changes (both by looking and with some automation), and I go yell at anyone who does something stupid. I know it's not the most scalable of schemes, but it's the best we have. The UART is actually an interesting case right now because we have an outstanding pull request that adds a bit to the UART and then adds "sifive,uart1" to the compat string https://github.com/sifive/sifive-blocks/pull/90 My intent is to ensure that the device tree's compat string uniquely identifies the software interface to a block. Thus, whenever a device's implementation changes in a software-visible way (bug fix or feature addition) we change the compat string -- either adding one (as is the case of the UART, where the compat string will be both "sifive,uart1" and "sifive,uart0" since the new feature is backwards compatible with the old software) or changing one (if the interface change is not compatible with old software). Like I said above, this is all a manual process right now and this only applies to SiFive's implementations. I'm confident that I can at least ensure that, for any given SiFive implementation, a block's compat string will uniquely identify the software interface to it. For the rest of the RISC-V world all we can do is set a good example and review the software. > Otherwise, don't do version numbers because we have no visibility to > what they mean. > >> +- reg: address and length of the register space >> +- interrupt-parent: should contain a phandle pointing to the SoC interrupt >> + controller device node that the UART interrupts are connected to > > Don't need to document interrupt-parent here. > >> +- interrupts: Should contain the UART interrupt identifier >> +- clocks: Should contain a clock identifier for the UART's parent clock >> + >> + >> +Example: >> + >> +uart0: serial@10010000 { >> + compatible = "sifive,uart0"; >> + interrupt-parent = <&plic0>; >> + interrupts = <80>; >> + reg = <0x0 0x10010000 0x0 0x1000>; >> + clocks = <&prci PRCI_CLK_TLCLK>; >> +}; >> -- >> 2.19.1 >>