1.. zephyr:board:: qemu_x86
2
3Overview
4********
5
6The X86 QEMU board configuration is used to emulate the X86 architecture.
7
8This board configuration provides support for an x86 Minute IA (Lakemont) CPU
9and the following devices:
10
11* HPET
12* Advanced Programmable Interrupt Controller (APIC)
13* NS16550 UART
14
15
16Hardware
17********
18
19Supported Features
20==================
21
22This configuration supports the following hardware features:
23
24+--------------+------------+-----------------------+
25| Interface    | Controller | Driver/Component      |
26+==============+============+=======================+
27| HPET         | on-chip    | system clock          |
28+--------------+------------+-----------------------+
29| APIC         | on-chip    | interrupt controller  |
30+--------------+------------+-----------------------+
31| NS16550      | on-chip    | serial port           |
32| UART         |            |                       |
33+--------------+------------+-----------------------+
34
35Devices
36=======
37
38HPET System Clock Support
39-------------------------
40
41The configuration uses an HPET clock frequency of 25 MHz.
42
43Serial Port
44-----------
45
46The board configuration uses a single serial communication channel that
47uses the NS16550 serial driver operating in polling mode. To override, enable
48the UART_INTERRUPT_DRIVEN Kconfig option, which allows the system to be
49interrupt-driven.
50
51If SLIP networking is enabled (see below), an additional serial port will be
52used for it.
53
54Known Problems or Limitations
55=============================
56
57The following platform features are unsupported:
58
59* Isolated Memory Regions
60* Serial port in Direct Memory Access (DMA) mode
61* Serial Peripheral Interface (SPI) flash
62* General-Purpose Input/Output (GPIO)
63* Inter-Integrated Circuit (I2C)
64* Ethernet
65* Supervisor Mode Execution Protection (SMEP)
66
67Programming and Debugging
68*************************
69
70Applications for the ``qemu_x86`` board configuration can be built and run in
71the usual way for emulated boards (see :ref:`build_an_application` and
72:ref:`application_run` for more details).
73
74Flashing
75========
76
77While this board is emulated and you can't "flash" it, you can use this
78configuration to run basic Zephyr applications and kernel tests in the QEMU
79emulated environment. For example, with the :zephyr:code-sample:`synchronization` sample:
80
81.. zephyr-app-commands::
82   :zephyr-app: samples/synchronization
83   :host-os: unix
84   :board: qemu_x86
85   :goals: run
86
87This will build an image with the synchronization sample app, boot it using
88QEMU, and display the following console output:
89
90.. code-block:: console
91
92        ***** BOOTING ZEPHYR OS v1.8.99 - BUILD: Jun 27 2017 13:09:26 *****
93        threadA: Hello World from x86!
94        threadB: Hello World from x86!
95        threadA: Hello World from x86!
96        threadB: Hello World from x86!
97        threadA: Hello World from x86!
98        threadB: Hello World from x86!
99        threadA: Hello World from x86!
100        threadB: Hello World from x86!
101        threadA: Hello World from x86!
102        threadB: Hello World from x86!
103
104Exit QEMU by pressing :kbd:`CTRL+A` :kbd:`x`.
105
106For qemu_x86_64 platform, it also supports to use UEFI bootable method
107to run Zephyr applications and kernel tests, but you need to set up
108some environment configurations as follows:
109
110* Please install uefi-run in your system environment according to this
111  reference link https://github.com/Richard-W/uefi-run. Note that uefi-run
112  from snapstore may not work because of strict snap confinements.
113  The preferred method is installing with cargo.
114
115* Please install OVMF in your system environment according to this
116  reference link https://github.com/tianocore/tianocore.github.io/wiki/OVMF.
117  The easiest way is to install a special ``ovmf`` package found in many distros.
118  For example, use the following command in Ubuntu:
119
120  .. code-block:: console
121
122     sudo apt install ovmf
123
124* Set system environment variable OVMF_FD_PATH,
125  for example:
126
127  .. code-block:: console
128
129     export OVMF_FD_PATH=/usr/share/OVMF/OVMF_CODE.fd
130
131Now you can build application, for example UEFI boot test sample found under
132:zephyr_file:`tests/boot/uefi`:
133
134.. zephyr-app-commands::
135   :zephyr-app: tests/boot/uefi
136   :host-os: unix
137   :board: qemu_x86_64
138   :goals: run
139
140This will build an image with the uefi boot test app, boot it on
141qemu_x86_64 using UEFI, and display the following console output:
142
143.. code-block:: console
144
145        UEFI Interactive Shell v2.2
146        EDK II
147        UEFI v2.70 (EDK II, 0x00010000)
148        Mapping table
149              FS0: Alias(s):F0a:;BLK0:
150                  PciRoot(0x0)/Pci(0x1,0x1)/Ata(0x0)
151             BLK1: Alias(s):
152                  PciRoot(0x0)/Pci(0x1,0x1)/Ata(0x0)
153        Press ESC in 1 seconds to skip startup.nsh or any other key to continue.
154        Starting UEFI application...
155        *** Zephyr EFI Loader ***
156        Zeroing 524544 bytes of memory at 0x105000
157        Copying 32768 data bytes to 0x1000 from image offset
158        Copying 20480 data bytes to 0x100000 from image offset 32768
159        Copying 540416 data bytes to 0x185100 from image offset 53248
160        Jumping to Entry Point: 0x112b (48 31 c0 48 31 d2 48)
161        *** Booting Zephyr OS build zephyr-v2.6.0-1472-g61810ec36d28  ***
162        Hello World! qemu_x86_64
163
164Exit QEMU by pressing :kbd:`CTRL+A` :kbd:`x`.
165
166Debugging
167=========
168
169Refer to the detailed overview about :ref:`application_debugging`.
170
171Networking
172==========
173
174The board supports SLIP networking over an emulated serial port
175(``CONFIG_NET_SLIP_TAP=y``). The detailed setup is described in
176:ref:`networking_with_qemu`.
177
178It is also possible to use the QEMU built-in Ethernet adapter to connect
179to the host system. This is faster than using SLIP and is also the preferred
180way. See :ref:`networking_with_eth_qemu` for details.
181