1.. SPDX-License-Identifier: GPL-2.0+
2.. Copyright 2014 Broadcom Corporation.
3
4Semihosting
5===========
6
7Semihosting is ARM's way of having a real or virtual target communicate
8with a host or host debugger for basic operations such as file I/O,
9console I/O, etc. Please see `Arm's semihosting documentation
10<https://developer.arm.com/documentation/100863/latest/>`_ for more
11information.
12
13Platform Support
14----------------
15
16Versatile Express
17^^^^^^^^^^^^^^^^^
18
19For developing on armv8 virtual fastmodel platforms, semihosting is a
20valuable tool since it allows access to image/configuration files before
21eMMC or other NV media are available.
22
23There are two main ARM virtual Fixed Virtual Platform (FVP) models,
24`Versatile Express (VE) FVP and BASE FVP
25<http://www.arm.com/products/tools/models/fast-models/foundation-model.php>`_.
26The initial vexpress64 u-boot board created here runs on the VE virtual
27platform using the license-free Foundation_v8 simulator. Fortunately,
28the Foundation_v8 simulator also supports the BASE_FVP model which
29companies can purchase licenses for and contain much more functionality.
30So we can, in U-Boot, run either model by either using the VE FVP (default),
31or turning on ``CONFIG_BASE_FVP`` for the more full featured model.
32
33Rather than create a new armv8 board similar to ``armltd/vexpress64``, add
34semihosting calls to the existing one, enabled with ``CONFIG_SEMIHOSTING``
35and ``CONFIG_BASE_FVP`` both set. Also reuse the existing board config file
36vexpress_aemv8.h but differentiate the two models by the presence or
37absence of ``CONFIG_BASE_FVP``. This change is tested and works on both the
38Foundation and Base fastmodel simulators.
39
40QEMU
41^^^^
42
43Another ARM emulator which supports semihosting is `QEMU
44<https://www.qemu.org/>`_. To enable semihosting, enable
45``CONFIG_SERIAL_PROBE_ALL`` when configuring U-Boot, and use
46``-semihosting`` when invoking QEMU. Adding ``-nographic`` can also be
47helpful. When using a semihosted serial console, QEMU will block waiting
48for input. This will cause the GUI to become unresponsive. To mitigate
49this, try adding ``-nographic``. For more information about building and
50running QEMU, refer to the :doc:`board documentation
51<../board/emulation/qemu-arm>`.
52
53OpenOCD
54^^^^^^^
55
56Any ARM platform can use semihosting with an attached debugger. One such
57debugger with good support for a variety of boards and JTAG adapters is
58`OpenOCD <https://openocd.org/>`_. Semihosting is not enabled by default,
59so you will need to enable it::
60
61    $ openocd -f <your board config> -c init -c halt -c \
62          'arm semihosting enable' -c resume
63
64Note that enabling semihosting can only be done after attaching to the
65board with ``init``, and must be done while the CPU is halted. For a more
66extended example, refer to the :ref:`LS1046ARDB docs <ls1046ardb_jtag>`.
67
68Loading files
69-------------
70
71The semihosting code adds a "semihosting filesystem"::
72
73  load hostfs - <address> <image>
74
75That will load an image from the host filesystem into RAM at the specified
76address. If you are using U-Boot SPL, you can also use ``BOOT_DEVICE_SMH``
77which will load ``CONFIG_SPL_FS_LOAD_PAYLOAD_NAME``.
78
79Host console
80------------
81
82U-Boot can use the host's console instead of a physical serial device by
83enabling ``CONFIG_SERIAL_SEMIHOSTING``. If you don't have
84``CONFIG_DM_SERIAL`` enabled, make sure you disable any other serial
85drivers.
86
87Migrating from ``smhload``
88--------------------------
89
90If you were using the ``smhload`` command, you can migrate commands like::
91
92    smhload <file> <address> [<end var>]
93
94to a generic load command like::
95
96    load hostfs - <address> <file>
97
98The ``load`` command will set the ``filesize`` variable with the size of
99the file. The ``fdt chosen`` command has been updated to take a size
100instead of an end address. If you were adding the initramfs to your device
101tree like::
102
103    fdt chosen <address> <end var>
104
105you can now run::
106
107    fdt chosen <address> $filesize
108