zephyr: docs: Reorganize the build steps

I went reading this document from the perspective of a potential ODM
partner looking to build Zephyr and noticed it has a bunch of issues:

- It seems that we recommend using the ebuild as the primary way of
  building as it was at the top of this document.  This ebuild exists
  only to integrate with the greater portage build system, and it's
  unlikely that folks will want to run the ebuild manually in most
  cases.  I kept this in the doc, but moved it down lower so it didn't
  seem like the recommended thing.

  `zmake build` is now the first command people will see when they
  want to know how to build the EC.

- The out-of-chroot steps are mixed in with the regular build steps.
  I moved these out to another doc, recommending the standard Chromium
  OS developer guide for chroot setup.

- The `volteer` Zephyr project is deprecated.  Updated references to
  `skyrim` so there's a working build target for folks to try.

BUG=none
BRANCH=none
TEST=view markdown in gitiles

Signed-off-by: Jack Rosenthal <jrosenth@chromium.org>
Change-Id: Ib93d37f8bdd6fe3e33667ce60d15dffc8949bd68
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/3484837
Reviewed-by: Jeremy Bettis <jbettis@chromium.org>

2 files changed, 121 insertions, 104 deletions

diff --git a/docs/zephyr/out_of_chroot.md b/docs/zephyr/out_of_chroot.md
new file mode 100644
index 0000000000..22e1e2c342
--- /dev/null
+++ b/docs/zephyr/out_of_chroot.md
@@ -0,0 +1,76 @@
+# Building Zephyr Out-of-Chroot
+
+It is possible to build Zephyr outside of the Chromium OS chroot,
+albeit with additional steps.
+
+*** note
+**Note:** These steps are maintained on a best-effort basis, and may
+not be accurate depending on your Linux distribution and your system's
+specific environment.
+***
+
+[TOC]
+
+## Remove west, if installed [b/184654974](http://b/184654974)
+
+Zephyr's Cmake system will try to attach itself to the west tool if it finds it
+installed, conflicting with manual cmake invocations. If you installed west,
+you'll need to remove it:
+
+```bash
+python3 -m pip uninstall west
+```
+
+## Install zmake
+
+You can install zmake with pip:
+
+```bash
+cd ~/chromiumos/src/platform/ec
+python3 -m pip install -e zephyr/zmake --user
+```
+
+Ensure that `~/.local/bin` is in your `PATH`.
+
+You may also need to install these items:
+
+```bash
+sudo apt-get install cmake ninja-build python3-pyelftools gcc-multilib \
+    python3-pykwalify python3-colorama python3-testfixtures
+```
+
+## Install binman
+
+First build pylibfdt:
+
+```bash
+cd somewhere
+sudo apt-get install flex bison swig
+git clone git://git.kernel.org/pub/scm/utils/dtc/dtc.git
+cd dtc
+make
+make install PREFIX=~/.local         # You can install this where it suits
+```
+
+If you have a Chromium OS checkout then you should do:
+
+```bash
+cd ~/.local/bin
+ln -s ~/chromiumos/src/third_party/u-boot/files/tools/binman/binman
+```
+
+otherwise:
+
+```bash
+cd somewhere
+git clone https://source.denx.de/u-boot/u-boot.git
+cd ~/.local/bin
+ln -s somewhere/u-boot/tools/binman/binman
+```
+
+## Install Zephyr toolchain
+
+If using the Zephyr toolchain (`-t zephyr`), follow the [upstream
+documentation] to install the Zephyr build tools.
+
+[upstream documentation]: https://docs.zephyrproject.org/getting_started/index.html#install-a-toolchain
diff --git a/docs/zephyr/zephyr_build.md b/docs/zephyr/zephyr_build.md
index 414dfb832b..8668c50e11 100644
--- a/docs/zephyr/zephyr_build.md
+++ b/docs/zephyr/zephyr_build.md
@@ -6,135 +6,70 @@ Chromium OS EC uses the `zmake` tool to build Zephyr.
 
 This section describes how to build and use zmake.
 
-## Syncing the source
+## Environment Setup
 
-*** note
-The Zephyr build relies on multiple repos.  This means that partial
-syncs are not supported (i.e., just doing `repo sync .` in
-`platform/ec`), as you may end up with a Zephyr kernel or module which
-is not compatible with your EC checkout.
-***
+Follow the [Chromium OS Developer Guide] to sync the source and get
+the chroot setup.
 
-## Working inside the chroot
+It is also possible to build without a Chromium OS chroot, albeit with
+additional setup steps.  See [out-of-chroot building] if this
+interests you.
 
-### Building
+### A Note on Syncing the Source
 
-You can build zephyr with:
-
-```bash
-emerge-volteer chromeos-zephyr
-```
-
-For local development you can run zmake directly; see instruction below.
-
-## Working outside the chroot
-
-Running outside the Chromium OS chroot is useful for upstream work and for
-those using the EC outside the Chromium OS.
+The Legacy EC required only a single repository, and thus, it was common
+for developers to sync just the EC repository using `repo sync .`.
 
+Since the Zephyr build relies on multiple repositories, doing so will
+likely end you up in a broken state.  Please be sure to do a complete
+sync when updating the source.
 
-### Remove west, if installed [b/184654974](http://b/184654974)
+## Building
 
-Zephyr's Cmake system will try to attach itself to the west tool if it finds it
-installed, conflicting with manual cmake invocations. If you installed west,
-you'll need to remove it:
+To build the EC for a single project, run:
 
-```bash
-python3 -m pip uninstall west
+``` shellsession
+(chroot) $ zmake build "${PROJECT}"
 ```
 
+For example, to build the EC for `skyrim`, run:
 
-### Install zmake
-
-You can install zmake with pip:
-
-```bash
-cd ~/chromiumos/src/platform/ec
-python3 -m pip install -e zephyr/zmake --user
+``` shellsession
+(chroot) $ zmake build skyrim
 ```
 
-Ensure that ~/.local/bin in on your PATH
+The output binary will then be located at `build/zephyr/skyrim/output/zephyr.bin`.
 
-You may also need to install these items:
+Additional output files you may find useful:
 
-```bash
-sudo apt-get install cmake ninja-build python3-pyelftools gcc-multilib \
-    python3-pykwalify python3-colorama python3-testfixtures
-```
-
-You must reinstall zmake after any `repo sync` since new features may have been
-added that are needed by the build.
-
-
-### Install binman
-
-First build pylibfdt:
-
-```bash
-cd somewhere
-sudo apt-get install flex bison swig
-git clone git://git.kernel.org/pub/scm/utils/dtc/dtc.git
-cd dtc
-make
-make install PREFIX=~/.local         # You can install this where it suits
-```
-
-If you have a Chromium OS checkout then you should do:
-
-```bash
-cd ~/.local/bin
-ln -s ~/chromiumos/src/third_party/u-boot/files/tools/binman/binman
-```
+*   `build/zephyr/skyrim/output/zephyr.ro.elf` - read-only ELF for debugging
+*   `build/zephyr/skyrim/output/zephyr.rw.elf` - read-write ELF for debugging
 
-otherwise:
-
-```bash
-cd somewhere
-git clone https://source.denx.de/u-boot/u-boot.git
-cd ~/.local/bin
-ln -s somewhere/u-boot/tools/binman/binman
-```
-
-As above, ensure that `~/.local/bin` in on your PATH
-
-
-### Install Zephyr toolchain
+You might also find these files useful (using read-only as an example):
 
-If using the Zephyr toolchain (`-t zephyr`), follow the [upstream
-documentation] to install the Zephyr build tools.
+*   `build/zephyr/skyrim/build-ro/zephyr/.config` - Kconfig options selected
+*   `build/zephyr/skyrim/build-ro/zephyr/include/generated/devicetree_unfixed.h` - the (large)
+    header file that zephyr uses to provide devicetree information to the C code
+*   `build/zephyr/skyrim/build-ro/zephyr/zephyr.dts` - devicetree that is used
+*   `build/zephyr/skyrim/build-ro/zephyr/zephyr.dts` - map of image
 
-[upstream documentation]: https://docs.zephyrproject.org/getting_started/index.html#install-a-toolchain
+For a complete list of `zmake` commands and options, see the
+[Zmake Documentation].
 
+Googlers may be interested in setting up [building with Goma](../goma.md)
+as well.
 
-### Building
+### Building from Portage
 
-You can use `zmake help` to obtain help on how to use zmake. The following is
-a rough guide.
+There is also a [an ebuild] for integration into the larger Chromium
+OS build system.
 
-First configure the build with the project(s) you want:
+To build using this flow, run:
 
-```bash
-zmake build -B /tmp/z volteer
+``` shellsession
+(chroot) $ emerge-${BOARD} chromeos-base/chromeos-zephyr
 ```
 
-The output is in that directory:
-
-*   `volteer/output/zephyr.bin` - output binary (read-only and read-write packed
-    together)
-*   `volteer/output/zephyr.ro.elf` - read-only ELF for debugging
-*   `volteer/output/zephyr.rw.elf` - read-write ELF for debugging
-
-You might also find these files useful (using read-only as an example):
-
-*   `volteer/build-ro/zephyr/.config` - Kconfig options selected
-*   `volteer/build-ro/zephyr/include/generated/devicetree_unfixed.h` - the (large)
-    header file that zephyr uses to provide devicetree information to the C code
-*   `volteer/build-ro/zephyr/zephyr.dts` - devicetree that is used
-*   `volteer/build-ro/zephyr/zephyr.dts` - map of image
-
-Googlers may be interested in setting up [building with Goma](../goma.md)
-as well.
-
 ### Looking at the Kconfig
 
 It should be possible to do this with:
@@ -144,3 +79,9 @@ ninja -C /tmp/z/volteer/build-ro menuconfig
 ```
 
 However at present this does not work [b/184662866](http://b/184662866).
+
+
+[Chromium OS Developer Guide]: https://chromium.googlesource.com/chromiumos/docs/+/HEAD/developer_guide.md
+[Zmake Documentation]: ../../zephyr/zmake/README.md
+[an ebuild]: https://chromium.googlesource.com/chromiumos/overlays/chromiumos-overlay/+/HEAD/chromeos-base/chromeos-zephyr/chromeos-zephyr-9999.ebuild
+[out-of-chroot building]: ./out_of_chroot.md