[U-Boot] [PATCH 29/50] doc: board: Add QEMU x86 board doc

[Bin Meng <bmeng.cn@gmail.com>]

This extracts QEMU x86 board specific information from README.x86,
converts plain text documentation to reST format and adds it to
Sphinx TOC tree. No essential content change.

Signed-off-by: Bin Meng <bmeng.cn@gmail.com>
---

 doc/README.x86                   |  93 -----------------------------------
 doc/board/emulation/index.rst    |   9 ++++
 doc/board/emulation/qemu-x86.rst | 101 +++++++++++++++++++++++++++++++++++++++
 doc/board/index.rst              |   1 +
 4 files changed, 111 insertions(+), 93 deletions(-)
 create mode 100644 doc/board/emulation/index.rst
 create mode 100644 doc/board/emulation/qemu-x86.rst

diff --git a/doc/README.x86 b/doc/README.x86
index c987439..8cee320 100644
--- a/doc/README.x86
+++ b/doc/README.x86
@@ -57,99 +57,6 @@ Both tell the Makefile to build u-boot.rom as a target.
 
 ---
 
-QEMU x86 target instructions for bare mode:
-
-To build u-boot.rom for QEMU x86 targets, just simply run
-
-$ make qemu-x86_defconfig (for 32-bit)
-or
-$ make qemu-x86_64_defconfig (for 64-bit)
-$ make all
-
-Note this default configuration will build a U-Boot for the QEMU x86 i440FX
-board. To build a U-Boot against QEMU x86 Q35 board, you can change the build
-configuration during the 'make menuconfig' process like below:
-
-Device Tree Control  --->
-	...
-	(qemu-x86_q35) Default Device Tree for DT control
-
-Test with QEMU for bare mode
-----------------------------
-QEMU is a fancy emulator that can enable us to test U-Boot without access to
-a real x86 board. Please make sure your QEMU version is 2.3.0 or above test
-U-Boot. To launch QEMU with u-boot.rom, call QEMU as follows:
-
-$ qemu-system-i386 -nographic -bios path/to/u-boot.rom
-
-This will instantiate an emulated x86 board with i440FX and PIIX chipset. QEMU
-also supports emulating an x86 board with Q35 and ICH9 based chipset, which is
-also supported by U-Boot. To instantiate such a machine, call QEMU with:
-
-$ qemu-system-i386 -nographic -bios path/to/u-boot.rom -M q35
-
-Note by default QEMU instantiated boards only have 128 MiB system memory. But
-it is enough to have U-Boot boot and function correctly. You can increase the
-system memory by pass '-m' parameter to QEMU if you want more memory:
-
-$ qemu-system-i386 -nographic -bios path/to/u-boot.rom -m 1024
-
-This creates a board with 1 GiB system memory. Currently U-Boot for QEMU only
-supports 3 GiB maximum system memory and reserves the last 1 GiB address space
-for PCI device memory-mapped I/O and other stuff, so the maximum value of '-m'
-would be 3072.
-
-QEMU emulates a graphic card which U-Boot supports. Removing '-nographic' will
-show QEMU's VGA console window. Note this will disable QEMU's serial output.
-If you want to check both consoles, use '-serial stdio'.
-
-Multicore is also supported by QEMU via '-smp n' where n is the number of cores
-to instantiate. Note, the maximum supported CPU number in QEMU is 255.
-
-The fw_cfg interface in QEMU also provides information about kernel data,
-initrd, command-line arguments and more. U-Boot supports directly accessing
-these informtion from fw_cfg interface, which saves the time of loading them
-from hard disk or network again, through emulated devices. To use it , simply
-providing them in QEMU command line:
-
-$ qemu-system-i386 -nographic -bios path/to/u-boot.rom -m 1024 -kernel /path/to/bzImage
-    -append 'root=/dev/ram console=ttyS0' -initrd /path/to/initrd -smp 8
-
-Note: -initrd and -smp are both optional
-
-Then start QEMU, in U-Boot command line use the following U-Boot command to
-setup kernel:
-
- => qfw
-qfw - QEMU firmware interface
-
-Usage:
-qfw <command>
-    - list                             : print firmware(s) currently loaded
-    - cpus                             : print online cpu number
-    - load <kernel addr> <initrd addr> : load kernel and initrd (if any) and setup for zboot
-
-=> qfw load
-loading kernel to address 01000000 size 5d9d30 initrd 04000000 size 1b1ab50
-
-Here the kernel (bzImage) is loaded to 01000000 and initrd is to 04000000. Then,
-'zboot' can be used to boot the kernel:
-
-=> zboot 01000000 - 04000000 1b1ab50
-
-To run 64-bit U-Boot, qemu-system-x86_64 should be used instead, e.g.:
-$ qemu-system-x86_64 -nographic -bios path/to/u-boot.rom
-
-A specific CPU can be specified via the '-cpu' parameter but please make
-sure the specified CPU supports 64-bit like '-cpu core2duo'. Conversely
-'-cpu pentium' won't work for obvious reasons that the processor only
-supports 32-bit.
-
-Note 64-bit support is very preliminary at this point. Lots of features
-are missing in the 64-bit world. One notable feature is the VGA console
-support which is currently missing, so that you must specify '-nographic'
-to get 64-bit U-Boot up and running.
-
 CPU Microcode
 -------------
 Modern CPUs usually require a special bit stream called microcode [8] to be
diff --git a/doc/board/emulation/index.rst b/doc/board/emulation/index.rst
new file mode 100644
index 0000000..6d533f3
--- /dev/null
+++ b/doc/board/emulation/index.rst
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Emulation
+=========
+
+.. toctree::
+   :maxdepth: 2
+
+   qemu-x86
diff --git a/doc/board/emulation/qemu-x86.rst b/doc/board/emulation/qemu-x86.rst
new file mode 100644
index 0000000..c2e704a
--- /dev/null
+++ b/doc/board/emulation/qemu-x86.rst
@@ -0,0 +1,101 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. sectionauthor:: Bin Meng <bmeng.cn@gmail.com>
+
+QEMU x86
+========
+
+Build instructions for bare mode
+--------------------------------
+
+To build u-boot.rom for QEMU x86 targets, just simply run::
+
+   $ make qemu-x86_defconfig (for 32-bit)
+   $ make qemu-x86_64_defconfig (for 64-bit)
+   $ make all
+
+Note this default configuration will build a U-Boot for the QEMU x86 i440FX
+board. To build a U-Boot against QEMU x86 Q35 board, you can change the build
+configuration during the 'make menuconfig' process like below::
+
+   Device Tree Control  --->
+       ...
+       (qemu-x86_q35) Default Device Tree for DT control
+
+Test with QEMU for bare mode
+----------------------------
+
+QEMU is a fancy emulator that can enable us to test U-Boot without access to
+a real x86 board. Please make sure your QEMU version is 2.3.0 or above test
+U-Boot. To launch QEMU with u-boot.rom, call QEMU as follows::
+
+   $ qemu-system-i386 -nographic -bios path/to/u-boot.rom
+
+This will instantiate an emulated x86 board with i440FX and PIIX chipset. QEMU
+also supports emulating an x86 board with Q35 and ICH9 based chipset, which is
+also supported by U-Boot. To instantiate such a machine, call QEMU with::
+
+   $ qemu-system-i386 -nographic -bios path/to/u-boot.rom -M q35
+
+Note by default QEMU instantiated boards only have 128 MiB system memory. But
+it is enough to have U-Boot boot and function correctly. You can increase the
+system memory by pass '-m' parameter to QEMU if you want more memory::
+
+   $ qemu-system-i386 -nographic -bios path/to/u-boot.rom -m 1024
+
+This creates a board with 1 GiB system memory. Currently U-Boot for QEMU only
+supports 3 GiB maximum system memory and reserves the last 1 GiB address space
+for PCI device memory-mapped I/O and other stuff, so the maximum value of '-m'
+would be 3072.
+
+QEMU emulates a graphic card which U-Boot supports. Removing '-nographic' will
+show QEMU's VGA console window. Note this will disable QEMU's serial output.
+If you want to check both consoles, use '-serial stdio'.
+
+Multicore is also supported by QEMU via '-smp n' where n is the number of cores
+to instantiate. Note, the maximum supported CPU number in QEMU is 255.
+
+The fw_cfg interface in QEMU also provides information about kernel data,
+initrd, command-line arguments and more. U-Boot supports directly accessing
+these informtion from fw_cfg interface, which saves the time of loading them
+from hard disk or network again, through emulated devices. To use it , simply
+providing them in QEMU command line::
+
+   $ qemu-system-i386 -nographic -bios path/to/u-boot.rom -m 1024 \
+     -kernel /path/to/bzImage -append 'root=/dev/ram console=ttyS0' \
+     -initrd /path/to/initrd -smp 8
+
+Note: -initrd and -smp are both optional
+
+Then start QEMU, in U-Boot command line use the following U-Boot command to
+setup kernel::
+
+   => qfw
+   qfw - QEMU firmware interface
+
+   Usage:
+   qfw <command>
+       - list                             : print firmware(s) currently loaded
+       - cpus                             : print online cpu number
+       - load <kernel addr> <initrd addr> : load kernel and initrd (if any) and setup for zboot
+
+   => qfw load
+   loading kernel to address 01000000 size 5d9d30 initrd 04000000 size 1b1ab50
+
+Here the kernel (bzImage) is loaded to 01000000 and initrd is to 04000000. Then,
+'zboot' can be used to boot the kernel::
+
+   => zboot 01000000 - 04000000 1b1ab50
+
+To run 64-bit U-Boot, qemu-system-x86_64 should be used instead, e.g.::
+
+   $ qemu-system-x86_64 -nographic -bios path/to/u-boot.rom
+
+A specific CPU can be specified via the '-cpu' parameter but please make
+sure the specified CPU supports 64-bit like '-cpu core2duo'. Conversely
+'-cpu pentium' won't work for obvious reasons that the processor only
+supports 32-bit.
+
+Note 64-bit support is very preliminary at this point. Lots of features
+are missing in the 64-bit world. One notable feature is the VGA console
+support which is currently missing, so that you must specify '-nographic'
+to get 64-bit U-Boot up and running.
diff --git a/doc/board/index.rst b/doc/board/index.rst
index eb21a67..6d2356f 100644
--- a/doc/board/index.rst
+++ b/doc/board/index.rst
@@ -7,5 +7,6 @@ Board-specific doc
    :maxdepth: 2
 
    coreboot/index
+   emulation/index
    google/index
    intel/index
-- 
2.7.4