| Message ID | 20220322205938.1721846-2-sean.anderson@seco.com |
|---|---|
| State | Accepted |
| Commit | d0ed9b10810f17c5b5cb2ee962c6d4df29a65a9c |
| Delegated to: | Tom Rini |
| Headers | show |
| Series | arm: semihosting: Cleanups and new features | expand |
On 3/22/22 21:59, Sean Anderson wrote: > This converts the semihosting readme to rST. I have tried to make only > cosmetic changes, but I did fix up the first link (which was broken). > > Signed-off-by: Sean Anderson <sean.anderson@seco.com> > --- > > (no changes since v1) > > doc/usage/index.rst | 1 + > .../semihosting.rst} | 35 +++++++++++-------- > 2 files changed, 21 insertions(+), 15 deletions(-) > rename doc/{README.semihosting => usage/semihosting.rst} (53%) > > diff --git a/doc/usage/index.rst b/doc/usage/index.rst > index 750102830b..bfa59f2217 100644 > --- a/doc/usage/index.rst > +++ b/doc/usage/index.rst > @@ -11,6 +11,7 @@ Use U-Boot > netconsole > partitions > cmdline > + semihosting > > Shell commands > -------------- > diff --git a/doc/README.semihosting b/doc/usage/semihosting.rst > similarity index 53% > rename from doc/README.semihosting > rename to doc/usage/semihosting.rst > index f382d0131e..ed16e4d582 100644 > --- a/doc/README.semihosting > +++ b/doc/usage/semihosting.rst > @@ -1,35 +1,40 @@ > -SPDX-License-Identifier: GPL-2.0+ > -/* > - * Copyright 2014 Broadcom Corporation. > - */ > +.. SPDX-License-Identifier: GPL-2.0+ > +.. Copyright 2014 Broadcom Corporation. > + > +Semihosting > +=========== > > Semihosting is ARM's way of having a real or virtual target communicate Thank you for starting the conversion. I think this document needs some rework in a future patch: Semihosting is not ARM specific. See https://qemu.readthedocs.io/en/latest/system/invocation.html > with a host or host debugger for basic operations such as file I/O, > -console I/O, etc. Please see > -http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0471c/Bgbjjgij.html for more information. > +console I/O, etc. Please see `Arm's semihosting documentation > +<https://developer.arm.com/documentation/100863/latest/>`_ for more > +information. > > For developing on armv8 virtual fastmodel platforms, semihosting is a > valuable tool since it allows access to image/configuration files before > eMMC or other NV media are available. > > There are two main ARM virtual Fixed Virtual Platform (FVP) models, > -Versatile Express (VE) FVP and BASE FVP (See > -http://www.arm.com/products/tools/models/fast-models/foundation-model.php) > +`Versatile Express (VE) FVP and BASE FVP > +<http://www.arm.com/products/tools/models/fast-models/foundation-model.php>`_. > The initial vexpress64 u-boot board created here runs on the VE virtual > platform using the license-free Foundation_v8 simulator. Fortunately, > the Foundation_v8 simulator also supports the BASE_FVP model which > companies can purchase licenses for and contain much more functionality. This does not capture the usage of QEMU's semihosting at all. > -So we can, in u-boot, run either model by either using the VE FVP (default), > -or turning on CONFIG_BASE_FVP for the more full featured model. > +So we can, in U-Boot, run either model by either using the VE FVP (default), > +or turning on ``CONFIG_BASE_FVP`` for the more full featured model. > > -Rather than create a new armv8 board similar to armltd/vexpress64, add > -semihosting calls to the existing one, enabled with CONFIG_SEMIHOSTING > -and CONFIG_BASE_FVP both set. Also reuse the existing board config file > +Rather than create a new armv8 board similar to ``armltd/vexpress64``, add %s/create/creating/ > +semihosting calls to the existing one, enabled with ``CONFIG_SEMIHOSTING`` > +and ``CONFIG_BASE_FVP`` both set. Also reuse the existing board config file > vexpress_aemv8.h but differentiate the two models by the presence or > -absence of CONFIG_BASE_FVP. This change is tested and works on both the > +absence of ``CONFIG_BASE_FVP``. This change is tested and works on both the > Foundation and Base fastmodel simulators. > > -The semihosting code adds a command: > +Loading files > +------------- > + > +The semihosting code adds a "hostfs":: Do you mean: "Semihosting provides access to the host file system via the smhload command:" > > smhload <image> <address> [env var] > Can this command be removed once you can bind semihosting as a host filesystem (patch 12/29)? It seems duplicate to 'load host'. Best regards Heinrich
On 3/22/22 6:05 PM, Heinrich Schuchardt wrote: > On 3/22/22 21:59, Sean Anderson wrote: >> This converts the semihosting readme to rST. I have tried to make only >> cosmetic changes, but I did fix up the first link (which was broken). >> >> Signed-off-by: Sean Anderson <sean.anderson@seco.com> >> --- >> >> (no changes since v1) >> >> doc/usage/index.rst | 1 + >> .../semihosting.rst} | 35 +++++++++++-------- >> 2 files changed, 21 insertions(+), 15 deletions(-) >> rename doc/{README.semihosting => usage/semihosting.rst} (53%) >> >> diff --git a/doc/usage/index.rst b/doc/usage/index.rst >> index 750102830b..bfa59f2217 100644 >> --- a/doc/usage/index.rst >> +++ b/doc/usage/index.rst >> @@ -11,6 +11,7 @@ Use U-Boot >> netconsole >> partitions >> cmdline >> + semihosting >> >> Shell commands >> -------------- >> diff --git a/doc/README.semihosting b/doc/usage/semihosting.rst >> similarity index 53% >> rename from doc/README.semihosting >> rename to doc/usage/semihosting.rst >> index f382d0131e..ed16e4d582 100644 >> --- a/doc/README.semihosting >> +++ b/doc/usage/semihosting.rst >> @@ -1,35 +1,40 @@ >> -SPDX-License-Identifier: GPL-2.0+ >> -/* >> - * Copyright 2014 Broadcom Corporation. >> - */ >> +.. SPDX-License-Identifier: GPL-2.0+ >> +.. Copyright 2014 Broadcom Corporation. >> + >> +Semihosting >> +=========== >> >> Semihosting is ARM's way of having a real or virtual target communicate > > Thank you for starting the conversion. I think this document needs some > rework in a future patch: > > Semihosting is not ARM specific. See > https://qemu.readthedocs.io/en/latest/system/invocation.html Ah, I was only aware of the RISC-V version (which is basically ARM but with a different trap instruction). However, for this patch I am trying not to modify the original source of this file too much (except to fix the links and maybe some spelling). >> with a host or host debugger for basic operations such as file I/O, >> -console I/O, etc. Please see >> -http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0471c/Bgbjjgij.html for more information. >> +console I/O, etc. Please see `Arm's semihosting documentation >> +<https://developer.arm.com/documentation/100863/latest/>`_ for more >> +information. >> >> For developing on armv8 virtual fastmodel platforms, semihosting is a >> valuable tool since it allows access to image/configuration files before >> eMMC or other NV media are available. >> >> There are two main ARM virtual Fixed Virtual Platform (FVP) models, >> -Versatile Express (VE) FVP and BASE FVP (See >> -http://www.arm.com/products/tools/models/fast-models/foundation-model.php) >> +`Versatile Express (VE) FVP and BASE FVP >> +<http://www.arm.com/products/tools/models/fast-models/foundation-model.php>`_. >> The initial vexpress64 u-boot board created here runs on the VE virtual >> platform using the license-free Foundation_v8 simulator. Fortunately, >> the Foundation_v8 simulator also supports the BASE_FVP model which >> companies can purchase licenses for and contain much more functionality. > > This does not capture the usage of QEMU's semihosting at all. > >> -So we can, in u-boot, run either model by either using the VE FVP (default), >> -or turning on CONFIG_BASE_FVP for the more full featured model. >> +So we can, in U-Boot, run either model by either using the VE FVP (default), >> +or turning on ``CONFIG_BASE_FVP`` for the more full featured model. >> >> -Rather than create a new armv8 board similar to armltd/vexpress64, add >> -semihosting calls to the existing one, enabled with CONFIG_SEMIHOSTING >> -and CONFIG_BASE_FVP both set. Also reuse the existing board config file >> +Rather than create a new armv8 board similar to ``armltd/vexpress64``, add > > %s/create/creating/ This is correct (though clumsy). >> +semihosting calls to the existing one, enabled with ``CONFIG_SEMIHOSTING`` >> +and ``CONFIG_BASE_FVP`` both set. Also reuse the existing board config file >> vexpress_aemv8.h but differentiate the two models by the presence or >> -absence of CONFIG_BASE_FVP. This change is tested and works on both the >> +absence of ``CONFIG_BASE_FVP``. This change is tested and works on both the >> Foundation and Base fastmodel simulators. >> >> -The semihosting code adds a command: >> +Loading files >> +------------- >> + >> +The semihosting code adds a "hostfs":: > > Do you mean: > > "Semihosting provides access to the host file system via the smhload > command:" Yes, that is better, though I think I accidentally changed the wording here when creating this commit. >> >> smhload <image> <address> [env var] >> > Can this command be removed once you can bind semihosting as a host > filesystem (patch 12/29)? It seems duplicate to 'load host'. Yes. See patch 17/29. --Sean
On Tue, Mar 22, 2022 at 04:59:09PM -0400, Sean Anderson wrote: > This converts the semihosting readme to rST. I have tried to make only > cosmetic changes, but I did fix up the first link (which was broken). > > Signed-off-by: Sean Anderson <sean.anderson@seco.com> Applied to u-boot/next, thanks!
diff --git a/doc/usage/index.rst b/doc/usage/index.rst index 750102830b..bfa59f2217 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -11,6 +11,7 @@ Use U-Boot netconsole partitions cmdline + semihosting Shell commands -------------- diff --git a/doc/README.semihosting b/doc/usage/semihosting.rst similarity index 53% rename from doc/README.semihosting rename to doc/usage/semihosting.rst index f382d0131e..ed16e4d582 100644 --- a/doc/README.semihosting +++ b/doc/usage/semihosting.rst @@ -1,35 +1,40 @@ -SPDX-License-Identifier: GPL-2.0+ -/* - * Copyright 2014 Broadcom Corporation. - */ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2014 Broadcom Corporation. + +Semihosting +=========== Semihosting is ARM's way of having a real or virtual target communicate with a host or host debugger for basic operations such as file I/O, -console I/O, etc. Please see -http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0471c/Bgbjjgij.html for more information. +console I/O, etc. Please see `Arm's semihosting documentation +<https://developer.arm.com/documentation/100863/latest/>`_ for more +information. For developing on armv8 virtual fastmodel platforms, semihosting is a valuable tool since it allows access to image/configuration files before eMMC or other NV media are available. There are two main ARM virtual Fixed Virtual Platform (FVP) models, -Versatile Express (VE) FVP and BASE FVP (See -http://www.arm.com/products/tools/models/fast-models/foundation-model.php) +`Versatile Express (VE) FVP and BASE FVP +<http://www.arm.com/products/tools/models/fast-models/foundation-model.php>`_. The initial vexpress64 u-boot board created here runs on the VE virtual platform using the license-free Foundation_v8 simulator. Fortunately, the Foundation_v8 simulator also supports the BASE_FVP model which companies can purchase licenses for and contain much more functionality. -So we can, in u-boot, run either model by either using the VE FVP (default), -or turning on CONFIG_BASE_FVP for the more full featured model. +So we can, in U-Boot, run either model by either using the VE FVP (default), +or turning on ``CONFIG_BASE_FVP`` for the more full featured model. -Rather than create a new armv8 board similar to armltd/vexpress64, add -semihosting calls to the existing one, enabled with CONFIG_SEMIHOSTING -and CONFIG_BASE_FVP both set. Also reuse the existing board config file +Rather than create a new armv8 board similar to ``armltd/vexpress64``, add +semihosting calls to the existing one, enabled with ``CONFIG_SEMIHOSTING`` +and ``CONFIG_BASE_FVP`` both set. Also reuse the existing board config file vexpress_aemv8.h but differentiate the two models by the presence or -absence of CONFIG_BASE_FVP. This change is tested and works on both the +absence of ``CONFIG_BASE_FVP``. This change is tested and works on both the Foundation and Base fastmodel simulators. -The semihosting code adds a command: +Loading files +------------- + +The semihosting code adds a "hostfs":: smhload <image> <address> [env var]
This converts the semihosting readme to rST. I have tried to make only cosmetic changes, but I did fix up the first link (which was broken). Signed-off-by: Sean Anderson <sean.anderson@seco.com> --- (no changes since v1) doc/usage/index.rst | 1 + .../semihosting.rst} | 35 +++++++++++-------- 2 files changed, 21 insertions(+), 15 deletions(-) rename doc/{README.semihosting => usage/semihosting.rst} (53%)