Skip to content

kernel/user partition, Phase 4 part 6: move kernel-only headers to sof/kernel - #11487

Merged
lgirdwood merged 7 commits into
thesofproject:mainfrom
lgirdwood:kernel-user/phase4f
Nov 19, 2026
Merged

lgirdwood merged 7 commits into
thesofproject:mainfrom
lgirdwood:kernel-user/phase4f

Conversation

@lgirdwood

@lgirdwood lgirdwood commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

Phase 4 of #11306 (kernel / user-space partition), sixth part: start moving the kernel-only headers to src/kernel/include/sof/kernel/, included as <sof/kernel/...>, as the issue plans. This moves the headers that no user-space source includes and that have no host replacement.

Why

With the header untangling of the previous parts, these headers are only included by kernel code. Moving them makes a kernel-only include visible in the source: user-space code that writes <sof/kernel/...> is obviously wrong, and a checkpatch rule can catch it later. It is also a step towards keeping the kernel headers off the user-space include path.

What changes

  • New src/kernel/include: it is on the include path of the firmware (the SOF interface library, which sof_kernel and modules_sof use), of the host library, of the testbench and the topology parser, and of the seven ZTest unit tests that build kernel sources. It is also in the Doxygen input. It is not on the include path of the LLEXT modules, which build fine without it. The include checker treats everything below it as kernel-only.

  • Moved headers:

    Old include New include
    sof/platform.h sof/kernel/platform.h
    sof/ipc/driver.h sof/kernel/ipc/driver.h
    sof/llext_manager.h sof/kernel/llext_manager.h
    sof/drivers/{acp_dai_dma,afe-dai,afe-drv,afe-memif,cache_attr,edma,interrupt-map,mu,ssp}.h sof/kernel/drivers/...
    sof/lib/regions_mm.h, sof/lib/vpage.h (from zephyr/include) sof/kernel/lib/...

    Every include is rewritten, and so are the code owner entries, the Doxygen main page references and the platform headers' include guard errors that name sof/platform.h.

  • Removed: sof/drivers/dmic.h and sof/drivers/pmc.h, with the host platform pmc.h that it wraps. Nothing includes them.

Not moved yet

  • Host replacements: the kernel-only headers that the host builds replace with their own copies in posix/include: rtos/idc.h, sof/lib/io.h and sof/lib/mm_heap.h. Moving these needs a decision on the host copies.
  • Still reached by user code: the headers that the 16 baseline sources include: rtos/timer.h, rtos/interrupt.h, rtos/clk.h, rtos/userspace_helper.h, the memory map, perf_cnt.h, agent.h, cpu-clk-manager.h, watchdog.h and pm_runtime.h. They move once Phase 5 removes those uses.
  • Legacy drivers: dma-legacy.h and interrupt-legacy.h, which Phase 0 removes with the legacy drivers.

Patches

  1. kernel: add src/kernel/include to the include paths and the checker, and describe it in the src/kernel README. The ZTest unit tests list their include directories themselves. Only the seven that build kernel sources get it: audio/drc, fast-get, math/fft and math/{auditory,dct,fft_multi,matrix}, which build zephyr/lib/alloc.c. The others stay without it, so they cannot include kernel-only headers.
  2. platform: move sof/platform.h, and add src/kernel/include/sof to the Doxygen input for the main page reference to it.
  3. ipc: move sof/ipc/driver.h.
  4. library_manager: move sof/llext_manager.h.
  5. drivers: move the sof/drivers headers.
  6. lib: move regions_mm.h and vpage.h.
  7. drivers: remove dmic.h and pmc.h.

Functional change

None.

Testing

  • Include checker: with --strict, it passes for each of the 12 CI build configurations, built locally as CI does (repro-build.conf, -Werror), and for every other configuration below, with the same 16 baseline sources.
  • Per commit, compared with main:
    • Builds: tgl, tgl-h, mtl, lnl, ptl, wcl, nvl, imx8, imx8x, imx8m, imx8m_cm7, imx8ulp, imx95 and qemu_xtensa, and the extra CI configurations:

      • native_sim IPC3/IPC4 stub builds;
      • imx93 64-bit;
      • PTL with each userspace overlay;
      • PTL with CONFIG_SOF_USERSPACE_PROXY=n;
      • PTL and MTL with os_linux_overlay.conf;llext_relocatable.conf;
      • PTL and TGL with app/debug_stream_overlay.conf, and PTL with that overlay and user-space LL.

      The PTL and MTL builds include LLEXT modules.

    • Comparisons: objects, LLEXT modules and firmware images (sections, symbols, SYS_INIT() order), and the per-function disassembly. No object changes at any commit. The only image difference is sof_init() on imx8m_cm7, imx93 and imx95, which embeds the git hash.

    • Signing: rimage runs for every Intel platform, and the generated configs are unchanged.

    • Cadence xt-clang (RI-2022.10): MTL, PTL and NVL compile.

    • ZTest: the unit tests pass, run as in CI (20 of 20 configurations).

    • Host: the host library and the cmocka unit tests build and pass.

  • At the tip:
    • the testbench and the tools pass;
    • the host library and the cmocka unit tests pass for all nine defconfigs and the library config;
    • the platforms that already fail on main (acp_6_0, acp_7_0, acp_7_x, mt8186, mt8188, mt8195, mt8196, mt8365) have unchanged error sets. Their drivers use the moved sof/drivers headers.

All of the above, and the documentation build as in CI (no warnings, at every commit), was run on 6f356a4 (current main).

Changes since the last push

  • Doxygen (review): src/kernel/include/sof is in the Doxygen input (from patch 2, which creates the directory), so the main page references to the moved headers resolve, and the @file tags of regions_mm.h and vpage.h name their new paths. Before, the documentation build had three unresolved reference warnings.
  • ZTest include paths (review): only the seven unit tests that build kernel sources get src/kernel/include.
  • Rebased onto current main.

🤖 Generated with Claude Code

@lgirdwood lgirdwood left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review Summary

Cleanly structured, bisectable 7-commit series:

  • Moves all 15 kernel-only headers (platform.h, ipc/driver.h, llext_manager.h, drivers/*.h, lib/regions_mm.h, lib/vpage.h) into src/kernel/include/sof/kernel/... with zero leftover files in src/include/sof/drivers/ or zephyr/include/sof/drivers/, zero __syscall / userspace partition markers inside src/kernel/include/, and CODEOWNERS + src/kernel/README.md updated.
  • LLEXT isolation works immediately (sof_llext_build only passes ${SOF_BASE}/src/include to ${module}_llext_lib, not the SOF interface target).

Blocking — doxygen CI Failure (2-Layer Fix Required)

  1. doc/sof.doxygen.in (INPUT, lines 19–21): Add @top_srcdir@/src/kernel/include/sof \ so Doxygen resolves the updated @ref src/kernel/include/sof/kernel/... links in doc/mainpage.dox (lines 170, 171, 235).
  2. Stale @file tags in 100%-renamed headers (exposed as soon as doc/sof.doxygen.in scans src/kernel/include/sof with WARN_AS_ERROR = FAIL_ON_WARNINGS):
    • src/kernel/include/sof/kernel/lib/regions_mm.h:9: @file sof/lib/regions_mm.h -> @file sof/kernel/lib/regions_mm.h
    • src/kernel/include/sof/kernel/lib/vpage.h:5: @file sof/lib/vpage.h -> @file sof/kernel/lib/vpage.h

Non-Blocking Notes

  • ZTest include paths (Commit 1): Only 3 of the 16 modified ZTest CMakeLists.txt files (audio/drc, math/fft, fast-get) compile kernel/zephyr-lib sources that include <sof/kernel/...> (see inline note).
  • Future Phase 4 radar (acp_6_0 / non-native mtk): Pre-existing, not introduced here — src/schedule/zephyr_dma_domain.c, src/schedule/ll_schedule_xtos.c, and src/schedule/dma_multi_chan_domain.c live under src/ ([user-sources]), include <sof/kernel/platform.h>, and are outside [not-user-sources] / [leak-baseline] in scripts/kernel_user_partition.txt (unexercised by .github/workflows/zephyr.yml since acp_6_0 and mt81* aren't in that CI matrix).

Comment thread doc/mainpage.dox
Comment on lines +170 to +171
* - @ref src/kernel/include/sof/kernel/lib/regions_mm.h "sof/kernel/lib/regions_mm.h"<br/>
* - @ref src/kernel/include/sof/kernel/lib/vpage.h "sof/kernel/lib/vpage.h"<br/>

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Blocking (doxygen CI failure): Updating these @ref targets (plus line 235 for platform.h) fails in CI because doc/sof.doxygen.in does not list @top_srcdir@/src/kernel/include/sof in INPUT:

--- a/doc/sof.doxygen.in
+++ b/doc/sof.doxygen.in
@@ -19,6 +19,7 @@ INPUT            = @top_srcdir@/src/include/ipc \
                    @top_srcdir@/src/include/kernel \
                    @top_srcdir@/src/include/user \
                    @top_srcdir@/src/include/sof \
+                   @top_srcdir@/src/kernel/include/sof \
                    @top_srcdir@/zephyr/include \

Note that once @top_srcdir@/src/kernel/include/sof is added to INPUT, Doxygen also flags the stale @file paths in the two pure-rename headers from commit 7 (WARN_AS_ERROR = FAIL_ON_WARNINGS):

  • src/kernel/include/sof/kernel/lib/regions_mm.h:9: change @file sof/lib/regions_mm.h -> @file sof/kernel/lib/regions_mm.h
  • src/kernel/include/sof/kernel/lib/vpage.h:5: change @file sof/lib/vpage.h -> @file sof/kernel/lib/vpage.h

Applying all three makes ninja -C docbuild doc pass cleanly.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed. src/kernel/include/sof is now in the Doxygen INPUT, added in the sof/platform.h commit, which creates the directory (adding it in the first commit gives a "does not exist" warning there). The @file tags of regions_mm.h and vpage.h name their new paths. The documentation build, as CI runs it, now has no warnings at any commit; before, it had the three unresolved references.

target_include_directories(app PRIVATE
${SOF_ROOT}/zephyr/include
${SOF_ROOT}/src/include
${SOF_ROOT}/src/kernel/include

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit (non-blocking): Commit 1 notes adding src/kernel/include for ZTest unit tests that build kernel sources, which applies to audio/drc, math/fft, and fast-get. Pure user-safe / shared-library unit tests (math/basic/{arithmetic,complex,trigonometry}, math/{a_law,mu_law,window,dft3,dct,fft_multi,matrix,auditory,advanced/functions}, audio/{crossover,selector}, dsrc, objpool) don't pull in <sof/kernel/...> headers — dropping ${SOF_ROOT}/src/kernel/include from those 13 CMakeLists.txt files (like test/ztest/unit/list/CMakeLists.txt) preserves compile-time checks that they stay free of kernel-only includes.

Suggested change
${SOF_ROOT}/src/kernel/include

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, done for the 12 unit tests that build no kernel sources (audio/{crossover,selector}, dsrc, objpool, math/{a_law,mu_law,window,dft3}, math/basic/{arithmetic,complex,trigonometry} and math/advanced/functions); they pass without it. Seven keep it, not three: besides audio/drc, math/fft and fast-get, the math/{auditory,dct,fft_multi,matrix} tests build zephyr/lib/alloc.c, which includes <sof/kernel/drivers/interrupt-map.h>. Without the directory those four fail to build.

lrgirdwo and others added 7 commits November 19, 2026 13:04
Phase 4 of the kernel / user-space partition moves the kernel-only
headers to src/kernel/include/sof/kernel, included as
<sof/kernel/...>, so that kernel-only includes are visible in the
source and the headers can later be kept off the user-space include
path.

Add the directory to the include path of the firmware (the SOF
interface library that sof_kernel and modules_sof use, so not the
LLEXT modules), of the host library, of the testbench and the
topology parser, and of the ZTest unit tests that build kernel
sources. The include checker treats everything below it as
kernel-only. The headers move in the following commits.

No functional change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
sof/platform.h declares the platform init, boot and context save
functions and includes the platform definitions. Only kernel code
includes it. Move it to src/kernel/include and include it as
<sof/kernel/platform.h>, and update the platform headers that name it
in their include guard errors. Add src/kernel/include/sof to the
Doxygen input, for the main page reference to it.

No functional change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
sof/ipc/driver.h is the interface between the IPC core and the
platform IPC driver: message transmit and receive, the IPC task and
the host page tables. Only kernel code, and the host testbench and
unit tests built with the kernel code, include it. Move it to
src/kernel/include and include it as <sof/kernel/ipc/driver.h>.

No functional change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
sof/llext_manager.h declares the LLEXT loader and its dependency
handling, which only the kernel library manager code uses. Move it to
src/kernel/include and include it as <sof/kernel/llext_manager.h>.

No functional change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
The headers in sof/drivers describe the AMD, MediaTek and i.MX DAI
and DMA drivers, the i.MX messaging unit, the SSP and the interrupt
map. Only kernel code includes them. Move them to src/kernel/include
and include them as <sof/kernel/drivers/...>, and update the code
owner entries.

dmic.h and pmc.h are not used anymore and stay for now.

No functional change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
sof/lib/regions_mm.h (the virtual memory heaps) and sof/lib/vpage.h
(the virtual page allocator) are the interfaces of kernel memory
management code. Only kernel code and its tests include them. Move
them to src/kernel/include and include them as
<sof/kernel/lib/regions_mm.h> and <sof/kernel/lib/vpage.h>.

No functional change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Nothing includes sof/drivers/dmic.h, the definitions of the removed
SOF DMIC driver, or sof/drivers/pmc.h and the host platform pmc.h
that it wraps. Remove them, with their code owner and include checker
entries, instead of moving them to the kernel headers.

No functional change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
@lgirdwood

Copy link
Copy Markdown
Member Author

Thanks, both review comments are addressed in the force-push (details inline and under "Changes since the last push"). On the legacy LL scheduling domains under src/schedule that include <sof/kernel/platform.h>: #11489 classifies them as kernel sources, like the legacy host and DAI drivers, and adds a source-tree check that fails on <sof/kernel/...> includes from user-space code, so such cases are caught even when no CI configuration builds the file.

@intel-sofci

Copy link
Copy Markdown

PR 11487: test results

Run date: 2026-11-19 15:55 UTC

Tested commit: e009533b9e3e60ca02337cb8d15cce8f3190cab5

mtl pass rate lnl pass rate ptl pass rate wcl pass rate nvl pass rate

@lgirdwood
lgirdwood merged commit 412057e into thesofproject:main Nov 19, 2026
45 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants