[PATCH 1/3] doc: usage: Convert README.vxworks to reST

[PATCH 1/3] doc: usage: Convert README.vxworks to reST

[Bin Meng]

This converts the existing README.vxworks to reST, and puts it under
the doc/usage/os directory.

Signed-off-by: Bin Meng <bmeng.cn@gmail.com>
---

 doc/usage/index.rst                          |  8 +++++++
 doc/{README.vxworks => usage/os/vxworks.rst} | 22 ++++++++++----------
 2 files changed, 19 insertions(+), 11 deletions(-)
 rename doc/{README.vxworks => usage/os/vxworks.rst} (93%)

diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index 0aacf531b2..b8916971bc 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -52,3 +52,11 @@ Shell commands
    size
    true
    ums
+
+Booting OS
+----------
+
+.. toctree::
+   :maxdepth: 1
+
+   os/vxworks
diff --git a/doc/README.vxworks b/doc/usage/os/vxworks.rst
similarity index 93%
rename from doc/README.vxworks
rename to doc/usage/os/vxworks.rst
index 12a0d744d8..e696c639b2 100644
--- a/doc/README.vxworks
+++ b/doc/usage/os/vxworks.rst
@@ -1,11 +1,10 @@
-# SPDX-License-Identifier: GPL-2.0+
-#
-# Copyright (C) 2013, Miao Yan <miao.yan@windriver.com>
-# Copyright (C) 2015-2018, Bin Meng <bmeng.cn@gmail.com>
-# Copyright (C) 2019, Lihua Zhao <lihua.zhao@windriver.com>
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright (C) 2013, Miao Yan <miao.yan@windriver.com>
+.. Copyright (C) 2015-2018, Bin Meng <bmeng.cn@gmail.com>
+.. Copyright (C) 2019, Lihua Zhao <lihua.zhao@windriver.com>
 
-VxWorks Support
-===============
+VxWorks
+=======
 
 This document describes the information about U-Boot loading VxWorks kernel.
 
@@ -20,7 +19,7 @@ With CONFIG_EFI_LOADER option, it's possible to chain load a VxWorks x86 kernel
 via the UEFI boot loader application for VxWorks loaded by 'bootefi' command.
 
 VxWorks 7 on PowerPC and ARM
----------------------------
+----------------------------
 From VxWorks 7, VxWorks starts adopting device tree as its hardware description
 mechanism (for PowerPC and ARM), thus requiring boot interface changes.
 This section will describe the new interface.
@@ -35,11 +34,11 @@ For legacy bootm flow, make sure the least significant bit of flags in bootargs
 is cleared. The calling convention is described below:
 
 For PowerPC, the calling convention of the new VxWorks entry point conforms to
-the ePAPR standard, which is shown below (see ePAPR for more details):
+the ePAPR standard, which is shown below (see ePAPR for more details)::
 
     void (*kernel_entry)(fdt_addr, 0, 0, EPAPR_MAGIC, boot_IMA, 0, 0)
 
-For ARM, the calling convention is shown below:
+For ARM, the calling convention is shown below::
 
     void (*kernel_entry)(void *fdt_addr)
 
@@ -47,7 +46,7 @@ When using the Linux compatible standard DTB, the calling convention of VxWorks
 entry point is exactly the same as the Linux kernel.
 
 When booting a VxWorks 7 kernel (uImage format), the parameters passed to bootm
-is like below:
+is like below::
 
     bootm <kernel image address> - <device tree address>
 
@@ -108,6 +107,7 @@ BIOS of the graphics card first.
       CONFIG_FRAMEBUFFER_SET_VESA_MODE need remain set but care must be taken
       at which VESA mode is to be set. The supported pixel format is 32-bit
       RGBA, hence the available VESA mode can only be one of the following:
+
         * FRAMEBUFFER_VESA_MODE_10F
         * FRAMEBUFFER_VESA_MODE_112
         * FRAMEBUFFER_VESA_MODE_115
-- 
2.25.1

[PATCH 2/3] doc: usage: Update vxworks doc to mention RISC-V support

[Bin Meng]

At present the doc only mentions Arm, PowerPC and x86. RISC-V support
has been added since VxWorks SR0650 support for a while, and U-Boot
supports loading a RISC-V VxWorks kernel too. Let's document it.

Signed-off-by: Bin Meng <bmeng.cn@gmail.com>
---

 doc/usage/os/vxworks.rst | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/doc/usage/os/vxworks.rst b/doc/usage/os/vxworks.rst
index e696c639b2..e732f711fb 100644
--- a/doc/usage/os/vxworks.rst
+++ b/doc/usage/os/vxworks.rst
@@ -13,13 +13,13 @@ Status
 U-Boot supports loading VxWorks kernels via 'bootvx' and 'bootm' commands.
 For booting old kernels (6.9.x) on PowerPC and ARM, and all kernel versions
 on other architectures, 'bootvx' shall be used. For booting VxWorks 7 kernels
-on PowerPC and ARM, 'bootm' shall be used.
+on PowerPC/ARM/RISC-V, 'bootm' shall be used.
 
 With CONFIG_EFI_LOADER option, it's possible to chain load a VxWorks x86 kernel
 via the UEFI boot loader application for VxWorks loaded by 'bootefi' command.
 
-VxWorks 7 on PowerPC and ARM
-----------------------------
+VxWorks 7 on PowerPC/ARM/RISC-V
+-------------------------------
 From VxWorks 7, VxWorks starts adopting device tree as its hardware description
 mechanism (for PowerPC and ARM), thus requiring boot interface changes.
 This section will describe the new interface.
@@ -45,6 +45,11 @@ For ARM, the calling convention is shown below::
 When using the Linux compatible standard DTB, the calling convention of VxWorks
 entry point is exactly the same as the Linux kernel.
 
+For RISC-V, there is no legacy bootm flow as VxWorks always uses the same boot
+interface as the Linux kernel, with the calling convention below::
+
+    void (*kernel_entry)(unsigned long hartid, void *fdt_addr)
+
 When booting a VxWorks 7 kernel (uImage format), the parameters passed to bootm
 is like below::
 
-- 
2.25.1

Re: [PATCH 2/3] doc: usage: Update vxworks doc to mention RISC-V support

[Heinrich Schuchardt]

On 3/28/22 04:43, Bin Meng wrote:
> At present the doc only mentions Arm, PowerPC and x86. RISC-V support
> has been added since VxWorks SR0650 support for a while, and U-Boot
> supports loading a RISC-V VxWorks kernel too. Let's document it.
> 
> Signed-off-by: Bin Meng <bmeng.cn@gmail.com>
> ---
> 
>   doc/usage/os/vxworks.rst | 11 ++++++++---
>   1 file changed, 8 insertions(+), 3 deletions(-)
> 
> diff --git a/doc/usage/os/vxworks.rst b/doc/usage/os/vxworks.rst
> index e696c639b2..e732f711fb 100644
> --- a/doc/usage/os/vxworks.rst
> +++ b/doc/usage/os/vxworks.rst
> @@ -13,13 +13,13 @@ Status
>   U-Boot supports loading VxWorks kernels via 'bootvx' and 'bootm' commands.
>   For booting old kernels (6.9.x) on PowerPC and ARM, and all kernel versions
>   on other architectures, 'bootvx' shall be used. For booting VxWorks 7 kernels

A man-page for bootvx might be useful.

> -on PowerPC and ARM, 'bootm' shall be used.
> +on PowerPC/ARM/RISC-V, 'bootm' shall be used.
>   
>   With CONFIG_EFI_LOADER option, it's possible to chain load a VxWorks x86 kernel
>   via the UEFI boot loader application for VxWorks loaded by 'bootefi' command.
>   
> -VxWorks 7 on PowerPC and ARM
> -----------------------------
> +VxWorks 7 on PowerPC/ARM/RISC-V
> +-------------------------------
>   From VxWorks 7, VxWorks starts adopting device tree as its hardware description
>   mechanism (for PowerPC and ARM), thus requiring boot interface changes.
>   This section will describe the new interface.
> @@ -45,6 +45,11 @@ For ARM, the calling convention is shown below::
>   When using the Linux compatible standard DTB, the calling convention of VxWorks
>   entry point is exactly the same as the Linux kernel.
>   
> +For RISC-V, there is no legacy bootm flow as VxWorks always uses the same boot
> +interface as the Linux kernel, with the calling convention below::
> +

Nits: .. code-block:: C

Reviewed-by: Heinrich Schuchardt <xypron.glpk@gmx.de>

> +    void (*kernel_entry)(unsigned long hartid, void *fdt_addr)
> +
>   When booting a VxWorks 7 kernel (uImage format), the parameters passed to bootm
>   is like below::
>   

[PATCH 3/3] doc: usage: Convert README.plan9 to reST

[Bin Meng]

This converts the existing README.plan9 to reST, and puts it under
the doc/usage/os directory.

Signed-off-by: Bin Meng <bmeng.cn@gmail.com>
---

 doc/usage/index.rst                      |  1 +
 doc/{README.plan9 => usage/os/plan9.rst} | 12 ++++++++----
 2 files changed, 9 insertions(+), 4 deletions(-)
 rename doc/{README.plan9 => usage/os/plan9.rst} (89%)

diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index b8916971bc..ecb4908fd1 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -59,4 +59,5 @@ Booting OS
 .. toctree::
    :maxdepth: 1
 
+   os/plan9
    os/vxworks
diff --git a/doc/README.plan9 b/doc/usage/os/plan9.rst
similarity index 89%
rename from doc/README.plan9
rename to doc/usage/os/plan9.rst
index 2d3d0e0cf6..f91712c009 100644
--- a/doc/README.plan9
+++ b/doc/usage/os/plan9.rst
@@ -1,3 +1,10 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Steven Stallion
+.. June 2013
+
+Plan 9
+======
+
 Plan 9 from Bell Labs kernel images require additional setup to pass
 configuration information to the kernel.  An environment variable named
 confaddr must be defined with the same value as CONFADDR (see mem.h).
@@ -10,9 +17,6 @@ bootargs environment variable will be copied.
 
 If no command line arguments or bootargs are defined, CONFADDR is left
 uninitialized to permit manual configuration.  For example, PC-style
-configuration could be simulated by issuing a fatload in bootcmd:
+configuration could be simulated by issuing a fatload in bootcmd::
 
   # setenv bootcmd fatload mmc 0 $confaddr plan9.ini; ...; bootm
-
-Steven Stallion
-June 2013
-- 
2.25.1

Re: [PATCH 3/3] doc: usage: Convert README.plan9 to reST

[Heinrich Schuchardt]

On 3/28/22 04:43, Bin Meng wrote:
> This converts the existing README.plan9 to reST, and puts it under
> the doc/usage/os directory.
> 
> Signed-off-by: Bin Meng <bmeng.cn@gmail.com>
> ---
> 
>   doc/usage/index.rst                      |  1 +
>   doc/{README.plan9 => usage/os/plan9.rst} | 12 ++++++++----
>   2 files changed, 9 insertions(+), 4 deletions(-)
>   rename doc/{README.plan9 => usage/os/plan9.rst} (89%)
> 
> diff --git a/doc/usage/index.rst b/doc/usage/index.rst
> index b8916971bc..ecb4908fd1 100644
> --- a/doc/usage/index.rst
> +++ b/doc/usage/index.rst
> @@ -59,4 +59,5 @@ Booting OS
>   .. toctree::
>      :maxdepth: 1
>   
> +   os/plan9
>      os/vxworks
> diff --git a/doc/README.plan9 b/doc/usage/os/plan9.rst
> similarity index 89%
> rename from doc/README.plan9
> rename to doc/usage/os/plan9.rst
> index 2d3d0e0cf6..f91712c009 100644
> --- a/doc/README.plan9
> +++ b/doc/usage/os/plan9.rst
> @@ -1,3 +1,10 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +.. Steven Stallion
> +.. June 2013
> +
> +Plan 9
> +======
> +
>   Plan 9 from Bell Labs kernel images require additional setup to pass

Does U-Boot support any hardware that Plan 9 supports?

Or can we simply drop this document?

>   configuration information to the kernel.  An environment variable named
>   confaddr must be defined with the same value as CONFADDR (see mem.h).
> @@ -10,9 +17,6 @@ bootargs environment variable will be copied.
>   
>   If no command line arguments or bootargs are defined, CONFADDR is left
>   uninitialized to permit manual configuration.  For example, PC-style
> -configuration could be simulated by issuing a fatload in bootcmd:
> +configuration could be simulated by issuing a fatload in bootcmd::
>   
>     # setenv bootcmd fatload mmc 0 $confaddr plan9.ini; ...; bootm

Is this prompt correct?
I cannot find any defconfig where CONFIG_SYS_PROMPT="# ".

Best regards

Heinrich

> -
> -Steven Stallion
> -June 2013

Re: [PATCH 3/3] doc: usage: Convert README.plan9 to reST

[Heinrich Schuchardt]

On 3/29/22 19:11, Heinrich Schuchardt wrote:
> On 3/28/22 04:43, Bin Meng wrote:
>> This converts the existing README.plan9 to reST, and puts it under
>> the doc/usage/os directory.
>>
>> Signed-off-by: Bin Meng <bmeng.cn@gmail.com>
>> ---
>>
>>   doc/usage/index.rst                      |  1 +
>>   doc/{README.plan9 => usage/os/plan9.rst} | 12 ++++++++----
>>   2 files changed, 9 insertions(+), 4 deletions(-)
>>   rename doc/{README.plan9 => usage/os/plan9.rst} (89%)
>>
>> diff --git a/doc/usage/index.rst b/doc/usage/index.rst
>> index b8916971bc..ecb4908fd1 100644
>> --- a/doc/usage/index.rst
>> +++ b/doc/usage/index.rst
>> @@ -59,4 +59,5 @@ Booting OS
>>   .. toctree::
>>      :maxdepth: 1
>> +   os/plan9
>>      os/vxworks
>> diff --git a/doc/README.plan9 b/doc/usage/os/plan9.rst
>> similarity index 89%
>> rename from doc/README.plan9
>> rename to doc/usage/os/plan9.rst
>> index 2d3d0e0cf6..f91712c009 100644
>> --- a/doc/README.plan9
>> +++ b/doc/usage/os/plan9.rst
>> @@ -1,3 +1,10 @@
>> +.. SPDX-License-Identifier: GPL-2.0+
>> +.. Steven Stallion
>> +.. June 2013
>> +
>> +Plan 9
>> +======
>> +
>>   Plan 9 from Bell Labs kernel images require additional setup to pass
>
> Does U-Boot support any hardware that Plan 9 supports?

https://p9f.org/magic/man2html/8/booting describes the Raspberry Pi and
OMAP3 as supported by Plan 9.

http://9p.io/sources/contrib/miller/9pi.img.gz
is meant to be an image for the Raspberry Pi. See description at
https://bendyworks.com/blog/getting-plan-9-running-on-the-raspberry-pi

So let's keep this document.

Reviewed-by: Heinrich Schuchardt <xypron.glpk@gmx.de>

>
> Or can we simply drop this document?
>
>>   configuration information to the kernel.  An environment variable named
>>   confaddr must be defined with the same value as CONFADDR (see mem.h).
>> @@ -10,9 +17,6 @@ bootargs environment variable will be copied.
>>   If no command line arguments or bootargs are defined, CONFADDR is left
>>   uninitialized to permit manual configuration.  For example, PC-style
>> -configuration could be simulated by issuing a fatload in bootcmd:
>> +configuration could be simulated by issuing a fatload in bootcmd::
>>     # setenv bootcmd fatload mmc 0 $confaddr plan9.ini; ...; bootm
>
> Is this prompt correct?
> I cannot find any defconfig where CONFIG_SYS_PROMPT="# ".
>
> Best regards
>
> Heinrich
>
>> -
>> -Steven Stallion
>> -June 2013
>

Re: [PATCH 1/3] doc: usage: Convert README.vxworks to reST

[Heinrich Schuchardt]

On 3/28/22 04:43, Bin Meng wrote:
> This converts the existing README.vxworks to reST, and puts it under
> the doc/usage/os directory.
> 
> Signed-off-by: Bin Meng <bmeng.cn@gmail.com>
> ---
> 
>   doc/usage/index.rst                          |  8 +++++++
>   doc/{README.vxworks => usage/os/vxworks.rst} | 22 ++++++++++----------
>   2 files changed, 19 insertions(+), 11 deletions(-)
>   rename doc/{README.vxworks => usage/os/vxworks.rst} (93%)
> 
> diff --git a/doc/usage/index.rst b/doc/usage/index.rst
> index 0aacf531b2..b8916971bc 100644
> --- a/doc/usage/index.rst
> +++ b/doc/usage/index.rst
> @@ -52,3 +52,11 @@ Shell commands
>      size
>      true
>      ums
> +
> +Booting OS
> +----------
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   os/vxworks
> diff --git a/doc/README.vxworks b/doc/usage/os/vxworks.rst
> similarity index 93%
> rename from doc/README.vxworks
> rename to doc/usage/os/vxworks.rst
> index 12a0d744d8..e696c639b2 100644
> --- a/doc/README.vxworks
> +++ b/doc/usage/os/vxworks.rst
> @@ -1,11 +1,10 @@
> -# SPDX-License-Identifier: GPL-2.0+
> -#
> -# Copyright (C) 2013, Miao Yan <miao.yan@windriver.com>
> -# Copyright (C) 2015-2018, Bin Meng <bmeng.cn@gmail.com>
> -# Copyright (C) 2019, Lihua Zhao <lihua.zhao@windriver.com>
> +.. SPDX-License-Identifier: GPL-2.0+
> +.. Copyright (C) 2013, Miao Yan <miao.yan@windriver.com>
> +.. Copyright (C) 2015-2018, Bin Meng <bmeng.cn@gmail.com>
> +.. Copyright (C) 2019, Lihua Zhao <lihua.zhao@windriver.com>
>   
> -VxWorks Support
> -===============
> +VxWorks
> +=======
>   
>   This document describes the information about U-Boot loading VxWorks kernel.
>   
> @@ -20,7 +19,7 @@ With CONFIG_EFI_LOADER option, it's possible to chain load a VxWorks x86 kernel
>   via the UEFI boot loader application for VxWorks loaded by 'bootefi' command.
>   
>   VxWorks 7 on PowerPC and ARM
> ----------------------------
> +----------------------------
>   From VxWorks 7, VxWorks starts adopting device tree as its hardware description
>   mechanism (for PowerPC and ARM), thus requiring boot interface changes.
>   This section will describe the new interface.
> @@ -35,11 +34,11 @@ For legacy bootm flow, make sure the least significant bit of flags in bootargs
>   is cleared. The calling convention is described below:
>   
>   For PowerPC, the calling convention of the new VxWorks entry point conforms to
> -the ePAPR standard, which is shown below (see ePAPR for more details):
> +the ePAPR standard, which is shown below (see ePAPR for more details)::

.. code-block:: c

Nits: Syntaxhighlighting depends on specifying the language.

>   
>       void (*kernel_entry)(fdt_addr, 0, 0, EPAPR_MAGIC, boot_IMA, 0, 0)
>   
> -For ARM, the calling convention is shown below:
> +For ARM, the calling convention is shown below::

.. code-block:: c

Reviewed-by: Heinrich Schuchardt <xypron.glpk@gmx.de>

>   
>       void (*kernel_entry)(void *fdt_addr)
>   
> @@ -47,7 +46,7 @@ When using the Linux compatible standard DTB, the calling convention of VxWorks
>   entry point is exactly the same as the Linux kernel.
>   
>   When booting a VxWorks 7 kernel (uImage format), the parameters passed to bootm
> -is like below:
> +is like below::
>   
>       bootm <kernel image address> - <device tree address>
>   
> @@ -108,6 +107,7 @@ BIOS of the graphics card first.
>         CONFIG_FRAMEBUFFER_SET_VESA_MODE need remain set but care must be taken
>         at which VESA mode is to be set. The supported pixel format is 32-bit
>         RGBA, hence the available VESA mode can only be one of the following:
> +
>           * FRAMEBUFFER_VESA_MODE_10F
>           * FRAMEBUFFER_VESA_MODE_112
>           * FRAMEBUFFER_VESA_MODE_115