[PATCH 0/4] Documentation: riscv: Image cleanups

[PATCH 0/4] Documentation: riscv: Image cleanups

[Palmer Dabbelt]

There were a handful of issues with our image format documentation that
I noticed when reading it.  Nominally they're all independent, but since
it's text they'll all conflict so I've sent them in order.



_______________________________________________
linux-riscv mailing list
linux-riscv@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-riscv

[PATCH 1/4] Documentation: riscv: boot: We're not compatible with arm64

[Palmer Dabbelt]

The documentation for our bootloader claims that it can be made
compatible with arm64, but that's not true.  There are some differences
between our format and arm64:

* We've used the first 32 bits of their 64-bit "res2" as a version number,
  which we're currently setting to non-zero.
* We're using their "res4" field as our magic number.
* We're treating their magic number as our "res3" field, which nominally
  contains a flag for big endian systems already.  This can't get set, so we
  should just drop it -- it's also not described what the flag means.

This patch removes the claim that our header can be made compatible with
arm64.

Signed-off-by: Palmer Dabbelt <palmer@sifive.com>
---
 Documentation/riscv/boot-image-header.txt | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/Documentation/riscv/boot-image-header.txt b/Documentation/riscv/boot-image-header.txt
index 1b73fea23b39..77e8e505bc41 100644
--- a/Documentation/riscv/boot-image-header.txt
+++ b/Documentation/riscv/boot-image-header.txt
@@ -21,9 +21,8 @@ The following 64-byte header is present in decompressed Linux kernel image.
 	u32 res3;		  /* Reserved for additional RISC-V specific header */
 	u32 res4;		  /* Reserved for PE COFF offset */
 
-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.
+This header format is compliant with PE/COFF header and largely inspired by,
+but not compatible with, the ARM64 header.
 
 Notes:
 - This header can also be reused to support EFI stub for RISC-V in future. EFI
-- 
2.21.0


_______________________________________________
linux-riscv mailing list
linux-riscv@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-riscv

Re: [PATCH 1/4] Documentation: riscv: boot: We're not compatible with arm64

[Paul Walmsley]

On Fri, 13 Sep 2019, Palmer Dabbelt wrote:

> The documentation for our bootloader claims that it can be made
> compatible with arm64, but that's not true.  There are some differences
> between our format and arm64:
> 
> * We've used the first 32 bits of their 64-bit "res2" as a version number,
>   which we're currently setting to non-zero.

During the review of this patch, I assumed -- maybe incorrectly -- that 
ARM64 didn't require the reserved fields to be zero.  In retrospect, this 
was not a good assumption to make.  It would have been better for me to 
get explicit agreement from the ARM64 folks.

> * We're using their "res4" field as our magic number.
> * We're treating their magic number as our "res3" field,

This looks like the key issue.  Let's rename the 32-bit RISC-V res3 field 
as magic2, and just use it.  Then over time we should be able to deprecate 
the original RISC-V 64-bit magic field.

>   which nominally contains a flag for big endian systems already.  This 
>   can't get set, so we should just drop it -- it's also not described 
>   what the flag means.

This one I'm not seeing.  In both headers, the flags field is in the 
same place: towards the beginning of the headers, before the reserved 
fields:

https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/arch/riscv/include/asm/image.h#n56

https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/arch/arm64/include/asm/image.h#n49

The endianness bit in that field is defined the same way:

https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/arm64/booting.rst#n106

https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/riscv/boot-image-header.txt#n46

Please let me know if I've misunderstood your point.

> 
> This patch removes the claim that our header can be made compatible with
> arm64.
> 
> Signed-off-by: Palmer Dabbelt <palmer@sifive.com>
> ---
>  Documentation/riscv/boot-image-header.txt | 5 ++---
>  1 file changed, 2 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/riscv/boot-image-header.txt b/Documentation/riscv/boot-image-header.txt
> index 1b73fea23b39..77e8e505bc41 100644
> --- a/Documentation/riscv/boot-image-header.txt
> +++ b/Documentation/riscv/boot-image-header.txt
> @@ -21,9 +21,8 @@ The following 64-byte header is present in decompressed Linux kernel image.
>  	u32 res3;		  /* Reserved for additional RISC-V specific header */
>  	u32 res4;		  /* Reserved for PE COFF offset */
>  
> -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.
> +This header format is compliant with PE/COFF header and largely inspired by,
> +but not compatible with, the ARM64 header.
>  
>  Notes:
>  - This header can also be reused to support EFI stub for RISC-V in future. EFI
> -- 
> 2.21.0
> 
> 
> _______________________________________________
> linux-riscv mailing list
> linux-riscv@lists.infradead.org
> http://lists.infradead.org/mailman/listinfo/linux-riscv
> 


- Paul

_______________________________________________
linux-riscv mailing list
linux-riscv@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-riscv

Re: [PATCH 1/4] Documentation: riscv: boot: We're not compatible with arm64

[Atish Patra]

On Fri, 2019-09-13 at 18:13 -0700, Paul Walmsley wrote:
> On Fri, 13 Sep 2019, Palmer Dabbelt wrote:
> 
> > The documentation for our bootloader claims that it can be made
> > compatible with arm64, but that's not true.  There are some
> > differences
> > between our format and arm64:
> > 
> > * We've used the first 32 bits of their 64-bit "res2" as a version
> > number,
> >   which we're currently setting to non-zero.
> 
> During the review of this patch, I assumed -- maybe incorrectly --
> that 
> ARM64 didn't require the reserved fields to be zero.  In retrospect,
> this 
> was not a good assumption to make.  It would have been better for me
> to 
> get explicit agreement from the ARM64 folks.
> 

Any reserved field is set to zero. The idea was to modify the reserve
field for ARM to have a flag version if we ever unify both ARM64 &
RISC-V headers.

> > * We're using their "res4" field as our magic number.
> > * We're treating their magic number as our "res3" field,
> 
> This looks like the key issue.  Let's rename the 32-bit RISC-V res3
> field 
> as magic2, and just use it.  Then over time we should be able to
> deprecate 
> the original RISC-V 64-bit magic field.
> 

Originally, "RISCV" magic value was a 64-bit value. That's why I kept
in res4 field. Again, my plan was to have a arch specific ifdef only
for magic values if we ever unify both ARM64 & RISC-V headers.

We never got the ack for unification of boot header proposal from ARM
maintainers. Thus, these things never got implemented.

> >   which nominally contains a flag for big endian systems
> > already.  This 
> >   can't get set, so we should just drop it -- it's also not
> > described 
> >   what the flag means.
> 
> This one I'm not seeing.  In both headers, the flags field is in the 
> same place: towards the beginning of the headers, before the
> reserved 
> fields:
> 
> https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/arch/riscv/include/asm/image.h#n56
> 
> https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/arch/arm64/include/asm/image.h#n49
> 
> The endianness bit in that field is defined the same way:
> 
> https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/arm64/booting.rst#n106
> 
> https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/riscv/boot-image-header.txt#n46
> 
> Please let me know if I've misunderstood your point.
> 

I agree with Paul.

Regards,
Atish
> > This patch removes the claim that our header can be made compatible
> > with
> > arm64.
> > 
> > Signed-off-by: Palmer Dabbelt <palmer@sifive.com>
> > ---
> >  Documentation/riscv/boot-image-header.txt | 5 ++---
> >  1 file changed, 2 insertions(+), 3 deletions(-)
> > 
> > diff --git a/Documentation/riscv/boot-image-header.txt
> > b/Documentation/riscv/boot-image-header.txt
> > index 1b73fea23b39..77e8e505bc41 100644
> > --- a/Documentation/riscv/boot-image-header.txt
> > +++ b/Documentation/riscv/boot-image-header.txt
> > @@ -21,9 +21,8 @@ The following 64-byte header is present in
> > decompressed Linux kernel image.
> >  	u32 res3;		  /* Reserved for additional RISC-V
> > specific header */
> >  	u32 res4;		  /* Reserved for PE COFF offset */
> >  
> > -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.
> > +This header format is compliant with PE/COFF header and largely
> > inspired by,
> > +but not compatible with, the ARM64 header.
> >  
> >  Notes:
> >  - This header can also be reused to support EFI stub for RISC-V in
> > future. EFI
> > -- 
> > 2.21.0
> > 
> > 
> > _______________________________________________
> > linux-riscv mailing list
> > linux-riscv@lists.infradead.org
> > http://lists.infradead.org/mailman/listinfo/linux-riscv
> > 
> 
> - Paul

-- 
Regards,
Atish
_______________________________________________
linux-riscv mailing list
linux-riscv@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-riscv

[PATCH 2/4] Documentation: riscv: boot: Don't claim we're compliant with PE

[Palmer Dabbelt]

We don't yet have a PE header in our image.  While we could add one, we
shouldn't claim we have one in the documentation.

Signed-off-by: Palmer Dabbelt <palmer@sifive.com>
---
 Documentation/riscv/boot-image-header.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/riscv/boot-image-header.txt b/Documentation/riscv/boot-image-header.txt
index 77e8e505bc41..219f62ef62c4 100644
--- a/Documentation/riscv/boot-image-header.txt
+++ b/Documentation/riscv/boot-image-header.txt
@@ -21,7 +21,7 @@ The following 64-byte header is present in decompressed Linux kernel image.
 	u32 res3;		  /* Reserved for additional RISC-V specific header */
 	u32 res4;		  /* Reserved for PE COFF offset */
 
-This header format is compliant with PE/COFF header and largely inspired by,
+This header format can be made compliant with PE/COFF header and largely inspired by,
 but not compatible with, the ARM64 header.
 
 Notes:
-- 
2.21.0


_______________________________________________
linux-riscv mailing list
linux-riscv@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-riscv

[PATCH 3/4] Documentation: riscv: boot: Whitespace fix

[Palmer Dabbelt]

This fixes a missing space before a "(" that I found when reading the
documentation.

Signed-off-by: Palmer Dabbelt <palmer@sifive.com>
---
 Documentation/riscv/boot-image-header.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/riscv/boot-image-header.txt b/Documentation/riscv/boot-image-header.txt
index 219f62ef62c4..e325d1c9ad4c 100644
--- a/Documentation/riscv/boot-image-header.txt
+++ b/Documentation/riscv/boot-image-header.txt
@@ -28,7 +28,7 @@ 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
+  code0 should be replaced with "MZ" magic string and res4 (at offset 0x3c) should
   point to the rest of the PE/COFF header.
 
 - version field indicate header version number.
-- 
2.21.0


_______________________________________________
linux-riscv mailing list
linux-riscv@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-riscv

[PATCH 4/4] Documentation: riscv: boot: Don't mention big-endian

[Palmer Dabbelt]

The documentation defines a flag to indicate big endian systems, but
doesn't define what that flag actually means -- for example:

* Are the other fields BE or LE?
* Does the BE format assume the bootloader enters BE mode, is there a
  kernel stub that does so, or are we adding extra BE instructions?

Signed-off-by: Palmer Dabbelt <palmer@sifive.com>
---
 Documentation/riscv/boot-image-header.txt | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/Documentation/riscv/boot-image-header.txt b/Documentation/riscv/boot-image-header.txt
index e325d1c9ad4c..d3efaf374b27 100644
--- a/Documentation/riscv/boot-image-header.txt
+++ b/Documentation/riscv/boot-image-header.txt
@@ -42,8 +42,5 @@ Notes:
   header extendible in future. One example would be to accommodate ISA
   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.
-
 - Image size is mandatory for boot loader to load kernel image. Booting will
   fail otherwise.
-- 
2.21.0


_______________________________________________
linux-riscv mailing list
linux-riscv@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-riscv

Re: [PATCH 0/4] Documentation: riscv: Image cleanups

[Atish Patra]

On Fri, 2019-09-13 at 12:24 -0700, Palmer Dabbelt wrote:
> There were a handful of issues with our image format documentation
> that
> I noticed when reading it.  Nominally they're all independent, but
> since
> it's text they'll all conflict so I've sent them in order.
> 
> 
> 
> _______________________________________________
> linux-riscv mailing list
> linux-riscv@lists.infradead.org
> http://lists.infradead.org/mailman/listinfo/linux-riscv

As I replied in Paul's patch

There is a patch already queued that changed the format to ReST. You
need to rebase the series accordingly

https://lkml.org/lkml/2019/7/26/1321

It would also be good if you combine your documentation typo fixes with
paul's so that all of them can be merged together.

-- 
Regards,
Atish
_______________________________________________
linux-riscv mailing list
linux-riscv@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-riscv