linux-kernel - Re: [PATCH] docs: riscv: convert boot-image-header.txt to ReST

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <40e0f516-402b-29eb-d69b-fda1af26801e@wdc.com>
Date:   Fri, 26 Jul 2019 15:24:24 -0700
From:   Atish Patra <atish.patra@....com>
To:     Mauro Carvalho Chehab <mchehab+samsung@...nel.org>,
        Linux Doc Mailing List <linux-doc@...r.kernel.org>
Cc:     Albert Ou <aou@...s.berkeley.edu>,
        Jonathan Corbet <corbet@....net>,
        Linus Walleij <linus.walleij@...aro.org>,
        Palmer Dabbelt <palmer@...ive.com>,
        "linux-kernel@...r.kernel.org" <linux-kernel@...r.kernel.org>,
        Mauro Carvalho Chehab <mchehab@...radead.org>,
        Paul Walmsley <paul.walmsley@...ive.com>,
        "linux-riscv@...ts.infradead.org" <linux-riscv@...ts.infradead.org>,
        Karsten Merker <merker@...ian.org>
Subject: Re: [PATCH] docs: riscv: convert boot-image-header.txt to ReST

On 7/26/19 2:02 PM, Mauro Carvalho Chehab wrote:
> Convert this small file to ReST format by:
>     - Using a proper markup for the document title;
>     - marking a code block as such;
>     - use tags for Author and date;
>     - use tables for bit map fields.
> 
> While here, fix a broken reference for a document with is
> planned but is not here yet.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@...nel.org>
> ---
>   ...image-header.txt => boot-image-header.rst} | 39 ++++++++++++-------
>   Documentation/riscv/index.rst                 |  1 +
>   2 files changed, 26 insertions(+), 14 deletions(-)
>   rename Documentation/riscv/{boot-image-header.txt => boot-image-header.rst} (72%)
> 
> diff --git a/Documentation/riscv/boot-image-header.txt b/Documentation/riscv/boot-image-header.rst
> similarity index 72%
> rename from Documentation/riscv/boot-image-header.txt
> rename to Documentation/riscv/boot-image-header.rst
> index 1b73fea23b39..43e9bd0731d5 100644
> --- a/Documentation/riscv/boot-image-header.txt
> +++ b/Documentation/riscv/boot-image-header.rst
> @@ -1,22 +1,25 @@
> -				Boot image header in RISC-V Linux
> -			=============================================
> +=================================
> +Boot image header in RISC-V Linux
> +=================================
>   
> -Author: Atish Patra <atish.patra@....com>
> -Date  : 20 May 2019
> +:Author: Atish Patra <atish.patra@....com>
> +:Date:   20 May 2019
>   
>   This document only describes the boot image header details for RISC-V Linux.
> -The complete booting guide will be available at Documentation/riscv/booting.txt.
>   
> -The following 64-byte header is present in decompressed Linux kernel image.
> +TODO:
> +  Write a complete booting guide.
> +
> +The following 64-byte header is present in decompressed Linux kernel image::
>   
>   	u32 code0;		  /* Executable code */
> -	u32 code1; 		  /* Executable code */
> +	u32 code1;		  /* Executable code */
>   	u64 text_offset;	  /* Image load offset, little endian */
>   	u64 image_size;		  /* Effective Image size, little endian */
>   	u64 flags;		  /* kernel flags, little endian */
>   	u32 version;		  /* Version of this header */
> -	u32 res1  = 0;		  /* Reserved */
> -	u64 res2  = 0;    	  /* Reserved */
> +	u32 res1 = 0;		  /* Reserved */
> +	u64 res2 = 0;		  /* Reserved */
>   	u64 magic = 0x5643534952; /* Magic number, little endian, "RISCV" */
>   	u32 res3;		  /* Reserved for additional RISC-V specific header */
>   	u32 res4;		  /* Reserved for PE COFF offset */
> @@ -25,16 +28,21 @@ This header format is compliant with PE/COFF header and largely inspired from
>   ARM64 header. Thus, both ARM64 & RISC-V header can be combined into one common
>   header in future.
>   
> -Notes:
> +Notes
> +=====
> +
>   - This header can also be reused to support EFI stub for RISC-V in future. EFI
>     specification needs PE/COFF image header in the beginning of the kernel image
>     in order to load it as an EFI application. In order to support EFI stub,
>     code0 should be replaced with "MZ" magic string and res5(at offset 0x3c) should
>     point to the rest of the PE/COFF header.
>   
> -- version field indicate header version number.
> -	Bits 0:15  - Minor version
> -	Bits 16:31 - Major version
> +- version field indicate header version number
> +
> +	==========  =============
> +	Bits 0:15   Minor version
> +	Bits 16:31  Major version
> +	==========  =============
>   
>     This preserves compatibility across newer and older version of the header.
>     The current version is defined as 0.1.
> @@ -44,7 +52,10 @@ Notes:
>     extension for RISC-V in future. For current version, it is set to be zero.
>   
>   - In current header, the flag field has only one field.
> -	Bit 0: Kernel endianness. 1 if BE, 0 if LE.
> +
> +	=====  ====================================
> +	Bit 0  Kernel endianness. 1 if BE, 0 if LE.
> +	=====  ====================================
>   
>   - Image size is mandatory for boot loader to load kernel image. Booting will
>     fail otherwise.
> diff --git a/Documentation/riscv/index.rst b/Documentation/riscv/index.rst
> index e3ca0922a8c2..215fd3c1f2d5 100644
> --- a/Documentation/riscv/index.rst
> +++ b/Documentation/riscv/index.rst
> @@ -5,6 +5,7 @@ RISC-V architecture
>   .. toctree::
>       :maxdepth: 1
>   
> +    boot-image-header
>       pmu
>   
>   .. only::  subproject and html
> 

Thanks for the quick patch.

Reviewed-by: Atish Patra <atish.patra@....com>

-- 
Regards,
Atish