Received: by 2002:a05:6358:3188:b0:123:57c1:9b43 with SMTP id q8csp7433662rwd; Tue, 20 Jun 2023 00:53:11 -0700 (PDT) X-Google-Smtp-Source: ACHHUZ7jsMUxpQSRGigVhjMcvFRcepGL9ZGt1y2wT9uP9JuXfuOPYQdQPrCnyxU0pmBswRopVrzs X-Received: by 2002:a17:90b:8d3:b0:25e:abf2:a149 with SMTP id ds19-20020a17090b08d300b0025eabf2a149mr8178257pjb.18.1687247591082; Tue, 20 Jun 2023 00:53:11 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1687247591; cv=none; d=google.com; s=arc-20160816; b=VNn8OcN6dSm7FS7wY04VVSP2nn4pNlfCRV4YAVKEq2ILlK3RZnNTyDevPVm1u4fNhw rYBjUuajOWTUsZIo1507U3dG2tqH26tKoXrzxS5i4iE2sQeyOIijUl6Qul6F8n71Iz+s F/MezZNGtTrDBFd3RIObMAt3dNkYOuHz8QbIu2ASzDgdjE7TNcDJ19k9NDxK+1uw6LJx uRG0EEI52cWRaBewR17RoUXMaE9IYdIiH/ISfEKG0N5SCpFBYCN0H8fL2yqAgMXgcy2c wemBdonLTYJqCU4aDgs3VEHqIVUlI927/2M7AHz85v8A1PcnByJ1utwg8RlRQLy8/b5t gxpg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:in-reply-to:content-transfer-encoding :content-disposition:mime-version:references:message-id:subject:cc :to:from:date:dkim-signature; bh=VNlkE9w8+4f9Owz1VR7DDy4a4R4dy/xTsJ/TjLKMtek=; b=tzyblt3xdRBxog5EduLigB++wbWboXorwfPWdjuJnFqfKrHTBllpI3nAgJYCk7YxG+ lcgxYn74Srsg9JCsz6d0yK7fUpY2e+kWdHR0YFnhsWo8w8OudvgD/D/gg9nTKPrxcPmI kvgtUJf7xfIj8yKaxE2SrReMHg7+Y4UOllv+y/4hOA62dzZIGKjNT/rNQxQ3shniAyGH X0w4NqwtNtOwsRvhoOxvCdcZyjuETTvzkU4rnMFDApOa8E1iem9ojsgp3FmrYoI4KRs+ 2MpkytMCcZNYR6VRza/eDaXrK3MhaC/Q+BykonNgREy1n5ZWYjUCO7KJ+het/5WP+HR9 eVbQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@ventanamicro.com header.s=google header.b=bIFBmbK7; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id b5-20020a63eb45000000b0053b8c98d14bsi1156138pgk.859.2023.06.20.00.52.58; Tue, 20 Jun 2023 00:53:11 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@ventanamicro.com header.s=google header.b=bIFBmbK7; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231438AbjFTHmU (ORCPT + 99 others); Tue, 20 Jun 2023 03:42:20 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:41606 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231322AbjFTHl6 (ORCPT ); Tue, 20 Jun 2023 03:41:58 -0400 Received: from mail-pg1-x529.google.com (mail-pg1-x529.google.com [IPv6:2607:f8b0:4864:20::529]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 3690FE4D for ; Tue, 20 Jun 2023 00:41:15 -0700 (PDT) Received: by mail-pg1-x529.google.com with SMTP id 41be03b00d2f7-543c6a2aa07so2309817a12.0 for ; Tue, 20 Jun 2023 00:41:15 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ventanamicro.com; s=google; t=1687246874; x=1689838874; h=in-reply-to:content-transfer-encoding:content-disposition :mime-version:references:message-id:subject:cc:to:from:date:from:to :cc:subject:date:message-id:reply-to; bh=VNlkE9w8+4f9Owz1VR7DDy4a4R4dy/xTsJ/TjLKMtek=; b=bIFBmbK7FiaHLaGDgWmmB8jUjaecxgDpHm0ygwpqqg5bHBVtNXttGwGxPwQo1YYQ7Y ZYlopM4IUXYJTd9dQvjq7ZsHlFV6SDvOM0ePY0PyCktChM1feYusty5BHSInAs1Td43g nc11Q98qxk0UJzEZ1zwFu8gtOAL3ZLkQtCnkMneDVIEJTVe9ttfRLgQdm7xE0tduQIBB uaxQ/DaCgChdzcJ3h0cvQslVCVDWrj5T8TpJj8LUBZycoBSfkmEKVsXzpfW/m+IXAetN DcEWlT04weeu/jZAvmCiw5LBjQmAlVpkN6e67RhWhdS/40ees722j8iArp1zPRh96yj1 h2kA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1687246874; x=1689838874; h=in-reply-to:content-transfer-encoding:content-disposition :mime-version:references:message-id:subject:cc:to:from:date :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=VNlkE9w8+4f9Owz1VR7DDy4a4R4dy/xTsJ/TjLKMtek=; b=H7JTN9115HM/DxwyHGX7zsakFwqKvu7KPnufWEFZGvEfXfWrbXCmdq5HKeVpj442V9 v5EmKK20EvEDo/lqIEYoCjClcmZAQZv3vqaZtvXqERkIiDy75gk3nayG9wLZBhe6uKfT b52n+FdCP8xM2WEMtugMtjSodjqDIPfxsNIDIiB7yzNNXlcBJhjcirzNT0k54qaoKKIx PsuAcvqI9GWUANhZzzjrAurR/xBXC62rSdBe8FEIFEzWrPNMMGfzymdE1uTHx0avHjBV oLIzWWcBj6FVQ4hyheV6fZ5KkllkrPj2+XSQ2VWP8xeqP+scSM85K8d8sEE1OeUfr0IX hZKw== X-Gm-Message-State: AC+VfDwhdkXy4AcwzRfRlocUn3XvvRl93AaHtNpMIwffr91EIvljOly3 LTIvVlIc14P04726Sx4gkmm5kg== X-Received: by 2002:a05:6a21:339a:b0:115:dfb:da59 with SMTP id yy26-20020a056a21339a00b001150dfbda59mr10678421pzb.3.1687246874592; Tue, 20 Jun 2023 00:41:14 -0700 (PDT) Received: from sunil-laptop ([106.51.184.72]) by smtp.gmail.com with ESMTPSA id r1-20020a1709028bc100b001a1b66af22fsm975645plo.62.2023.06.20.00.41.10 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 20 Jun 2023 00:41:14 -0700 (PDT) Date: Tue, 20 Jun 2023 13:11:07 +0530 From: Sunil V L To: Alexandre Ghiti Cc: Conor Dooley , Atish Kumar Patra , Jonathan Corbet , Paul Walmsley , Palmer Dabbelt , Albert Ou , linux-doc@vger.kernel.org, linux-riscv@lists.infradead.org, linux-kernel@vger.kernel.org Subject: Re: [PATCH 1/2] Documentation: riscv: Add early boot document Message-ID: References: <20230619094705.51337-1-alexghiti@rivosinc.com> <20230619-kerchief-unmixed-cfdbeb1cf242@wendy> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_NONE, SPF_HELO_NONE,SPF_PASS,T_SCC_BODY_TEXT_LINE,URIBL_BLOCKED autolearn=unavailable autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Mon, Jun 19, 2023 at 04:04:52PM +0200, Alexandre Ghiti wrote: > On Mon, Jun 19, 2023 at 2:26 PM Conor Dooley wrote: > > > > Hey Alex, > > > > Thanks for working on this :) I've got a mix of suggestions and > > questions below. Hopefully it is not too disjoint, since I didn't write > > them in order. > > > > On Mon, Jun 19, 2023 at 11:47:04AM +0200, Alexandre Ghiti wrote: > > > This document describes the constraints and requirements of the early > > > boot process in a RISC-V kernel. > > > > > > Szigned-off-by: Alexandre Ghiti > > > --- > > > Documentation/riscv/boot-image-header.rst | 3 - > > > Documentation/riscv/boot.rst | 181 ++++++++++++++++++++++ > > > Documentation/riscv/index.rst | 1 + > > > 3 files changed, 182 insertions(+), 3 deletions(-) > > > create mode 100644 Documentation/riscv/boot.rst > > > > > > diff --git a/Documentation/riscv/boot-image-header.rst b/Documentation/riscv/boot-image-header.rst > > > index d7752533865f..a4a45310c4c4 100644 > > > --- a/Documentation/riscv/boot-image-header.rst > > > +++ b/Documentation/riscv/boot-image-header.rst > > > @@ -7,9 +7,6 @@ Boot image header in RISC-V Linux > > > > > > This document only describes the boot image header details for RISC-V Linux. > > > > > > -TODO: > > > - Write a complete booting guide. > > > - > > > The following 64-byte header is present in decompressed Linux kernel image:: > > > > > > u32 code0; /* Executable code */ > > > diff --git a/Documentation/riscv/boot.rst b/Documentation/riscv/boot.rst > > > new file mode 100644 > > > index 000000000000..b02230818b79 > > > --- /dev/null > > > +++ b/Documentation/riscv/boot.rst > > > @@ -0,0 +1,181 @@ > > > +.. SPDX-License-Identifier: GPL-2.0 > > > + > > > +============================================= > > > +Early boot requirements/constraints on RISC-V > > > +============================================= > > > > Please use "title case", here and elsewhere in the doc. > > You mean using "title: " instead of "===="? Or using uppercase for the > first letter of each word? FYI I followed > https://docs.kernel.org/doc-guide/sphinx.html?highlight=title#specific-guidelines-for-the-kernel-documentation > > > I'd also be inclined to drop the "Early" from here, as it permits more > > natural section headings. Perhaps "RISC-V Kernel Boot Requirements and > > Constraints"? > > Good suggestion, I'll go with that, thanks > > > > > > + > > > +:Author: Alexandre Ghiti > > > +:Date: 23 May 2023 > > > + > > > +This document describes what the RISC-V kernel expects from the previous stages > > > > "the previous stages" is a bit vague IMO. You mean bootloader stages I > > assume, but I think it should be explicit. Perhaps: > > "...what a RISC-V kernel expects from bootloaders and firmware, and the > > constraints..." > > > > > +and the firmware, but also the constraints that any developer must have in mind > > > +when touching the early boot process, e.g. before the final virtual mapping is > > > +setup. > > > > s/setup./set up./ > > > > Do you mean to have "For example" here? Or is "before the final virtual > > mapping is set up" the definition or "early boot"? If the latter, I > > would reword this as something like: > > "...when modifying the early boot process. For the purposes of this > > document, the 'early boot process' refers to any code that runs before > > the final virtual mapping is set up." > > Thanks, that's what I meant. > > > > > > +Pre-kernel boot (Expectations from firmware) > > > > Firmware or bootloaders? TBH, I would just drop the section in () and > > do something like: > > Pre-kernel Requirements and Constraints > > ======================================= > > > > The RISC-V kernel expects the following of bootloaders and platform > > firmware: > > > > Ok > > > > + > > > +Registers state > > > > s/Registers state/Register State/ > > Ok > > > > > > +--------------- > > > + > > > +The RISC-V kernel expects: > > > + > > > + * `$a0` to contain the hartid of the current core. > > > + * `$a1` to contain the address of the device tree in memory. > > > + > > > +CSR state > > > +--------- > > > + > > > +The RISC-V kernel expects: > > > + > > > + * `$satp = 0`: the MMU must be disabled. > > > > "the MMU, if present, must be disabled." ;) > > Ahah forgot the !mmu case, thanks :) > > > > > > + > > > +Reserved memory for resident firmware > > > +------------------------------------- > > > + > > > +The RISC-V kernel expects the firmware to mark any resident memory with the > > > > Should this be > > "...resident memory, or memory it has protected with PMPs, with..." > > ? > > I used "resident" memory instead of "PMP" memory because it was more > general. I mean you can have a region that is resident but not > protected by PMP, and I don't think the kernel should ask for this > resident memory to be protected with PMP right? > > > > > > +`no-map` flag, thus the kernel won't map those regions in the direct mapping > > > > "no-map" is a DT specific term, should this section be moved down under > > DT, as a sub-section of that? > > Maybe I can rephrase with something like that: > > "The RISC-V kernel must not map any resident memory in the direct > mapping, so the firmware must correctly mark those regions as follows: > - when using a devicetree, using the `no-map` flag, > - when booting with UEFI without devicetree, either as > `EfiRuntimeServicesData/Code` or `EfiReserved`." > Hi Alex, I am not sure about the idea behind mentioning only UEFI boot without DT since UEFI boot is supported with DT also. Should we just mention that "when booting with UEFI, resident firmware ranges must be marked as per UEFI specification" ? Converting reserved-memory node in DT to UEFI memory map is anyway mentioned separately under UEFI memory map section right? Thanks, Sunil