Skip to content

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

Draft
lgirdwood wants to merge 15 commits into
thesofproject:mainfrom
lgirdwood:kernel-user/phase4d
Draft

lgirdwood wants to merge 15 commits into
thesofproject:mainfrom
lgirdwood:kernel-user/phase4d

Conversation

@lgirdwood

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.

Based on #11470. Only the last ten commits are new.

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 kernel/user partition, Phase 4 part 3: untangle the DMA, timer and LL domain headers #11470:
    • 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 (18 of 18 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.

All of the above was run on #11470, on 607d0a9 (current main).

🤖 Generated with Claude Code

lrgirdwo and others added 15 commits November 16, 2026 20:04
sof/lib/dma.h uses neither the register access helpers of
sof/lib/io.h nor the platform memory map, but it brings both into the
user-space host, DAI, copier, chain DMA, ASRC and pipeline sources
that use the DMA API. Drop the includes.

Three kernel sources got them through this header, so they include
what they use: zephyr/wrapper.c the register helpers and the memory
map, which it included as platform/lib/memory.h instead of through
sof/lib/memory.h, zephyr/lib/cpu.c and ipc3/host-page-table.c the
memory map. So does dma-legacy.h, which sof/lib/dma.h includes for the
builds without the Zephyr native drivers: it uses the register
helpers.

No functional change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
rtos/timer.h uses nothing from sof/platform.h, which brings the
platform definitions and clock headers into every user-space source
that reads the cycle counter or the stream timestamps. Drop the
include.

base_fw_intel.c, zephyr/lib/alloc.c and zephyr/lib/cpu.c used
HOST_PAGE_SIZE and platform_boot_complete() through this header, so
they include sof/platform.h.

dai-zephyr.c got the memory map through this header too, and it uses
local_to_host() from it. It defines local_to_host() as a no-op if the
platform doesn't, so without the include the code still built but lost
the imx8ulp address translation. Include sof/lib/memory.h there.

No functional change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
domain_init() only uses clock_ms_to_ticks() from rtos/clk.h in the
builds without Zephyr. The Zephyr builds compute the ticks with
k_ms_to_cyc_ceil64(), but still include the clock header, and with it
the platform clock headers, into the user-space scheduler and IPC
sources. Only include it when not building for Zephyr.

The native_sim platform code used the clock definitions through this
header, so it includes rtos/clk.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 sof_dma_*() system calls in sof/lib/sof_dma.h take Zephyr's
struct dma_config and struct dma_status, and their callers use the
Zephyr DMA constants, so user-space code needs zephyr/drivers/dma.h.
The header has no system calls itself, and Zephyr's own header cannot
be split.

Remove it from the kernel-only headers, with a note that user-space
code must not call its dma_*() driver functions directly, which the
include check cannot catch. None does today: the user-space DMA code
only uses the sof_dma_*() calls.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Ten sources no longer include kernel-only headers in any
configuration: the ASRC, chain DMA, copier DAI and gain, UAOL, DMA and
DAI library sources, the user-space IPC code and the DP scheduler
thread and application code. Remove them from the leak baseline.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
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 <noreply@anthropic.com>
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
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 <noreply@anthropic.com>
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
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 <noreply@anthropic.com>
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
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 <noreply@anthropic.com>
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
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 <noreply@anthropic.com>
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
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 <noreply@anthropic.com>
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
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 <noreply@anthropic.com>
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
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 <noreply@anthropic.com>
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
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 <noreply@anthropic.com>
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
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 <noreply@anthropic.com>
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
@kv2019i

kv2019i commented Nov 17, 2026

Copy link
Copy Markdown
Collaborator

@lgirdwood part 3 merged, ready for this one

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.

3 participants