Repository navigation
kernel/user partition, Phase 4 part 4: move the mailbox headers to src/platform - #11476
Merged
Merged
Conversation
Collaborator
|
@lgirdwood part 3 merged, ready for this one |
Contributor
There was a problem hiding this comment.
🟢 Approval recommended
No active review issues remain to block approval of the mailbox-header separation change.
No open issues 🎉
What changed in this PR
Continues SOF’s kernel/user-space separation under #11306 by moving user-visible mailbox headers into src/platform. Built on #11470, this separates mailbox access from kernel memory maps without intended runtime changes.
Changes:
- Relocate mailbox headers and extract unchanged window layouts for Intel, i.MX, simulator and host-library platforms.
- Update firmware, tooling and test include paths, with explicit includes replacing removed transitive dependencies.
- Document the boundary, retain i.MX8 ownership and reduce the include-checker baseline from 29 to 22 sources beyond #11470.
| File | Description |
|---|---|
zephyr/wrapper.c |
Explicitly includes register helpers and memory definitions. |
zephyr/lib/cpu.c |
Adds direct memory and platform dependencies. |
zephyr/lib/alloc.c |
Adds the required platform include. |
zephyr/include/sof/lib/dma.h |
Removes transitive register and memory-map includes. |
zephyr/include/sof/lib/dma-legacy.h |
Keeps register helpers available to legacy DMA. |
zephyr/include/rtos/timer.h |
Removes the transitive platform include. |
zephyr/CMakeLists.txt |
Adds user-visible platform include directories. |
tools/tplg_parser/CMakeLists.txt |
Adds the relocated host-library header path. |
tools/testbench/CMakeLists.txt |
Adds the relocated host-library header path. |
test/ztest/unit/objpool/CMakeLists.txt |
Adds the user-visible POSIX header path. |
test/ztest/unit/math/matrix/CMakeLists.txt |
Adds the user-visible POSIX header path. |
test/ztest/unit/math/fft/CMakeLists.txt |
Adds the user-visible POSIX header path. |
test/ztest/unit/math/fft_multi/CMakeLists.txt |
Adds the user-visible POSIX header path. |
test/ztest/unit/math/dct/CMakeLists.txt |
Adds the user-visible POSIX header path. |
test/ztest/unit/math/auditory/CMakeLists.txt |
Adds the user-visible POSIX header path. |
test/ztest/unit/math/advanced/functions/CMakeLists.txt |
Adds the user-visible POSIX header path. |
test/ztest/unit/fast-get/CMakeLists.txt |
Adds the user-visible POSIX header path. |
test/ztest/unit/dsrc/CMakeLists.txt |
Adds the user-visible POSIX header path. |
test/ztest/unit/audio/drc/CMakeLists.txt |
Adds the user-visible POSIX header path. |
test/ztest/unit/audio/crossover/CMakeLists.txt |
Adds the user-visible POSIX header path. |
test/cmocka/src/lib/alloc/CMakeLists.txt |
Adds the relocated shared cAVS header path. |
test/cmocka/CMakeLists.txt |
Adds relocated shared cAVS and ACE header paths. |
src/platform/tigerlake/include/platform/lib/mailbox.h |
Relocates the Tiger Lake mailbox wrapper unchanged. |
src/platform/tigerlake/include/platform/lib/mailbox_layout.h |
Extracts Tiger Lake mailbox window constants. |
src/platform/README.md |
Documents user-safe platform headers and mapped windows. |
src/platform/qemu_xtensa/include/platform/lib/mailbox.h |
Relocates the QEMU mailbox stub unchanged. |
src/platform/posix/include/platform/lib/mailbox.h |
Uses the extracted POSIX mailbox layout. |
src/platform/posix/include/platform/lib/mailbox_layout.h |
Extracts POSIX mailbox declarations and byte-addressed bases. |
src/platform/novalake/include/platform/lib/mailbox.h |
Relocates the Nova Lake mailbox wrapper unchanged. |
src/platform/novalake/include/platform/lib/mailbox_layout.h |
Extracts Nova Lake devicetree-backed window definitions. |
src/platform/meteorlake/include/platform/lib/mailbox.h |
Relocates the Meteor Lake mailbox wrapper unchanged. |
src/platform/meteorlake/include/platform/lib/mailbox_layout.h |
Extracts Meteor Lake devicetree-backed window definitions. |
src/platform/lunarlake/include/platform/lib/mailbox.h |
Relocates the Lunar Lake mailbox wrapper unchanged. |
src/platform/lunarlake/include/platform/lib/mailbox_layout.h |
Extracts Lunar Lake devicetree-backed window definitions. |
src/platform/library/include/platform/lib/mailbox.h |
Uses the extracted host-library mailbox layout. |
src/platform/library/include/platform/lib/mailbox_layout.h |
Extracts the mailbox getter declaration and base macro. |
src/platform/intel/cavs/include/cavs/lib/mailbox.h |
Replaces the memory map with layout and cache includes. |
src/platform/intel/ace/include/ace/lib/mailbox.h |
Replaces the memory map with layout and cache includes. |
src/platform/imx95/include/platform/lib/mailbox.h |
Relocates i.MX95 mailbox definitions unchanged. |
src/platform/imx93_a55/include/platform/lib/mailbox.h |
Relocates i.MX93 mailbox definitions unchanged. |
src/platform/imx8ulp/include/platform/lib/mailbox.h |
Uses the extracted i.MX8ULP mailbox layout. |
src/platform/imx8ulp/include/platform/lib/mailbox_layout.h |
Extracts i.MX8ULP window constants and SDRAM base. |
src/platform/imx8m/include/platform/lib/mailbox.h |
Uses the extracted i.MX8M mailbox layout. |
src/platform/imx8m/include/platform/lib/mailbox_layout.h |
Extracts i.MX8M window constants and SDRAM base. |
src/platform/imx8m_cm7/include/platform/lib/mailbox.h |
Relocates i.MX8M CM7 mailbox definitions unchanged. |
src/platform/imx8/include/platform/lib/mailbox.h |
Uses the extracted i.MX8 mailbox layout. |
src/platform/imx8/include/platform/lib/mailbox_layout.h |
Extracts i.MX8 window constants and SDRAM base. |
src/platform/ace30/include/platform/lib/mailbox.h |
Relocates the ACE 3.0 mailbox wrapper unchanged. |
src/platform/ace30/include/platform/lib/mailbox_layout.h |
Extracts ACE 3.0 devicetree-backed window definitions. |
src/kernel/platform/tigerlake/include/platform/lib/memory.h |
Imports the extracted Tiger Lake mailbox layout. |
src/kernel/platform/README.md |
Documents the mailbox headers’ new user-visible location. |
src/kernel/platform/posix/posix.c |
Explicitly includes clock definitions. |
src/kernel/platform/posix/include/platform/lib/memory.h |
Imports the extracted POSIX mailbox layout. |
src/kernel/platform/novalake/include/platform/lib/memory.h |
Imports the extracted Nova Lake mailbox layout. |
src/kernel/platform/meteorlake/include/platform/lib/memory.h |
Imports the extracted Meteor Lake mailbox layout. |
src/kernel/platform/lunarlake/include/platform/lib/memory.h |
Imports the extracted Lunar Lake mailbox layout. |
src/kernel/platform/library/include/platform/lib/memory.h |
Imports the extracted host-library mailbox definitions. |
src/kernel/platform/imx8ulp/include/platform/lib/memory.h |
Imports the extracted i.MX8ULP mailbox layout. |
src/kernel/platform/imx8m/include/platform/lib/memory.h |
Imports the extracted i.MX8M mailbox layout. |
src/kernel/platform/imx8/include/platform/lib/memory.h |
Imports the extracted i.MX8 mailbox layout. |
src/kernel/platform/ace30/include/platform/lib/memory.h |
Imports the extracted ACE 3.0 mailbox layout. |
src/kernel/ipc/ipc3/host-page-table.c |
Explicitly includes memory definitions. |
src/kernel/audio/base_fw.c |
Explicitly includes memory definitions for HOST_PAGE_SIZE. |
src/kernel/audio/base_fw_intel.c |
Adds the required platform include. |
src/kernel/arch/host/CMakeLists.txt |
Exposes relocated host-library platform headers. |
src/include/sof/schedule/ll_schedule_domain.h |
Limits the clock include to non-Zephyr builds. |
src/include/sof/lib/mailbox.h |
Removes the kernel memory-map dependency. |
src/audio/dai-zephyr.c |
Explicitly preserves platform address-translation definitions. |
scripts/kernel_user_partition.txt |
Allows mailbox and DMA type headers; shrinks the baseline. |
CODEOWNERS |
Extends i.MX8 ownership to the new header directory. |
Review effort: Balanced
Platform headers are kernel headers, in src/kernel/platform, but some of them define what user-space code needs, such as the mailbox window layout. Those parts move to src/platform, with the same layout and include names, so that the platform include directories in src/kernel/platform can become kernel-only. Add the platform's directory in src/platform to the include path. No platform has one yet. It is added even when it does not exist, so that existing build directories find it once it does, without running CMake again. No functional change. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: Liam Girdwood <[email protected]>
The mailbox window addresses and software register accessors are used by user-space code through sof/lib/mailbox.h: the software register page and the host box are mapped into the user-space LL and IPC threads. But they come from the platform mailbox headers, which use the window layout in the platform memory map, so every user of the mailbox gets the whole memory map. For the ACE platforms (MTL, LNL, PTL/WCL and NVL), move the shared ace/lib/mailbox.h and the platform mailbox headers to src/platform, and move the window layout out of each memory map into a new platform/lib/mailbox_layout.h there. The memory maps include it, and ace/lib/mailbox.h includes it, and rtos/cache.h for its accessors, instead of the memory map. No functional change. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: Liam Girdwood <[email protected]>
As for the ACE platforms, move the shared cavs/lib/mailbox.h and the TGL mailbox header to src/platform, and move the window layout out of the TGL memory map into platform/lib/mailbox_layout.h there, with the HP SRAM base address that the windows are at. The memory map includes it, and cavs/lib/mailbox.h includes it, and rtos/cache.h for its accessors, instead of the memory map. No functional change. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: Liam Girdwood <[email protected]>
Move the i.MX mailbox headers to src/platform. On imx8, imx8m and imx8ulp they used the window layout of the memory map: move it to platform/lib/mailbox_layout.h there, with the SDRAM1 base address that the mailbox is at, and include it from the memory map and the mailbox header instead of the memory map. The imx8m_cm7, imx93 and imx95 mailbox headers define the windows themselves. Add src/platform/imx8 to the imx8 code owner entry. No functional change. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: Liam Girdwood <[email protected]>
Move the qemu_xtensa mailbox header, which defines its windows and stubs out the software registers, to src/platform. No functional change. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: Liam Girdwood <[email protected]>
Move the mailbox headers of the native_sim (posix) and host library platforms to src/platform, and move the mailbox window definitions out of their memory maps into platform/lib/mailbox_layout.h there. Add the new directories where the host builds, the testbench, the topology parser and the ZTest unit tests add the platform include directories. No functional change. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: Liam Girdwood <[email protected]>
The platform mailbox headers now include what they need, the window layout, so sof/lib/mailbox.h no longer needs the platform memory map. Drop the include, which brought the memory map into every user-space source that uses the mailbox. base_fw.c got HOST_PAGE_SIZE through it on qemu_xtensa, so it includes the memory map. No functional change. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: Liam Girdwood <[email protected]>
The mailbox windows that user-space code uses, the software registers and the host box or the stream window, are mapped into the user-space LL and IPC threads, and sof/lib/mailbox.h no longer includes any kernel-only header. Remove it from the kernel-only headers. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: Liam Girdwood <[email protected]>
Add a README for src/platform, which holds the platform headers that user-space code may include, and point to it from the kernel platform README, which no longer has the mailbox. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: Liam Girdwood <[email protected]>
Seven sources that only used the mailbox no longer include kernel-only headers in any configuration: the copier host and IPC gateway code, the data blob helpers, the host component, the IPC4 module adapter and the volume component. Remove them from the leak baseline. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: Liam Girdwood <[email protected]>
lgirdwood
force-pushed
the
kernel-user/phase4d
branch
from
November 17, 2026 18:56
7109d67 to
dc2a6c9
Compare
lgirdwood
marked this pull request as ready for review
November 17, 2026 19:22
lgirdwood
requested review from
abonislawski,
dbaluta,
iuliana-prodan,
kv2019i,
lbetlej,
lyakh,
mmaka1,
plbossart and
ranj063
as code owners
November 17, 2026 19:22
PR 11476: test resultsRun date: 2026-11-17 19:40 UTC Tested commit: dc2a6c96c4c17fb3a6d86bfab1a97ed67e5559d5 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Phase 4 of #11306 (kernel / user-space partition), fourth part: move the mailbox headers that user-space code uses out of the kernel platform directories into a new
src/platform, and shrink the leak baseline from 29 to 22 sources.Why
User-space code uses the mailbox through
sof/lib/mailbox.h, and that use is intended:user_access_to_mailbox()maps exactly these windows into the user-space LL and IPC threads.But the window addresses come from the platform mailbox headers, which build on the window layout in the platform memory map. They live in
src/kernel/platform/<platform>/include, the include directories that Phase 4 is to make kernel-only. So every user of the mailbox got the platform memory map, and the platform include directories could not become kernel-only.What changes
src/platformdirectory. It holds the platform headers that user-space code may include, with the same layout and include names assrc/kernel/platform, and it is on the include path next to it.platform/lib/mailbox_layout.hinsrc/platform. The memory map includes it.HP_SRAM_BASEon TGL andSDRAM1_BASEon i.MX.src/platformas they are:platform/lib/mailbox.h, and the shared Intelace/lib/mailbox.handcavs/lib/mailbox.h. They include the layout instead of the memory map.sof/lib/mailbox.hno longer includes the memory map, and the checker no longer treats it as kernel-only.This covers Intel (TGL, MTL, LNL, PTL/WCL, NVL), i.MX (imx8, imx8x, imx8m, imx8m_cm7, imx8ulp, imx93, imx95), qemu_xtensa, native_sim (posix) and the host library. The AMD and MediaTek mailbox headers stay in
src/kernel/platformfor now: these platforms do not build on main and are waiting for the native drivers in Phase 0.In the CI configurations, the platform memory map now only reaches 4 user-space sources (16 before), and seven sources that only used the mailbox leave the baseline.
Patches
zephyr: add the platform'ssrc/platformdirectory to the include path. It is added even if it does not exist yet, so that existing build directories pick it up when it appears, without running CMake again.platform: intel: ace: moveace/lib/mailbox.hand the MTL, LNL, PTL/WCL and NVL mailbox headers, and split their window layouts out of the memory maps.platform: intel: cavs: the same forcavs/lib/mailbox.hand TGL.platform: imx: the same for the i.MX platforms. imx8m_cm7, imx93 and imx95 define their windows in the mailbox header, so these only move.src/platform/imx8gets the imx8 code owner.platform: qemu_xtensa: move the mailbox header.platform: posix, library: the same for native_sim and the host library. The new directories are added where the host builds, the testbench, the topology parser and the ZTest unit tests add the platform include directories.lib: mailbox: drop the memory map fromsof/lib/mailbox.h.base_fw.cusedHOST_PAGE_SIZEthrough it on qemu_xtensa and now includes the memory map.scripts: kernel_user_partition: allowsof/lib/mailbox.h.src/platform; the kernel platform README no longer lists the mailbox.The window layout headers are moved code: each one has its platform's block from the memory map, unchanged.
What is left
The 22 remaining sources use kernel APIs:
rtos/timer.h(11 sources).irq_local_disable()/irq_local_enable()(7 sources).perf_cnt.h,agent.h,cpu-clk-manager.h,watchdog.handpm_runtime.h.The mailbox is the first content of
src/platform. Making thesrc/kernel/platforminclude directories kernel-only also needs the rest of what user-space code takes from them to move, or be replaced.Functional change
None.
Testing
--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. Across all of them, exactly the 22 baseline sources leak.CONFIG_SOF_USERSPACE_PROXY=n;os_linux_overlay.conf;llext_relocatable.conf;app/debug_stream_overlay.conf, and PTL with that overlay and user-space LL.SYS_INIT()order), and the per-function disassembly. No object changes at any commit. In the images, only two functions differ:sof_init()on imx8m_cm7, imx93 and imx95, which embeds the git hash, and, in thelib: mailboxcommit, one assertion line number in qemu_xtensa'shost_common_update(), which has assertions enabled. Dropping the include line moves theassert()insof/lib/mailbox.hup by one.All of the above was run on 4681049 (current main).
Changes since the last push
scheduler_dp_kick()) and cmocka-to-ZTest changes, and the include check still passes with the same baseline.test/ztest/unit/audio/selector) also gets thesrc/platform/posix/includedirectory.🤖 Generated with Claude Code