Add clarifications to the x86 README

Explicitly list the targets supported in each section of the instructions from the x86 README.

Signed-off-by Igor Stoppa <[email protected]>

---
 doc/README.x86 | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

doc/README.x86 +7 -4

index af2459c..1105afe 100644
@@ -19,14 +19,15 @@ work with minimal adjustments on other x86 boards since coreboot deals with
 most of the low-level details.
 
 U-Boot also supports booting directly from x86 reset vector without coreboot,
-aka raw support or bare support. Currently Link, QEMU x86 targets and all
-Intel boards support running U-Boot 'bare metal'.
+aka raw support or bare support. U-Boot becomes a replacement for the BIOS.
+Currently Link, QEMU x86 targets and all Intel boards support running U-Boot
+'bare metal'.
 
 As for loading an OS, U-Boot supports directly booting a 32-bit or 64-bit
 Linux kernel as part of a FIT image. It also supports a compressed zImage.
 
-Build Instructions
-------------------
+Build Instructions for U-Boot as coreboot payload
+-------------------------------------------------
 Building U-Boot as a coreboot payload is just like building U-Boot for targets
 on other architectures, like below:
 

@@ -48,6 +49,8 @@ Change the 'Board configuration file' and 'Board Device Tree Source (dts) file'
 to point to a new board. You can also change the Cache-As-RAM (CAR) related
 settings here if the default values do not fit your new board.
 
+Build Instructions for U-Boot as BIOS replacement (raw/bare mode)
+-----------------------------------------------------------------
 Building a ROM version of U-Boot (hereafter referred to as u-boot.rom) is a
 little bit tricky, as generally it requires several binary blobs which are not
 shipped in the U-Boot source tree. Due to this reason, the u-boot.rom build is

Hi Igor,

Quoted 3 lines · Igor Stoppa

Explicitly list the targets supported in each section of the instructions from the x86 README.

Nits: we should put tags in the patch/commit title, eg:

x86: Add clarifications to the x86 README

Quoted 42 lines

Signed-off-by Igor Stoppa <[email protected]>

---
 doc/README.x86 | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

doc/README.x86 +7 -4

index af2459c..1105afe 100644
@@ -19,14 +19,15 @@ work with minimal adjustments on other x86 boards since coreboot deals with
 most of the low-level details.
 
 U-Boot also supports booting directly from x86 reset vector without coreboot,
-aka raw support or bare support. Currently Link, QEMU x86 targets and all
-Intel boards support running U-Boot 'bare metal'.
+aka raw support or bare support. U-Boot becomes a replacement for the BIOS.
+Currently Link, QEMU x86 targets and all Intel boards support running U-Boot
+'bare metal'.
 
 As for loading an OS, U-Boot supports directly booting a 32-bit or 64-bit
 Linux kernel as part of a FIT image. It also supports a compressed zImage.
 
-Build Instructions
-------------------
+Build Instructions for U-Boot as coreboot payload
+-------------------------------------------------
 Building U-Boot as a coreboot payload is just like building U-Boot for targets
 on other architectures, like below:
 

@@ -48,6 +49,8 @@ Change the 'Board configuration file' and 'Board Device Tree Source (dts) file'
 to point to a new board. You can also change the Cache-As-RAM (CAR) related
 settings here if the default values do not fit your new board.
 
+Build Instructions for U-Boot as BIOS replacement (raw/bare mode)
+-----------------------------------------------------------------
 Building a ROM version of U-Boot (hereafter referred to as u-boot.rom) is a
 little bit tricky, as generally it requires several binary blobs which are not
 shipped in the U-Boot source tree. Due to this reason, the u-boot.rom build is

@@ -87,7 +90,7 @@ Now you can build U-Boot and obtain u-boot.rom:
 $ make chromebook_link_defconfig
 $ make all
 

doc/README.x86 Now you can build U-Boot and obtain u-boot.rom: · line 93

Quoted 2 lines

doc/README.x86 +1 -1

-Intel Crown Bay specific instructions:
+Intel Crown Bay specific instructions (raw mode):

I think we don't need add (raw mode) as you already added a section header above.

doc/README.x86 Now you can build U-Boot and obtain u-boot.rom · line 128

Quoted 10 lines

doc/README.x86 +1 -1

 U-Boot support of Intel Crown Bay board [4] relies on a binary blob called
 Firmware Support Package [5] to perform all the necessary initialization steps

@@ -122,7 +125,7 @@ Now you can build U-Boot and obtain u-boot.rom
 $ make crownbay_defconfig
 $ make all
 
-Intel Minnowboard Max instructions:
+Intel Minnowboard Max instructions (raw mode):

Ditto.

doc/README.x86 Offset Description Controlling config · line 195

Quoted 9 lines

doc/README.x86 +1 -1

 This uses as FSP as with Crown Bay, except it is for the Atom E3800 series.
 Download this and get the .fd file (BAYTRAIL_FSP_GOLD_003_16-SEP-2014.fd at

@@ -189,7 +192,7 @@ Offset   Description         Controlling config
 Overall ROM image size is controlled by CONFIG_ROM_SIZE.
 
 
-Intel Galileo instructions:
+Intel Galileo instructions (raw mode):

Ditto.

Quoted 1 line

Quoted 3 lines

Only one binary blob is needed for Remote Management Unit (RMU) within Intel Quark SoC. Not like FSP, U-Boot does not call into the binary. The binary is
--

Regards,
Bin

I prefer 'bare mode' to 'raw mode'. It suggests that U-Boot is running on the bare metal. Perhaps we should drop the word 'raw' and use 'bare' instead, for consistency?

Hi Igor,

Quoted 3 lines · Igor Stoppa

Explicitly list the targets supported in each section of the instructions from the x86 README.

Nits: we should put tags in the patch/commit title, eg:

x86: Add clarifications to the x86 README

doc/README.x86 Now you can build U-Boot and obtain u-boot.rom: · line 93

Quoted 2 lines

doc/README.x86 +1 -1

-Intel Crown Bay specific instructions:
+Intel Crown Bay specific instructions (raw mode):

I think we don't need add (raw mode) as you already added a section header above.

Hi Bin,

Quoted 10 lines · Bin Meng

Hi Igor,

Quoted 3 lines · Igor Stoppa

Explicitly list the targets supported in each section of the instructions from the x86 README.

Nits: we should put tags in the patch/commit title, eg:

x86: Add clarifications to the x86 README

ok, will fix it

[...]

Quoted 5 lines

doc/README.x86 Now you can build U-Boot and obtain u-boot.rom: · line 93

Quoted 2 lines

doc/README.x86 +1 -1

-Intel Crown Bay specific instructions:
+Intel Crown Bay specific instructions (raw mode):

I think we don't need add (raw mode) as you already added a section header above.

This was intentional. You are absolutely right that it's redundant, but I was trying to make the doc more friendly toward someone (like yours truly :-) who approaches it for the first time. Reading it, sometimes I had the feeling I wasn't 100% sure of what a certain section was referring to.

Some sections are not exactly short.

But if you still think it should be removed, I'll do so.

Hi Igor,

Quoted 24 lines · Igor

Hi Bin,

Quoted 10 lines · Bin Meng

Hi Igor,

Quoted 3 lines · Igor Stoppa

Explicitly list the targets supported in each section of the instructions from the x86 README.

Nits: we should put tags in the patch/commit title, eg:

x86: Add clarifications to the x86 README

ok, will fix it

[...]

Quoted 5 lines

doc/README.x86 Now you can build U-Boot and obtain u-boot.rom: · line 93

Quoted 2 lines

doc/README.x86 +1 -1

-Intel Crown Bay specific instructions:
+Intel Crown Bay specific instructions (raw mode):

I think we don't need add (raw mode) as you already added a section header above.

Quoted 5 lines

This was intentional. You are absolutely right that it's redundant, but I was trying to make the doc more friendly toward someone (like yours truly :-) who approaches it for the first time. Reading it, sometimes I had the feeling I wasn't 100% sure of what a certain section was referring to.

I am OK, Simon?

Quoted 6 lines

Some sections are not exactly short.

But if you still think it should be removed, I'll do so.

Regards,
Bin

* Explicitly list the targets supported in each section of the instructions from the x86 README.

* Drop references to 'raw mode', in favor of 'bare mode'.

Signed-off-by Igor Stoppa <[email protected]>

---
 doc/README.x86 | 24 ++++++++++++++----------
 1 file changed, 14 insertions(+), 10 deletions(-)

doc/README.x86 +0 -0

index af2459c..20865a5 100644

doc/README.x86 +8 -4

+Currently Link, QEMU x86 targets and all Intel boards support running U-Boot
+'bare metal'.
 
 As for loading an OS, U-Boot supports directly booting a 32-bit or 64-bit
 Linux kernel as part of a FIT image. It also supports a compressed zImage.
 
-Build Instructions
-------------------
+Build Instructions for U-Boot as coreboot payload
+-------------------------------------------------
 Building U-Boot as a coreboot payload is just like building U-Boot for targets
 on other architectures, like below:
 

@@ -48,6 +50,8 @@ Change the 'Board configuration file' and 'Board Device Tree Source (dts) file'
 to point to a new board. You can also change the Cache-As-RAM (CAR) related
 settings here if the default values do not fit your new board.
 
+Build Instructions for U-Boot as BIOS replacement (bare mode)
+-------------------------------------------------------------
 Building a ROM version of U-Boot (hereafter referred to as u-boot.rom) is a
 little bit tricky, as generally it requires several binary blobs which are not
 shipped in the U-Boot source tree. Due to this reason, the u-boot.rom build is

@@ -87,7 +91,7 @@ Now you can build U-Boot and obtain u-boot.rom:
 $ make chromebook_link_defconfig
 $ make all
 
-Intel Crown Bay specific instructions:
+Intel Crown Bay specific instructions for bare mode:
 
 U-Boot support of Intel Crown Bay board [4] relies on a binary blob called
 Firmware Support Package [5] to perform all the necessary initialization steps

@@ -122,7 +126,7 @@ Now you can build U-Boot and obtain u-boot.rom
 $ make crownbay_defconfig
 $ make all
 
-Intel Minnowboard Max instructions:
+Intel Minnowboard Max instructions for bare mode:
 
 This uses as FSP as with Crown Bay, except it is for the Atom E3800 series.
 Download this and get the .fd file (BAYTRAIL_FSP_GOLD_003_16-SEP-2014.fd at

doc/README.x86 +0 -0

 Only one binary blob is needed for Remote Management Unit (RMU) within Intel
 Quark SoC. Not like FSP, U-Boot does not call into the binary. The binary is

@@ -252,8 +256,8 @@ At present it seems that for Minnowboard Max, coreboot does not pass through
 the video information correctly (it always says the resolution is 0x0). This

Hi Igor,

On Thu, Aug 13, 2015 at 7:00 PM, Igor Stoppa <[email protected]> wrote:

Quoted 1 line

+In this case, known as bare mode, fom the fact that it runs on the

fom?

Quoted 1 line

+'bare metal', U-Boot acts like a BIOS replacement.

Do you intentionally leave the remaining line (till 80col) blank?

Please also update the line for "Chromebook Link".

Quoted 3 lines · Bin Meng

Hi Igor,

On Thu, Aug 13, 2015 at 7:00 PM, Igor Stoppa <[email protected]> wrote:

[...]

Quoted 3 lines

Quoted 1 line

+In this case, known as bare mode, fom the fact that it runs on the

fom?

argh, sorry, fixed

Quoted 3 lines

Quoted 1 line

+'bare metal', U-Boot acts like a BIOS replacement.

Do you intentionally leave the remaining line (till 80col) blank?

It felt more readable. But it's a matter of personal preferences. Should I leave just a space?

Quoted 2 lines

Please also update the line for "Chromebook Link".

done, thanks

--

* Explicitly list the targets supported in each section of the instructions from the x86 README.

* Drop references to 'raw mode', in favor of 'bare mode'.

Signed-off-by Igor Stoppa <[email protected]>

---
 doc/README.x86 | 32 +++++++++++++++++++++-----------
 1 file changed, 21 insertions(+), 11 deletions(-)

doc/README.x86 +19 -9

index af2459c..9012541 100644
@@ -18,15 +18,16 @@ U-Boot supports running as a coreboot [1] payload on x86. So far only Link
 work with minimal adjustments on other x86 boards since coreboot deals with
 most of the low-level details.
 
-U-Boot also supports booting directly from x86 reset vector without coreboot,
-aka raw support or bare support. Currently Link, QEMU x86 targets and all
-Intel boards support running U-Boot 'bare metal'.
+U-Boot also supports booting directly from x86 reset vector, without coreboot.
+In this case, known as bare mode, from the fact that it runs on the
+'bare metal', U-Boot acts like a BIOS replacement. Currently Link, QEMU x86
+targets and all Intel boards support running U-Boot 'bare metal'.
 
 As for loading an OS, U-Boot supports directly booting a 32-bit or 64-bit
 Linux kernel as part of a FIT image. It also supports a compressed zImage.
 
-Build Instructions
-------------------
+Build Instructions for U-Boot as coreboot payload
+-------------------------------------------------
 Building U-Boot as a coreboot payload is just like building U-Boot for targets
 on other architectures, like below:
 

@@ -48,6 +49,8 @@ Change the 'Board configuration file' and 'Board Device Tree Source (dts) file'
 to point to a new board. You can also change the Cache-As-RAM (CAR) related
 settings here if the default values do not fit your new board.
 
+Build Instructions for U-Boot as BIOS replacement (bare mode)
+-------------------------------------------------------------
 Building a ROM version of U-Boot (hereafter referred to as u-boot.rom) is a
 little bit tricky, as generally it requires several binary blobs which are not
 shipped in the U-Boot source tree. Due to this reason, the u-boot.rom build is

@@ -58,7 +61,9 @@ $ export BUILD_ROM=y
 
 This tells the Makefile to build u-boot.rom as a target.
 
-Link-specific instructions:
+---
+
+Chromebook Link specific instructions for bare mode:
 
 First, you need the following binary blobs:
 

@@ -87,7 +92,9 @@ Now you can build U-Boot and obtain u-boot.rom:
 $ make chromebook_link_defconfig
 $ make all
 
-Intel Crown Bay specific instructions:
+---
+
+Intel Crown Bay specific instructions for bare mode:
 
 U-Boot support of Intel Crown Bay board [4] relies on a binary blob called
 Firmware Support Package [5] to perform all the necessary initialization steps

@@ -122,7 +129,9 @@ Now you can build U-Boot and obtain u-boot.rom
 $ make crownbay_defconfig
 $ make all
 
-Intel Minnowboard Max instructions:
+---
+
+Intel Minnowboard Max instructions for bare mode:
 
 This uses as FSP as with Crown Bay, except it is for the Atom E3800 series.
 Download this and get the .fd file (BAYTRAIL_FSP_GOLD_003_16-SEP-2014.fd at

@@ -188,8 +197,9 @@ Offset   Description         Controlling config
 
 Overall ROM image size is controlled by CONFIG_ROM_SIZE.
 
+---
 
-Intel Galileo instructions:
+Intel Galileo instructions for bare mode:
 
 Only one binary blob is needed for Remote Management Unit (RMU) within Intel
 Quark SoC. Not like FSP, U-Boot does not call into the binary. The binary is

@@ -252,8 +262,8 @@ At present it seems that for Minnowboard Max, coreboot does not pass through
 the video information correctly (it always says the resolution is 0x0). This

Quoted 93 lines · Igor Stoppa

* Explicitly list the targets supported in each section of the instructions from the x86 README.

* Drop references to 'raw mode', in favor of 'bare mode'.

Signed-off-by Igor Stoppa <[email protected]>

---
 doc/README.x86 | 32 +++++++++++++++++++++-----------
 1 file changed, 21 insertions(+), 11 deletions(-)

doc/README.x86 +19 -9

index af2459c..9012541 100644
@@ -18,15 +18,16 @@ U-Boot supports running as a coreboot [1] payload on x86. So far only Link
 work with minimal adjustments on other x86 boards since coreboot deals with
 most of the low-level details.
 
-U-Boot also supports booting directly from x86 reset vector without coreboot,
-aka raw support or bare support. Currently Link, QEMU x86 targets and all
-Intel boards support running U-Boot 'bare metal'.
+U-Boot also supports booting directly from x86 reset vector, without coreboot.
+In this case, known as bare mode, from the fact that it runs on the
+'bare metal', U-Boot acts like a BIOS replacement. Currently Link, QEMU x86
+targets and all Intel boards support running U-Boot 'bare metal'.
 
 As for loading an OS, U-Boot supports directly booting a 32-bit or 64-bit
 Linux kernel as part of a FIT image. It also supports a compressed zImage.
 
-Build Instructions
-------------------
+Build Instructions for U-Boot as coreboot payload
+-------------------------------------------------
 Building U-Boot as a coreboot payload is just like building U-Boot for targets
 on other architectures, like below:
 

@@ -48,6 +49,8 @@ Change the 'Board configuration file' and 'Board Device Tree Source (dts) file'
 to point to a new board. You can also change the Cache-As-RAM (CAR) related
 settings here if the default values do not fit your new board.
 
+Build Instructions for U-Boot as BIOS replacement (bare mode)
+-------------------------------------------------------------
 Building a ROM version of U-Boot (hereafter referred to as u-boot.rom) is a
 little bit tricky, as generally it requires several binary blobs which are not
 shipped in the U-Boot source tree. Due to this reason, the u-boot.rom build is

@@ -58,7 +61,9 @@ $ export BUILD_ROM=y
 
 This tells the Makefile to build u-boot.rom as a target.
 
-Link-specific instructions:
+---
+
+Chromebook Link specific instructions for bare mode:
 
 First, you need the following binary blobs:
 

@@ -87,7 +92,9 @@ Now you can build U-Boot and obtain u-boot.rom:
 $ make chromebook_link_defconfig
 $ make all
 
-Intel Crown Bay specific instructions:
+---
+
+Intel Crown Bay specific instructions for bare mode:
 
 U-Boot support of Intel Crown Bay board [4] relies on a binary blob called
 Firmware Support Package [5] to perform all the necessary initialization steps

@@ -122,7 +129,9 @@ Now you can build U-Boot and obtain u-boot.rom
 $ make crownbay_defconfig
 $ make all
 
-Intel Minnowboard Max instructions:
+---
+
+Intel Minnowboard Max instructions for bare mode:
 
 This uses as FSP as with Crown Bay, except it is for the Atom E3800 series.
 Download this and get the .fd file (BAYTRAIL_FSP_GOLD_003_16-SEP-2014.fd at

@@ -188,8 +197,9 @@ Offset   Description         Controlling config
 
 Overall ROM image size is controlled by CONFIG_ROM_SIZE.
 
+---
 
-Intel Galileo instructions:
+Intel Galileo instructions for bare mode:
 
 Only one binary blob is needed for Remote Management Unit (RMU) within Intel
 Quark SoC. Not like FSP, U-Boot does not call into the binary. The binary is

@@ -252,8 +262,8 @@ At present it seems that for Minnowboard Max, coreboot does not pass through
 the video information correctly (it always says the resolution is 0x0). This
 works correctly for link though.
 

doc/README.x86 At present it seems that for Minnowboard Max, coreboot does not pass through

Quoted 8 lines

doc/README.x86 +2 -3

-Test with QEMU
---------------
+Test with QEMU for bare mode
+----------------------------
 QEMU is a fancy emulator that can enable us to test U-Boot without access to
 a real x86 board. Please make sure your QEMU version is 2.3.0 or above test
 U-Boot. To launch QEMU with u-boot.rom, call QEMU as follows:
--

Reviewed-by Bin Meng <[email protected]>