doc: restructure build/config system section
Restructure Build/Config section to allow for addition of new content
(DTS).
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
diff --git a/doc/build/build-build-phase-1.svg b/doc/build/cmake/build-build-phase-1.svg
similarity index 100%
rename from doc/build/build-build-phase-1.svg
rename to doc/build/cmake/build-build-phase-1.svg
diff --git a/doc/build/build-build-phase-2.svg b/doc/build/cmake/build-build-phase-2.svg
similarity index 100%
rename from doc/build/build-build-phase-2.svg
rename to doc/build/cmake/build-build-phase-2.svg
diff --git a/doc/build/build-build-phase-3.svg b/doc/build/cmake/build-build-phase-3.svg
similarity index 100%
rename from doc/build/build-build-phase-3.svg
rename to doc/build/cmake/build-build-phase-3.svg
diff --git a/doc/build/build-build-phase-4.svg b/doc/build/cmake/build-build-phase-4.svg
similarity index 100%
rename from doc/build/build-build-phase-4.svg
rename to doc/build/cmake/build-build-phase-4.svg
diff --git a/doc/build/build-build-phase-5.svg b/doc/build/cmake/build-build-phase-5.svg
similarity index 100%
rename from doc/build/build-build-phase-5.svg
rename to doc/build/cmake/build-build-phase-5.svg
diff --git a/doc/build/build-build-phase-6.svg b/doc/build/cmake/build-build-phase-6.svg
similarity index 100%
rename from doc/build/build-build-phase-6.svg
rename to doc/build/cmake/build-build-phase-6.svg
diff --git a/doc/build/build-config-phase.svg b/doc/build/cmake/build-config-phase.svg
similarity index 100%
rename from doc/build/build-config-phase.svg
rename to doc/build/cmake/build-config-phase.svg
diff --git a/doc/build/build-postprocess-1.svg b/doc/build/cmake/build-postprocess-1.svg
similarity index 100%
rename from doc/build/build-postprocess-1.svg
rename to doc/build/cmake/build-postprocess-1.svg
diff --git a/doc/build/build-postprocess-2.svg b/doc/build/cmake/build-postprocess-2.svg
similarity index 100%
rename from doc/build/build-postprocess-2.svg
rename to doc/build/cmake/build-postprocess-2.svg
diff --git a/doc/build/build-postprocess-3.svg b/doc/build/cmake/build-postprocess-3.svg
similarity index 100%
rename from doc/build/build-postprocess-3.svg
rename to doc/build/cmake/build-postprocess-3.svg
diff --git a/doc/build/build-postprocess-4.svg b/doc/build/cmake/build-postprocess-4.svg
similarity index 100%
rename from doc/build/build-postprocess-4.svg
rename to doc/build/cmake/build-postprocess-4.svg
diff --git a/doc/build/cmake/index.rst b/doc/build/cmake/index.rst
new file mode 100644
index 0000000..7287ca6
--- /dev/null
+++ b/doc/build/cmake/index.rst
@@ -0,0 +1,417 @@
+.. _cmake-details:
+
+Build System (CMake)
+********************
+
+
+CMake is used to build your application together with the Zephyr kernel. A
+CMake build is done in two stages. The first stage is called
+**configuration**. During configuration, the CMakeLists.txt build scripts are
+executed. After configuration is finished, CMake has an internal model of the
+Zephyr build, and can generate build scripts that are native to the host
+platform.
+
+CMake supports generating scripts for several build systems, but only Ninja and
+Make are tested and supported by Zephyr. After configuration, you begin the
+**build** stage by executing the generated build scripts. These build scripts
+can recompile the application without involving CMake following
+most code changes. However, after certain changes, the configuration step must
+be executed again before building. The build scripts can detect some of these
+situations and reconfigure automatically, but there are cases when this must be
+done manually.
+
+Zephyr uses CMake's concept of a 'target' to organize the build. A
+target can be an executable, a library, or a generated file. For
+application developers, the library target is the most important to
+understand. All source code that goes into a Zephyr build does so by
+being included in a library target, even application code.
+
+Library targets have source code, that is added through CMakeLists.txt
+build scripts like this:
+
+.. code-block:: cmake
+
+ target_sources(app PRIVATE src/main.c)
+
+In the above :file:`CMakeLists.txt`, an existing library target named ``app``
+is configured to include the source file :file:`src/main.c`. The ``PRIVATE``
+keyword indicates that we are modifying the internals of how the library is
+being built. Using the keyword ``PUBLIC`` would modify how other
+libraries that link with app are built. In this case, using ``PUBLIC``
+would cause libraries that link with ``app`` to also include the
+source file :file:`src/main.c`, behavior that we surely do not want. The
+``PUBLIC`` keyword could however be useful when modifying the include
+paths of a target library.
+
+
+Build and Configuration Phases
+==============================
+
+The Zephyr build process can be divided into two main phases: a configuration
+phase (driven by CMake) and a build phase (driven by Make or Ninja).
+
+.. _build_configuration_phase:
+
+Configuration Phase
+-------------------
+
+The configuration phase begins when the user invokes *CMake* to generate a
+build system, specifying a source application directory and a board target.
+
+.. figure:: build-config-phase.svg
+ :align: center
+ :alt: Zephyr's build configuration phase
+ :figclass: align-center
+ :width: 80%
+
+CMake begins by processing the :file:`CMakeLists.txt` file in the application
+directory, which refers to the :file:`CMakeLists.txt` file in the Zephyr
+top-level directory, which in turn refers to :file:`CMakeLists.txt` files
+throughout the build tree (directly and indirectly). Its primary output is a
+set of Makefiles or Ninja files to drive the build process, but the CMake
+scripts also do some processing of their own, which is explained here.
+
+Note that paths beginning with :file:`build/` below refer to the build
+directory you create when running CMake.
+
+Devicetree
+ :file:`*.dts` (*devicetree source*) and :file:`*.dtsi` (*devicetree source
+ include*) files are collected from the target's architecture, SoC, board,
+ and application directories.
+
+ :file:`*.dtsi` files are included by :file:`*.dts` files via the C
+ preprocessor (often abbreviated *cpp*, which should not be confused with
+ C++). The C preprocessor is also used to merge in any devicetree
+ :file:`*.overlay` files, and to expand macros in :file:`*.dts`,
+ :file:`*.dtsi`, and :file:`*.overlay` files. The preprocessor output is
+ placed in :file:`build/zephyr/zephyr.dts.pre`.
+
+ The preprocessed devicetree sources are parsed by
+ :zephyr_file:`gen_defines.py <scripts/dts/gen_defines.py>` to generate a
+ :file:`build/zephyr/include/generated/devicetree_unfixed.h` header with
+ preprocessor macros.
+
+ Source code should access preprocessor macros generated from devicetree by
+ including the :zephyr_file:`devicetree.h <include/devicetree.h>` header,
+ which includes :file:`devicetree_unfixed.h`.
+
+ :file:`gen_defines.py` also writes the final devicetree to
+ :file:`build/zephyr/zephyr.dts` in the build directory. This file's contents
+ may be useful for debugging.
+
+ If the devicetree compiler ``dtc`` is installed, it is run on
+ :file:`build/zephyr/zephyr.dts` to catch any extra warnings and errors
+ generated by this tool. The output from ``dtc`` is unused otherwise, and
+ this step is skipped if ``dtc`` is not installed.
+
+ The above is just a brief overview. For more information on devicetree, see
+ :ref:`dt-guide`.
+
+Devicetree fixups
+ Files named :file:`dts_fixup.h` from the target’s architecture, SoC, board,
+ and application directories are concatenated into a single
+ :file:`devicetree_fixups.h` file. :file:`dts_fixup.h` files are a legacy
+ feature which should not be used in new code.
+
+Kconfig
+ :file:`Kconfig` files define available configuration options for for the
+ target architecture, SoC, board, and application, as well as dependencies
+ between options.
+
+ Kconfig configurations are stored in *configuration files*. The initial
+ configuration is generated by merging configuration fragments from the board
+ and application (e.g. :file:`prj.conf`).
+
+ The output from Kconfig is an :file:`autoconf.h` header with preprocessor
+ assignments, and a :file:`.config` file that acts both as a saved
+ configuration and as configuration output (used by CMake). The definitions in
+ :file:`autoconf.h` are automatically exposed at compile time, so there is no
+ need to include this header.
+
+ Information from devicetree is available to Kconfig, through the functions
+ defined in :zephyr_file:`kconfigfunctions.py
+ <scripts/kconfig/kconfigfunctions.py>`.
+
+ See :ref:`the Kconfig section of the manual <kconfig>` for more information.
+
+Build Phase
+-----------
+
+The build phase begins when the user invokes ``make`` or ``ninja``. Its
+ultimate output is a complete Zephyr application in a format suitable for
+loading/flashing on the desired target board (:file:`zephyr.elf`,
+:file:`zephyr.hex`, etc.) The build phase can be broken down, conceptually,
+into four stages: the pre-build, first-pass binary, final binary, and
+post-processing.
+
+Pre-build
++++++++++
+
+Pre-build occurs before any source files are compiled, because during
+this phase header files used by the source files are generated.
+
+Offset generation
+ Access to high-level data structures and members is sometimes
+ required when the definitions of those structures is not
+ immediately accessible (e.g., assembly language). The generation of
+ *offsets.h* (by *gen_offset_header.py*) facilitates this.
+
+System call boilerplate
+ The *gen_syscall.py* and *parse_syscalls.py* scripts work
+ together to bind potential system call functions with their
+ implementations.
+
+.. figure:: build-build-phase-1.svg
+ :align: center
+ :alt: Zephyr's build stage I
+ :figclass: align-center
+ :width: 80%
+
+Intermediate binaries
++++++++++++++++++++++
+
+Compilation proper begins with the first intermediate binary. Source files (C
+and assembly) are collected from various subsystems (which ones is
+decided during the configuration phase), and compiled into archives
+(with reference to header files in the tree, as well as those
+generated during the configuration phase and the pre-build stage(s)).
+
+.. figure:: build-build-phase-2.svg
+ :align: center
+ :alt: Zephyr's build stage II
+ :figclass: align-center
+ :width: 80%
+
+The exact number of intermediate binaries is decided during the configuration
+phase.
+
+If memory protection is enabled, then:
+
+Partition grouping
+ The *gen_app_partitions.py* script scans all the
+ generated archives and outputs linker scripts to ensure that
+ application partitions are properly grouped and aligned for the
+ target’s memory protection hardware.
+
+Then *cpp* is used to combine linker script fragments from the target’s
+architecture/SoC, the kernel tree, optionally the partition output if
+memory protection is enabled, and any other fragments selected during
+the configuration process, into a *linker.cmd* file. The compiled
+archives are then linked with *ld* as specified in the
+*linker.cmd*.
+
+Unfixed size binary
+ The unfixed size intermediate binary is produced when :ref:`usermode_api`
+ is enabled or :ref:`devicetree` is in use.
+ It produces a binary where sizes are not fixed and thus it may be used
+ by post-process steps that will impact the size of the final binary.
+
+.. figure:: build-build-phase-3.svg
+ :align: center
+ :alt: Zephyr's build stage III
+ :figclass: align-center
+ :width: 80%
+
+Fixed size binary
+ The fixed size intermediate binary is produced when :ref:`usermode_api`
+ is enabled or when generated IRQ tables are used,
+ :kconfig:option:`CONFIG_GEN_ISR_TABLES`
+ It produces a binary where sizes are fixed and thus the size must not change
+ between the intermediate binary and the final binary.
+
+.. figure:: build-build-phase-4.svg
+ :align: center
+ :alt: Zephyr's build stage IV
+ :figclass: align-center
+ :width: 80%
+
+Intermediate binaries post-processing
++++++++++++++++++++++++++++++++++++++
+
+The binaries from the previous stage are incomplete, with empty and/or
+placeholder sections that must be filled in by, essentially, reflection.
+
+To complete the build procedure the following scripts are executed on the
+intermediate binaries to produce the missing pieces needed for the final
+binary.
+
+When :ref:`usermode_api` is enabled:
+
+Partition alignment
+ The *gen_app_partitions.py* script scans the unfixed size binary and
+ generates an app shared memory aligned linker script snippet where the
+ partitions are sorted in descending order.
+
+.. figure:: build-postprocess-1.svg
+ :align: center
+ :alt: Zephyr's intermediate binary post-process I
+ :figclass: align-center
+ :width: 80%
+
+When :ref:`devicetree` is used:
+
+Device dependencies
+ The *gen_handles.py* script scans the unfixed size binary to determine
+ relationships between devices that were recorded from devicetree data,
+ and replaces the encoded relationships with values that are optimized to
+ locate the devices actually present in the application.
+
+.. figure:: build-postprocess-2.svg
+ :align: center
+ :alt: Zephyr's intermediate binary post-process II
+ :figclass: align-center
+ :width: 80%
+
+When :kconfig:option:`CONFIG_GEN_ISR_TABLES` is enabled:
+ The *gen_isr_tables.py* script scant the fixed size binary and creates
+ an isr_tables.c source file with a hardware vector table and/or software
+ IRQ table.
+
+.. figure:: build-postprocess-3.svg
+ :align: center
+ :alt: Zephyr's intermediate binary post-process III
+ :figclass: align-center
+ :width: 80%
+
+When :ref:`usermode_api` is enabled:
+
+Kernel object hashing
+ The *gen_kobject_list.py* scans the *ELF DWARF*
+ debug data to find the address of the all kernel objects. This
+ list is passed to *gperf*, which generates a perfect hash function and
+ table of those addresses, then that output is optimized by
+ *process_gperf.py*, using known properties of our special case.
+
+.. figure:: build-postprocess-4.svg
+ :align: center
+ :alt: Zephyr's intermediate binary post-process IV
+ :figclass: align-center
+ :width: 80%
+
+When no intermediate binary post-processing is required then the first
+intermediate binary will be directly used as the final binary.
+
+Final binary
+++++++++++++
+
+The binary from the previous stage is incomplete, with empty and/or
+placeholder sections that must be filled in by, essentially, reflection.
+
+The link from the previous stage is repeated, this time with the missing
+pieces populated.
+
+.. figure:: build-build-phase-5.svg
+ :align: center
+ :alt: Zephyr's build final stage
+ :figclass: align-center
+ :width: 80%
+
+Post processing
++++++++++++++++
+
+Finally, if necessary, the completed kernel is converted from *ELF* to
+the format expected by the loader and/or flash tool required by the
+target. This is accomplished in a straightforward manner with *objdump*.
+
+.. figure:: build-build-phase-6.svg
+ :align: center
+ :alt: Zephyr's build final stage post-process
+ :figclass: align-center
+ :width: 80%
+
+
+.. _build_system_scripts:
+
+Supporting Scripts and Tools
+============================
+
+The following is a detailed description of the scripts used during the build process.
+
+.. _gen_syscalls.py:
+
+:zephyr_file:`scripts/gen_syscalls.py`
+--------------------------------------
+
+.. include:: ../../../scripts/gen_syscalls.py
+ :start-after: """
+ :end-before: """
+
+.. _gen_handles.py:
+
+:zephyr_file:`scripts/gen_handles.py`
+--------------------------------------
+
+.. include:: ../../../scripts/gen_handles.py
+ :start-after: """
+ :end-before: """
+
+.. _gen_kobject_list.py:
+
+:zephyr_file:`scripts/gen_kobject_list.py`
+------------------------------------------
+
+.. include:: ../../../scripts/gen_kobject_list.py
+ :start-after: """
+ :end-before: """
+
+.. _gen_offset_header.py:
+
+:zephyr_file:`scripts/gen_offset_header.py`
+-------------------------------------------
+
+.. include:: ../../../scripts/gen_offset_header.py
+ :start-after: """
+ :end-before: """
+
+.. _parse_syscalls.py:
+
+:zephyr_file:`scripts/parse_syscalls.py`
+----------------------------------------
+
+
+.. include:: ../../../scripts/parse_syscalls.py
+ :start-after: """
+ :end-before: """
+
+.. _gen_idt.py:
+
+:zephyr_file:`arch/x86/gen_idt.py`
+----------------------------------
+
+.. include:: ../../../arch/x86/gen_idt.py
+ :start-after: """
+ :end-before: """
+
+.. _gen_gdt.py:
+
+:zephyr_file:`arch/x86/gen_gdt.py`
+----------------------------------
+
+.. include:: ../../../arch/x86/gen_gdt.py
+ :start-after: """
+ :end-before: """
+
+.. _gen_relocate_app.py:
+
+:zephyr_file:`scripts/gen_relocate_app.py`
+-------------------------------------------
+
+.. include:: ../../../scripts/gen_relocate_app.py
+ :start-after: """
+ :end-before: """
+
+.. _process_gperf.py:
+
+:zephyr_file:`scripts/process_gperf.py`
+---------------------------------------
+
+.. include:: ../../../scripts/process_gperf.py
+ :start-after: """
+ :end-before: """
+
+:zephyr_file:`scripts/gen_app_partitions.py`
+--------------------------------------------
+
+.. include:: ../../../scripts/gen_app_partitions.py
+ :start-after: """
+ :end-before: """
diff --git a/doc/build/index.rst b/doc/build/index.rst
index 4bc2c63..5e3ba91 100644
--- a/doc/build/index.rst
+++ b/doc/build/index.rst
@@ -4,455 +4,9 @@
###############################
-.. _cmake-details:
-
-Build System (CMake)
-********************
-
-
-CMake is used to build your application together with the Zephyr kernel. A
-CMake build is done in two stages. The first stage is called
-**configuration**. During configuration, the CMakeLists.txt build scripts are
-executed. After configuration is finished, CMake has an internal model of the
-Zephyr build, and can generate build scripts that are native to the host
-platform.
-
-CMake supports generating scripts for several build systems, but only Ninja and
-Make are tested and supported by Zephyr. After configuration, you begin the
-**build** stage by executing the generated build scripts. These build scripts
-can recompile the application without involving CMake following
-most code changes. However, after certain changes, the configuration step must
-be executed again before building. The build scripts can detect some of these
-situations and reconfigure automatically, but there are cases when this must be
-done manually.
-
-Zephyr uses CMake's concept of a 'target' to organize the build. A
-target can be an executable, a library, or a generated file. For
-application developers, the library target is the most important to
-understand. All source code that goes into a Zephyr build does so by
-being included in a library target, even application code.
-
-Library targets have source code, that is added through CMakeLists.txt
-build scripts like this:
-
-.. code-block:: cmake
-
- target_sources(app PRIVATE src/main.c)
-
-In the above :file:`CMakeLists.txt`, an existing library target named ``app``
-is configured to include the source file :file:`src/main.c`. The ``PRIVATE``
-keyword indicates that we are modifying the internals of how the library is
-being built. Using the keyword ``PUBLIC`` would modify how other
-libraries that link with app are built. In this case, using ``PUBLIC``
-would cause libraries that link with ``app`` to also include the
-source file :file:`src/main.c`, behavior that we surely do not want. The
-``PUBLIC`` keyword could however be useful when modifying the include
-paths of a target library.
-
-
-Build and Configuration Phases
-==============================
-
-The Zephyr build process can be divided into two main phases: a configuration
-phase (driven by CMake) and a build phase (driven by Make or Ninja).
-
-.. _build_configuration_phase:
-
-Configuration Phase
--------------------
-
-The configuration phase begins when the user invokes *CMake* to generate a
-build system, specifying a source application directory and a board target.
-
-.. figure:: build-config-phase.svg
- :align: center
- :alt: Zephyr's build configuration phase
- :figclass: align-center
- :width: 80%
-
-CMake begins by processing the :file:`CMakeLists.txt` file in the application
-directory, which refers to the :file:`CMakeLists.txt` file in the Zephyr
-top-level directory, which in turn refers to :file:`CMakeLists.txt` files
-throughout the build tree (directly and indirectly). Its primary output is a
-set of Makefiles or Ninja files to drive the build process, but the CMake
-scripts also do some processing of their own, which is explained here.
-
-Note that paths beginning with :file:`build/` below refer to the build
-directory you create when running CMake.
-
-Devicetree
- :file:`*.dts` (*devicetree source*) and :file:`*.dtsi` (*devicetree source
- include*) files are collected from the target's architecture, SoC, board,
- and application directories.
-
- :file:`*.dtsi` files are included by :file:`*.dts` files via the C
- preprocessor (often abbreviated *cpp*, which should not be confused with
- C++). The C preprocessor is also used to merge in any devicetree
- :file:`*.overlay` files, and to expand macros in :file:`*.dts`,
- :file:`*.dtsi`, and :file:`*.overlay` files. The preprocessor output is
- placed in :file:`build/zephyr/zephyr.dts.pre`.
-
- The preprocessed devicetree sources are parsed by
- :zephyr_file:`gen_defines.py <scripts/dts/gen_defines.py>` to generate a
- :file:`build/zephyr/include/generated/devicetree_unfixed.h` header with
- preprocessor macros.
-
- Source code should access preprocessor macros generated from devicetree by
- including the :zephyr_file:`devicetree.h <include/devicetree.h>` header,
- which includes :file:`devicetree_unfixed.h`.
-
- :file:`gen_defines.py` also writes the final devicetree to
- :file:`build/zephyr/zephyr.dts` in the build directory. This file's contents
- may be useful for debugging.
-
- If the devicetree compiler ``dtc`` is installed, it is run on
- :file:`build/zephyr/zephyr.dts` to catch any extra warnings and errors
- generated by this tool. The output from ``dtc`` is unused otherwise, and
- this step is skipped if ``dtc`` is not installed.
-
- The above is just a brief overview. For more information on devicetree, see
- :ref:`dt-guide`.
-
-Devicetree fixups
- Files named :file:`dts_fixup.h` from the target’s architecture, SoC, board,
- and application directories are concatenated into a single
- :file:`devicetree_fixups.h` file. :file:`dts_fixup.h` files are a legacy
- feature which should not be used in new code.
-
-Kconfig
- :file:`Kconfig` files define available configuration options for for the
- target architecture, SoC, board, and application, as well as dependencies
- between options.
-
- Kconfig configurations are stored in *configuration files*. The initial
- configuration is generated by merging configuration fragments from the board
- and application (e.g. :file:`prj.conf`).
-
- The output from Kconfig is an :file:`autoconf.h` header with preprocessor
- assignments, and a :file:`.config` file that acts both as a saved
- configuration and as configuration output (used by CMake). The definitions in
- :file:`autoconf.h` are automatically exposed at compile time, so there is no
- need to include this header.
-
- Information from devicetree is available to Kconfig, through the functions
- defined in :zephyr_file:`kconfigfunctions.py
- <scripts/kconfig/kconfigfunctions.py>`.
-
- See :ref:`the Kconfig section of the manual <kconfig>` for more information.
-
-Build Phase
------------
-
-The build phase begins when the user invokes ``make`` or ``ninja``. Its
-ultimate output is a complete Zephyr application in a format suitable for
-loading/flashing on the desired target board (:file:`zephyr.elf`,
-:file:`zephyr.hex`, etc.) The build phase can be broken down, conceptually,
-into four stages: the pre-build, first-pass binary, final binary, and
-post-processing.
-
-Pre-build
-+++++++++
-
-Pre-build occurs before any source files are compiled, because during
-this phase header files used by the source files are generated.
-
-Offset generation
- Access to high-level data structures and members is sometimes
- required when the definitions of those structures is not
- immediately accessible (e.g., assembly language). The generation of
- *offsets.h* (by *gen_offset_header.py*) facilitates this.
-
-System call boilerplate
- The *gen_syscall.py* and *parse_syscalls.py* scripts work
- together to bind potential system call functions with their
- implementations.
-
-.. figure:: build-build-phase-1.svg
- :align: center
- :alt: Zephyr's build stage I
- :figclass: align-center
- :width: 80%
-
-Intermediate binaries
-+++++++++++++++++++++
-
-Compilation proper begins with the first intermediate binary. Source files (C
-and assembly) are collected from various subsystems (which ones is
-decided during the configuration phase), and compiled into archives
-(with reference to header files in the tree, as well as those
-generated during the configuration phase and the pre-build stage(s)).
-
-.. figure:: build-build-phase-2.svg
- :align: center
- :alt: Zephyr's build stage II
- :figclass: align-center
- :width: 80%
-
-The exact number of intermediate binaries is decided during the configuration
-phase.
-
-If memory protection is enabled, then:
-
-Partition grouping
- The *gen_app_partitions.py* script scans all the
- generated archives and outputs linker scripts to ensure that
- application partitions are properly grouped and aligned for the
- target’s memory protection hardware.
-
-Then *cpp* is used to combine linker script fragments from the target’s
-architecture/SoC, the kernel tree, optionally the partition output if
-memory protection is enabled, and any other fragments selected during
-the configuration process, into a *linker.cmd* file. The compiled
-archives are then linked with *ld* as specified in the
-*linker.cmd*.
-
-Unfixed size binary
- The unfixed size intermediate binary is produced when :ref:`usermode_api`
- is enabled or :ref:`devicetree` is in use.
- It produces a binary where sizes are not fixed and thus it may be used
- by post-process steps that will impact the size of the final binary.
-
-.. figure:: build-build-phase-3.svg
- :align: center
- :alt: Zephyr's build stage III
- :figclass: align-center
- :width: 80%
-
-Fixed size binary
- The fixed size intermediate binary is produced when :ref:`usermode_api`
- is enabled or when generated IRQ tables are used,
- :kconfig:option:`CONFIG_GEN_ISR_TABLES`
- It produces a binary where sizes are fixed and thus the size must not change
- between the intermediate binary and the final binary.
-
-.. figure:: build-build-phase-4.svg
- :align: center
- :alt: Zephyr's build stage IV
- :figclass: align-center
- :width: 80%
-
-Intermediate binaries post-processing
-+++++++++++++++++++++++++++++++++++++
-
-The binaries from the previous stage are incomplete, with empty and/or
-placeholder sections that must be filled in by, essentially, reflection.
-
-To complete the build procedure the following scripts are executed on the
-intermediate binaries to produce the missing pieces needed for the final
-binary.
-
-When :ref:`usermode_api` is enabled:
-
-Partition alignment
- The *gen_app_partitions.py* script scans the unfixed size binary and
- generates an app shared memory aligned linker script snippet where the
- partitions are sorted in descending order.
-
-.. figure:: build-postprocess-1.svg
- :align: center
- :alt: Zephyr's intermediate binary post-process I
- :figclass: align-center
- :width: 80%
-
-When :ref:`devicetree` is used:
-
-Device dependencies
- The *gen_handles.py* script scans the unfixed size binary to determine
- relationships between devices that were recorded from devicetree data,
- and replaces the encoded relationships with values that are optimized to
- locate the devices actually present in the application.
-
-.. figure:: build-postprocess-2.svg
- :align: center
- :alt: Zephyr's intermediate binary post-process II
- :figclass: align-center
- :width: 80%
-
-When :kconfig:option:`CONFIG_GEN_ISR_TABLES` is enabled:
- The *gen_isr_tables.py* script scant the fixed size binary and creates
- an isr_tables.c source file with a hardware vector table and/or software
- IRQ table.
-
-.. figure:: build-postprocess-3.svg
- :align: center
- :alt: Zephyr's intermediate binary post-process III
- :figclass: align-center
- :width: 80%
-
-When :ref:`usermode_api` is enabled:
-
-Kernel object hashing
- The *gen_kobject_list.py* scans the *ELF DWARF*
- debug data to find the address of the all kernel objects. This
- list is passed to *gperf*, which generates a perfect hash function and
- table of those addresses, then that output is optimized by
- *process_gperf.py*, using known properties of our special case.
-
-.. figure:: build-postprocess-4.svg
- :align: center
- :alt: Zephyr's intermediate binary post-process IV
- :figclass: align-center
- :width: 80%
-
-When no intermediate binary post-processing is required then the first
-intermediate binary will be directly used as the final binary.
-
-Final binary
-++++++++++++
-
-The binary from the previous stage is incomplete, with empty and/or
-placeholder sections that must be filled in by, essentially, reflection.
-
-The link from the previous stage is repeated, this time with the missing
-pieces populated.
-
-.. figure:: build-build-phase-5.svg
- :align: center
- :alt: Zephyr's build final stage
- :figclass: align-center
- :width: 80%
-
-Post processing
-+++++++++++++++
-
-Finally, if necessary, the completed kernel is converted from *ELF* to
-the format expected by the loader and/or flash tool required by the
-target. This is accomplished in a straightforward manner with *objdump*.
-
-.. figure:: build-build-phase-6.svg
- :align: center
- :alt: Zephyr's build final stage post-process
- :figclass: align-center
- :width: 80%
-
-
-.. _build_system_scripts:
-
-Supporting Scripts and Tools
-============================
-
-The following is a detailed description of the scripts used during the build process.
-
-.. _gen_syscalls.py:
-
-:zephyr_file:`scripts/gen_syscalls.py`
---------------------------------------
-
-.. include:: ../../scripts/gen_syscalls.py
- :start-after: """
- :end-before: """
-
-.. _gen_handles.py:
-
-:zephyr_file:`scripts/gen_handles.py`
---------------------------------------
-
-.. include:: ../../scripts/gen_handles.py
- :start-after: """
- :end-before: """
-
-.. _gen_kobject_list.py:
-
-:zephyr_file:`scripts/gen_kobject_list.py`
-------------------------------------------
-
-.. include:: ../../scripts/gen_kobject_list.py
- :start-after: """
- :end-before: """
-
-.. _gen_offset_header.py:
-
-:zephyr_file:`scripts/gen_offset_header.py`
--------------------------------------------
-
-.. include:: ../../scripts/gen_offset_header.py
- :start-after: """
- :end-before: """
-
-.. _parse_syscalls.py:
-
-:zephyr_file:`scripts/parse_syscalls.py`
-----------------------------------------
-
-
-.. include:: ../../scripts/parse_syscalls.py
- :start-after: """
- :end-before: """
-
-.. _gen_idt.py:
-
-:zephyr_file:`arch/x86/gen_idt.py`
-----------------------------------
-
-.. include:: ../../arch/x86/gen_idt.py
- :start-after: """
- :end-before: """
-
-.. _gen_gdt.py:
-
-:zephyr_file:`arch/x86/gen_gdt.py`
-----------------------------------
-
-.. include:: ../../arch/x86/gen_gdt.py
- :start-after: """
- :end-before: """
-
-.. _gen_relocate_app.py:
-
-:zephyr_file:`scripts/gen_relocate_app.py`
--------------------------------------------
-
-.. include:: ../../scripts/gen_relocate_app.py
- :start-after: """
- :end-before: """
-
-.. _process_gperf.py:
-
-:zephyr_file:`scripts/process_gperf.py`
----------------------------------------
-
-.. include:: ../../scripts/process_gperf.py
- :start-after: """
- :end-before: """
-
-:zephyr_file:`scripts/gen_app_partitions.py`
---------------------------------------------
-
-.. include:: ../../scripts/gen_app_partitions.py
- :start-after: """
- :end-before: """
-
-.. _kconfig:
-
-Configuration System (Kconfig)
-*******************************
-
-The Zephyr kernel and subsystems can be configured at build time to adapt them
-for specific application and platform needs. Configuration is handled through
-Kconfig, which is the same configuration system used by the Linux kernel. The
-goal is to support configuration without having to change any source code.
-
-Configuration options (often called *symbols*) are defined in :file:`Kconfig`
-files, which also specify dependencies between symbols that determine what
-configurations are valid. Symbols can be grouped into menus and sub-menus to
-keep the interactive configuration interfaces organized.
-
-The output from Kconfig is a header file :file:`autoconf.h` with macros that
-can be tested at build time. Code for unused features can be compiled out to
-save space.
-
-The following sections explain how to set Kconfig configuration options, go
-into detail on how Kconfig is used within the Zephyr project, and have some
-tips and best practices for writing :file:`Kconfig` files.
-
.. toctree::
:maxdepth: 1
- kconfig/menuconfig.rst
- kconfig/setting.rst
- kconfig/tips.rst
- kconfig/preprocessor-functions.rst
- kconfig/extensions.rst
-Users interested in optimizing their configuration for security should refer
-to the Zephyr Security Guide's section on the :ref:`hardening`.
+ cmake/index.rst
+ kconfig/index.rst
diff --git a/doc/build/kconfig/index.rst b/doc/build/kconfig/index.rst
new file mode 100644
index 0000000..b59213d
--- /dev/null
+++ b/doc/build/kconfig/index.rst
@@ -0,0 +1,34 @@
+.. _kconfig:
+
+Configuration System (Kconfig)
+*******************************
+
+The Zephyr kernel and subsystems can be configured at build time to adapt them
+for specific application and platform needs. Configuration is handled through
+Kconfig, which is the same configuration system used by the Linux kernel. The
+goal is to support configuration without having to change any source code.
+
+Configuration options (often called *symbols*) are defined in :file:`Kconfig`
+files, which also specify dependencies between symbols that determine what
+configurations are valid. Symbols can be grouped into menus and sub-menus to
+keep the interactive configuration interfaces organized.
+
+The output from Kconfig is a header file :file:`autoconf.h` with macros that
+can be tested at build time. Code for unused features can be compiled out to
+save space.
+
+The following sections explain how to set Kconfig configuration options, go
+into detail on how Kconfig is used within the Zephyr project, and have some
+tips and best practices for writing :file:`Kconfig` files.
+
+.. toctree::
+ :maxdepth: 1
+
+ menuconfig.rst
+ setting.rst
+ tips.rst
+ preprocessor-functions.rst
+ extensions.rst
+
+Users interested in optimizing their configuration for security should refer
+to the Zephyr Security Guide's section on the :ref:`hardening`.
