Skip to contentSkip to conversation

Documentation: riscv: Image cleanups

PATCH In review Palmer Dabbelt 3 participants 8 messages Sep 13, 2019 – Sep 14, 2019

Subsystems (2)
lore
Share & tools
lore
#1 lore raw

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

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.

---
 Documentation/riscv/boot-image-header.txt | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)
Documentation/riscv/boot-image-header.txt +2 -3
index 1b73fea23b39..77e8e505bc41 100644
@@ -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
Signature · 7 lines
2.21.0


_______________________________________________
linux-riscv mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-riscv
#2 lore raw

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

Quoted 6 lines · 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.

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.

Quoted 2 lines

* 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.

Quoted 3 lines

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.

Quoted 34 lines

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

---
 Documentation/riscv/boot-image-header.txt | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)
Documentation/riscv/boot-image-header.txt +2 -3
index 1b73fea23b39..77e8e505bc41 100644
@@ -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
Signature · 7 lines
2.21.0


_______________________________________________
linux-riscv mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-riscv

- Paul

_______________________________________________
linux-riscv mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-riscv

#3 lore raw

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

Quoted 11 lines · Paul Walmsley
Quoted 8 lines · 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.

Quoted 8 lines

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.

Quoted 9 lines
Quoted 2 lines

* 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.

Quoted 15 lines
Quoted 5 lines

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

Quoted 8 lines

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

Quoted 43 lines
Quoted 29 lines

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

---
 Documentation/riscv/boot-image-header.txt | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)
Documentation/riscv/boot-image-header.txt +0 -0
index 1b73fea23b39..77e8e505bc41 100644
@@ -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 */

Documentation/riscv/boot-image-header.txt +0 -1
 	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

Documentation/riscv/boot-image-header.txt +1 -1
-header in future.
+This header format is compliant with PE/COFF header and largely

inspired by,
+but not compatible with, the ARM64 header.

Quoted 12 lines

Notes:
- This header can also be reused to support EFI stub for RISC-V in
future. EFI

Signature · 7 lines
2.21.0


_______________________________________________
linux-riscv mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-riscv

- Paul

Signature · 6 lines
Regards,
Atish
_______________________________________________
linux-riscv mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-riscv
#4 lore raw

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

In reply to 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.

---
 Documentation/riscv/boot-image-header.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/riscv/boot-image-header.txt +1 -1
index 77e8e505bc41..219f62ef62c4 100644
@@ -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:
Signature · 7 lines
2.21.0


_______________________________________________
linux-riscv mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-riscv
#5 lore raw

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

In reply to Palmer Dabbelt

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

---
 Documentation/riscv/boot-image-header.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/riscv/boot-image-header.txt +1 -1
index 219f62ef62c4..e325d1c9ad4c 100644
@@ -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.
Signature · 7 lines
2.21.0


_______________________________________________
linux-riscv mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-riscv
#6 lore raw

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

In reply to 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?

---
 Documentation/riscv/boot-image-header.txt | 3 ---
 1 file changed, 3 deletions(-)
Documentation/riscv/boot-image-header.txt +0 -3
index e325d1c9ad4c..d3efaf374b27 100644
@@ -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.
Signature · 7 lines
2.21.0


_______________________________________________
linux-riscv mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-riscv
#7 lore raw
In reply to Palmer Dabbelt
Quoted 8 lines · 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.

Quoted 4 lines

_______________________________________________
linux-riscv mailing list
[email protected]
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.

Signature · 6 lines
Regards,
Atish
_______________________________________________
linux-riscv mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-riscv