docs: Add 'targets' section
Creates a new section in the docs for target documentation, and adds
some documentation for the stm32f429i-disc1 target.
Change-Id: I0ffbfa56a97458d850834fc0f670b32885b0d2b5
diff --git a/docs/BUILD.gn b/docs/BUILD.gn
index 79aa782..2133e55 100644
--- a/docs/BUILD.gn
+++ b/docs/BUILD.gn
@@ -21,15 +21,24 @@
]
}
+# Documentation for upstream Pigweed targets.
+group("target_docs") {
+ deps = [
+ "$dir_pigweed/targets/stm32f429i-disc1:target_docs",
+ ]
+}
+
pw_doc_gen("docs") {
conf = "conf.py"
sources = [
"index.rst",
"modules.rst",
+ "targets.rst",
]
output_directory = target_gen_dir
deps = [
":core_docs",
+ ":target_docs",
"$dir_pw_bloat:docs",
"$dir_pw_build:docs",
"$dir_pw_docgen:docs",
diff --git a/docs/index.rst b/docs/index.rst
index 055690e..169bdcf 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -13,4 +13,5 @@
docs/embedded_cpp_guide
docs/style_guide
+ targets
modules
diff --git a/docs/targets.rst b/docs/targets.rst
new file mode 100644
index 0000000..d961d39
--- /dev/null
+++ b/docs/targets.rst
@@ -0,0 +1,12 @@
+=======
+Targets
+=======
+Pigweed is designed to support many 32-bit (and even some 64-bit) targets. This
+section contains documentation for the targets used for upstream Pigweed
+development, though more may exist outside the main Pigweed repository.
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ targets/*/target_docs
diff --git a/targets/stm32f429i-disc1/BUILD.gn b/targets/stm32f429i-disc1/BUILD.gn
new file mode 100644
index 0000000..3727e50
--- /dev/null
+++ b/targets/stm32f429i-disc1/BUILD.gn
@@ -0,0 +1,21 @@
+# Copyright 2019 The Pigweed Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License. You may obtain a copy of
+# the License at
+#
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations under
+# the License.
+
+import("$dir_pw_docgen/docs.gni")
+
+pw_doc_group("target_docs") {
+ sources = [
+ "target_docs.rst",
+ ]
+}
diff --git a/targets/stm32f429i-disc1/target_docs.rst b/targets/stm32f429i-disc1/target_docs.rst
new file mode 100644
index 0000000..71b236c
--- /dev/null
+++ b/targets/stm32f429i-disc1/target_docs.rst
@@ -0,0 +1,65 @@
+.. _chapter-stm32f429i-disc1:
+
+.. default-domain:: cpp
+
+.. highlight:: sh
+
+----------------
+stm32f429i-disc1
+----------------
+The STMicroelectronics STM32F429I-DISC1 development board is currently Pigweed's
+primary target for on-device testing and development.
+
+Building
+========
+To build for this target, change the ``pw_target_config`` GN build arg to point
+to this target's configuration file.
+
+.. code:: sh
+
+ $ gn gen --args='pw_target_config = "//targets/stm32f429i-disc1/target_config.gni"' out/disco
+ $ ninja -C out/disco
+
+or
+
+.. code:: sh
+
+ $ gn gen out/disco
+ $ gn args
+ # Modify and save the args file to update the pw_target_config.
+ pw_target_config = "//targets/stm32f429i-disc1/target_config.gni"
+ $ ninja -C out/disco
+
+Testing
+=======
+The default Pigweed build target will build all of the pigweed module unit
+tests. These tests can be run on-device in a few different ways.
+
+Run a unit test
+---------------
+Test if using ``out/disco`` as your build directory, tests will be located in
+``out/disco/obj/[module name]/[test_name].elf``. To run these on device, the
+stm32f429i-disc1 target provides a helper script that flashes the test to a
+device and then runs it.
+
+.. code:: sh
+
+ # Setup pigweed environment.
+ $ . env_setup/setup.sh
+ # Run test.
+ $ stm32f429i_disc1_unit_test_runner /path/to/binary
+
+Run multiple tests
+------------------
+Running all tests one-by-one is rather tedious. To make running multiple
+tests easier, use Pigweed's ``pw test`` command and pass it your build directory
+and the name of the test runner. By default, ``pw test`` will run all tests,
+but you can restrict it to specific groups using the ``--group`` flag.
+Individual test binaries can be specified with the ``--test`` flag as well.
+
+.. code:: sh
+
+ # Setup pigweed environment.
+ $ . env_setup/setup.sh
+ # Run test.
+ $ pw test --root out/disco/ --runner stm32f429i_disc1_unit_test_runner