[PATCH v3 01/29] doc: Convert semihosting readme to rST

[Sean Anderson]

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 at 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