build: namespace the generated headers with zephyr/

Namespaced the generated headers with `zephyr` to prevent
potential conflict with other headers.

Introduce a temporary Kconfig `LEGACY_GENERATED_INCLUDE_PATH`
that is enabled by default. This allows the developers to
continue the use of the old include paths for the time being
until it is deprecated and eventually removed. The Kconfig will
generate a build-time warning message, similar to the
`CONFIG_TIMER_RANDOM_GENERATOR`.

Updated the includes path of in-tree sources accordingly.

Most of the changes here are scripted, check the PR for more
info.

Signed-off-by: Yong Cong Sin <ycsin@meta.com>

doc/build/cmake/index.rst

@@ -88,7 +88,7 @@ Devicetree
 
    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_generated.h` header with
+   :file:`build/zephyr/include/generated/zephyr/devicetree_generated.h` header with
    preprocessor macros.
 
    Source code should access preprocessor macros generated from devicetree by

doc/build/dts/howtos.rst

@@ -42,7 +42,7 @@ CMake prints the input and output file locations like this:
 
    -- Found BOARD.dts: .../zephyr/boards/arm/qemu_cortex_m3/qemu_cortex_m3.dts
    -- Generated zephyr.dts: .../zephyr/build/zephyr/zephyr.dts
-   -- Generated devicetree_generated.h: .../zephyr/build/zephyr/include/generated/devicetree_generated.h
+   -- Generated devicetree_generated.h: .../zephyr/build/zephyr/include/generated/zephyr/devicetree_generated.h
 
 The :file:`zephyr.dts` file is the final devicetree in DTS format.
 

doc/build/dts/intro-input-output.rst

@@ -129,7 +129,7 @@ These are created in your application's build directory.
    input to :file:`gen_defines.py` and used to create :file:`zephyr.dts` and
    :file:`devicetree_generated.h`.
 
-:file:`<build>/zephyr/include/generated/devicetree_generated.h`
+:file:`<build>/zephyr/include/generated/zephyr/devicetree_generated.h`
    The generated macros and additional comments describing the devicetree.
    Included by ``devicetree.h``.
 

doc/build/dts/troubleshooting.rst

@@ -66,7 +66,7 @@ Below, ``<build>`` means your build directory.
 
 To find the devicetree node you need to check, use the number ``<N>`` from the
 linker error. Look for this number in the list of nodes at the top of
-:file:`<build>/zephyr/include/generated/devicetree_generated.h`. For example, if
+:file:`<build>/zephyr/include/generated/zephyr/devicetree_generated.h`. For example, if
 ``<N>`` is 15, and your :file:`devicetree_generated.h` file looks like this,
 the node you are interested in is ``/soc/i2c@deadbeef``:
 

doc/kernel/drivers/index.rst

@@ -203,7 +203,7 @@ A device-specific API definition typically looks like this:
    __syscall int specific_from_user(const struct device *dev, int bar);
 
    /* Only needed when extensions include syscalls */
-   #include <syscalls/specific.h>
+   #include <zephyr/syscalls/specific.h>
 
 A driver implementing extensions to the subsystem will define the real
 implementation of both the subsystem API and the specific APIs:
@@ -243,7 +243,7 @@ implementation of both the subsystem API and the specific APIs:
        return z_impl_specific_do_that(dev, bar)
    }
 
-   #include <syscalls/specific_from_user_mrsh.c>
+   #include <zephyr/syscalls/specific_from_user_mrsh.c>
 
    #endif /* CONFIG_USERSPACE */
 

doc/kernel/usermode/syscalls.rst

@@ -87,7 +87,7 @@ bottom of ``include/sensor.h``:
 
 .. code-block:: c
 
-    #include <syscalls/sensor.h>
+    #include <zephyr/syscalls/sensor.h>
 
 C prototype functions must be declared in one of the directories
 listed in the CMake variable ``SYSCALL_INCLUDE_DIRS``. This list
@@ -143,7 +143,7 @@ C and header files by the :ref:`gen_syscalls.py` script, all of which can be fou
 the project out directory under ``include/generated/``:
 
 * The system call is added to the enumerated type of system call IDs,
-  which is expressed in ``include/generated/syscall_list.h``. It is the name
+  which is expressed in ``include/generated/zephyr/syscall_list.h``. It is the name
   of the API in uppercase, prefixed with ``K_SYSCALL_``.
 
 * An entry for the system call is created in the dispatch table
@@ -172,7 +172,7 @@ The body of the API is created in the generated system header. Using the
 example of :c:func:`k_sem_init()`, this API is declared in
 ``include/kernel.h``. At the bottom of ``include/kernel.h`` is::
 
-    #include <syscalls/kernel.h>
+    #include <zephyr/syscalls/kernel.h>
 
 Inside this header is the body of :c:func:`k_sem_init()`::
 
@@ -362,7 +362,7 @@ For example:
         K_OOPS(K_SYSCALL_OBJ(sem, K_OBJ_SEM));
         return z_impl_k_sem_take(sem, timeout);
     }
-    #include <syscalls/k_sem_take_mrsh.c>
+    #include <zephyr/syscalls/k_sem_take_mrsh.c>
 
 
 Verification Memory Access Policies

doc/services/retention/blinfo.rst

@@ -122,7 +122,7 @@ this mode:
 
 	#include <bootutil/boot_status.h>
 	#include <bootutil/image.h>
-	#include <mcuboot_version.h>
+	#include <zephyr/mcuboot_version.h>
 	#include <zephyr/settings/settings.h>
 
 API Reference