[PATCH] doc: Improve docs

[Baurzhan Ismagulov <ibr@radix50.net>]

From: Baurzhan Ismagulov <ibr@ilbers.de>

Signed-off-by: Baurzhan Ismagulov <ibr@ilbers.de>
---
 doc/edk2_build.md  | 59 +++++++++++++++++++++++++++++++++++++++---------------
 doc/user_manual.md | 17 ++++++++++++----
 2 files changed, 56 insertions(+), 20 deletions(-)

diff --git a/doc/edk2_build.md b/doc/edk2_build.md
index 64c90ff..f33d381 100644
--- a/doc/edk2_build.md
+++ b/doc/edk2_build.md
@@ -1,12 +1,20 @@
 # Building Tianocore UEFI Firmware
 
-## Install Build Dependencies
+A binary `ovmf` package is available in Debian Jessie, Stretch, and sid, but it
+doesn't seem to be recent enough for testing images generated by Isar.
+
+## Get the Sources
+
+```
+git clone https://github.com/tianocore/edk2
+cd edk2
+git checkout 3858b4a1ff09d3243fea8d07bd135478237cb8f7
+```
 
-Install the following packages with `sudo apt-get install`:
+## Install Build Dependencies
 
 ```
-uuid-dev      # /usr/include/uuid/uuid.h
-acpica-tools  # /usr/bin/iasl
+sudo apt-get install acpica-tools g++ make nasm python uuid-dev
 ```
 
 ## Build BaseTools
@@ -14,31 +22,50 @@ acpica-tools  # /usr/bin/iasl
 * `BaseTools/Source/C/Makefiles/header.makefile`: Remove `-Werror`
 * `make -C BaseTools`
 
-
 ## Initialize Build Environment
 
-`. edksetup.sh`
+`. ./edksetup.sh`
 
-## Build IA32 Firmware
+## Build X64 Firmware
+
+Usable with qemu-system-x86_64.
 
-* `Conf/target.txt`: Edit as follows:
+Edit `Conf/target.txt` as follows:
 ```
-ACTIVE_PLATFORM       = OvmfPkg/OvmfPkgIa32.dsc
+ACTIVE_PLATFORM       = OvmfPkg/OvmfPkgX64.dsc
 TARGET                = RELEASE
-TARGET_ARCH           = IA32
+TARGET_ARCH           = X64
 TOOL_CHAIN_TAG        = GCC49
 MAX_CONCURRENT_THREAD_NUMBER = 8
 ```
-* `build`
 
-## Build X64 Firmware
+```
+build
+```
+
+Tested on Stretch.
+
+## Build IA32 Firmware
 
-* `Conf/target.txt`: Edit as follows:
+Usable with qemu-system-i386 or qemu-system-x86_64. If the X64 version works
+for you, skip this section.
+
+Edit `Conf/target.txt` as follows:
 ```
-ACTIVE_PLATFORM       = OvmfPkg/OvmfPkgX64.dsc
+ACTIVE_PLATFORM       = OvmfPkg/OvmfPkgIa32.dsc
 TARGET                = RELEASE
-TARGET_ARCH           = X64
+TARGET_ARCH           = IA32
 TOOL_CHAIN_TAG        = GCC49
 MAX_CONCURRENT_THREAD_NUMBER = 8
 ```
-* `build`
+
+```
+build
+```
+
+Tested on Jessie.
+
+## TODO
+
+* Test sid `ovmf` later than 2018-08-07. If it doesn't work, provide an updated
+  package.
diff --git a/doc/user_manual.md b/doc/user_manual.md
index ff4939c..24e3cc7 100644
--- a/doc/user_manual.md
+++ b/doc/user_manual.md
@@ -57,23 +57,32 @@ The supported host system is >= stretch.
 
 Install the following packages:
 ```
+binfmt-support
+debootstrap
 dosfstools
-git
 dpkg-dev
+git
+mtools
 parted
 python3
 python3-distutils             # host >= buster
-qemu
+qemu                          # start_vm
 qemu-user-static
-binfmt-support
-sudo
 reprepro
+sudo
 ```
 
 Notes:
 
 * BitBake requires Python 3.4+.
 * The python3 package is required for the correct `alternatives` setting.
+* If you'd like to run bitbake in a container (chroot, docker, etc.), install
+  the above in the container, and also perform `sudo apt-get install
+  binfmt-support qemu-user-static` on the host that should run the container.
+* If you install `binfmt-support` after `qemu-user-static`, perform `sudo
+  apt-get install --reinstall qemu-user-static` to register binary formats
+  handled by QEMU (check e.g. `qemu-arm` in `/usr/sbin/update-binfmts
+  --display`).
 
 ### Setup Sudo
 
-- 
2.11.0