doc/usage/semihosting.rst

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