Skip to content

kernel/user partition, Phase 4 part 4: move the mailbox headers to src/platform - #11476

Merged
lgirdwood merged 10 commits into
thesofproject:mainfrom
lgirdwood:kernel-user/phase4d
Nov 17, 2026
Merged

lgirdwood merged 10 commits into
thesofproject:mainfrom
lgirdwood:kernel-user/phase4d

Conversation

@lgirdwood

@lgirdwood lgirdwood commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

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:

  • IPC handlers: the user-space handlers read the request payload from the host box.
  • Status registers: the copier, volume and IPC4 DAI code write status to the software registers.
  • IPC3 position updates: the host and xrun code write stream positions to the stream window.

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

  • New src/platform directory. It holds the platform headers that user-space code may include, with the same layout and include names as src/kernel/platform, and it is on the include path next to it.
  • Window layout: for each platform, the layout of the host memory windows moves out of the memory map into a new platform/lib/mailbox_layout.h in src/platform. The memory map includes it.
    • The layout keeps the base address it builds on: the devicetree window bases on ACE, HP_SRAM_BASE on TGL and SDRAM1_BASE on i.MX.
  • Mailbox headers move to src/platform as they are: platform/lib/mailbox.h, and the shared Intel ace/lib/mailbox.h and cavs/lib/mailbox.h. They include the layout instead of the memory map.
  • sof/lib/mailbox.h no 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/platform for 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

  1. zephyr: add the platform's src/platform directory 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.
  2. platform: intel: ace: move ace/lib/mailbox.h and the MTL, LNL, PTL/WCL and NVL mailbox headers, and split their window layouts out of the memory maps.
  3. platform: intel: cavs: the same for cavs/lib/mailbox.h and TGL.
  4. 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/imx8 gets the imx8 code owner.
  5. platform: qemu_xtensa: move the mailbox header.
  6. 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.
  7. lib: mailbox: drop the memory map from sof/lib/mailbox.h. base_fw.c used HOST_PAGE_SIZE through it on qemu_xtensa and now includes the memory map.
  8. scripts: kernel_user_partition: allow sof/lib/mailbox.h.
  9. Docs: a README for src/platform; the kernel platform README no longer lists the mailbox.
  10. Baseline: remove the seven sources that are now clean: the copier host and IPC gateway code, the data blob helpers, the host component, the IPC4 module adapter and the volume component.

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:

  • Timestamps: the platform timestamp functions and the cycle counter from rtos/timer.h (11 sources).
  • IRQ locking: irq_local_disable()/irq_local_enable() (7 sources).
  • IADK: the user-space helper partitions in the IADK sources.
  • Single uses: the memory map in the notifier and the DRAM tester, and single uses of perf_cnt.h, agent.h, cpu-clk-manager.h, watchdog.h and pm_runtime.h.

The mailbox is the first content of src/platform. Making the src/kernel/platform include directories kernel-only also needs the rest of what user-space code takes from them to move, or be replaced.

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. Across all of them, exactly the 22 baseline sources leak.
  • 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.
    • Comparisons: objects, LLEXT modules and firmware images (sections, symbols, 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 the lib: mailbox commit, one assertion line number in qemu_xtensa's host_common_update(), which has assertions enabled. Dropping the include line moves the assert() in sof/lib/mailbox.h up by one.
    • 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 (19 of 19 configurations, including the new selector test).
    • 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.

All of the above was run on 4681049 (current main).

Changes since the last push

🤖 Generated with Claude Code

@kv2019i

kv2019i commented Nov 17, 2026

Copy link
Copy Markdown
Collaborator

@lgirdwood part 3 merged, ready for this one

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟢 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

lrgirdwo and others added 10 commits November 17, 2026 16:51
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]>
@intel-sofci

Copy link
Copy Markdown

PR 11476: test results

Run date: 2026-11-17 19:40 UTC

Tested commit: dc2a6c96c4c17fb3a6d86bfab1a97ed67e5559d5

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

@lgirdwood
lgirdwood merged commit 72e797d into thesofproject:main Nov 17, 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.

5 participants