This documents how to use semihosting, the new semihosting features, and how to migrate from smhload.
Signed-off-by: Sean Anderson sean.anderson@seco.com ---
Changes in v3: - Add additional documentation for QEMU and OpenOCD - Add dummy device number for hostfs
Changes in v2: - Add migration instructions for smhload
doc/usage/semihosting.rst | 71 ++++++++++++++++++++++++++++++++++++--- 1 file changed, 67 insertions(+), 4 deletions(-)
diff --git a/doc/usage/semihosting.rst b/doc/usage/semihosting.rst index ed16e4d582..1d793983a7 100644 --- a/doc/usage/semihosting.rst +++ b/doc/usage/semihosting.rst @@ -10,6 +10,12 @@ console I/O, etc. Please see `Arm's semihosting documentation https://developer.arm.com/documentation/100863/latest/`_ for more information.
+Platform Support +---------------- + +Versatile Express +^^^^^^^^^^^^^^^^^ + 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. @@ -31,13 +37,70 @@ 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 Foundation and Base fastmodel simulators.
+QEMU +^^^^ + +Another ARM emulator which supports semihosting is `QEMU +https://www.qemu.org/`_. To enable semihosting, enable +``CONFIG_SERIAL_PROBE_ALL`` when configuring U-Boot, and use +``-semihosting`` when invoking QEMU. Adding ``-nographic`` can also be +helpful. When using a semihosted serial console, QEMU will block waiting +for input. This will cause the GUI to become unresponsive. To mitigate +this, try adding ``-nographic``. For more information about building and +running QEMU, refer to the :doc:`board documentation +<../board/emulation/qemu-arm>`. + +OpenOCD +^^^^^^^ + +Any ARM platform can use semihosting with an attached debugger. One such +debugger with good support for a variety of boards and JTAG adapters is +`OpenOCD https://openocd.org/`_. Semihosting is not enabled by default, +so you will need to enable it:: + + $ openocd -f <your board config> -c init -c halt -c \ + 'arm semihosting enable' -c resume + +Note that enabling semihosting can only be done after attaching to the +board with ``init``, and must be done while the CPU is halted. + Loading files -------------
-The semihosting code adds a "hostfs":: +The semihosting code adds a "semihosting filesystem"::
- smhload <image> <address> [env var] + load hostfs - <address> <image>
That will load an image from the host filesystem into RAM at the specified -address and optionally store the load end address in the specified -environment variable. +address. If you are using U-Boot SPL, you can also use ``BOOT_DEVICE_SMH`` +which will load ``CONFIG_SPL_FS_LOAD_PAYLOAD_NAME``. + +Host console +------------ + +U-Boot can use the host's console instead of a physical serial device by +enabling ``CONFIG_SERIAL_SEMIHOSTING``. If you don't have +``CONFIG_DM_SERIAL`` enabled, make sure you disable any other serial +drivers. + +Migrating from ``smhload`` +-------------------------- + +If you were using the ``smhload`` command, you can migrate commands like:: + + smhload <file> <address> [<end var>] + +to a generic load command like:: + + load hostfs - <address> <file> + +The ``load`` command will set the ``filesize`` variable with the size of +the file. The ``fdt chosen`` command has been updated to take a size +instead of an end address. If you were adding the initramfs to your device +tree like:: + + fdt chosen <address> <end var> + +you can now run:: + + fdt chosen <address> $filesize