Re: [RFC PATCH v2 24/25] Documentation: Add PISA architecture documentation

[sashiko-bot@kernel.org]

Thank you for your contribution! Sashiko AI review found 2 potential
issues to consider:
- [Low] docs: incomplete pisa.* boot parameter docs and wrong scrub_max
  unit
- [Low] docs: pisa.rst omits block I/O, page-cache folio, and user_pa
  support
--

commit cadce0626ec3fdede5eca92aaf3542cae769fd37
Author: Luigi Rizzo <lrizzo@google.com>

Documentation: Add PISA architecture documentation

This commit adds architecture and runtime control documentation for the
Pre-mapped IOVA Superpage Allocator (PISA) in
Documentation/core-api/pisa.rst and lists the pisa.* kernel parameters in
Documentation/admin-guide/kernel-parameters.txt.

> diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
> index 0b3c140babd94..cb978469a7df3 100644
> --- a/Documentation/admin-guide/kernel-parameters.txt
> +++ b/Documentation/admin-guide/kernel-parameters.txt
> @@ -5345,6 +5345,12 @@ Kernel parameters
>  	pirq=		[SMP,APIC] Manual mp-table setup
>  			See Documentation/arch/x86/i386/IO-APIC.rst.
>  
> +	pisa.*=		[IOMMU] Pre-mapped IOVA Superpage Allocator (PISA)
> +			tuning parameters (max_bits, max_pages, slots, max_idle,
> +			idle_ms, reservoir_max, scrub_max, compact, wasted_pct,
> +			old_ms, pcp_batch, user_max_4K_pages, scrub_migrate).
> +			See Documentation/core-api/pisa.rst.

[Severity: Low]
Should this entry also include the pisa.decrypt boot parameter defined in
drivers/iommu/pisa-alloc.c, and use [ARM64,X86-64] instead of [IOMMU] (which
is not defined in the restriction tag list in kernel-parameters.txt)?

In addition, this entry defers to Documentation/core-api/pisa.rst, which
does not describe decrypt, max_idle, idle_ms, compact, wasted_pct, old_ms,
pcp_batch, or scrub_migrate, and describes scrub_max as counting idle 2MB
PISA pages even though pisa_scrub_alloc() accounts the budget in 4KB base
pages ((unsigned long)used << order) and scrubs dirty blocks from
partial_dirty and partial pages before idle pages.

> diff --git a/Documentation/core-api/pisa.rst b/Documentation/core-api/pisa.rst
> new file mode 100644
> index 0000000000000..6ed4bd9951f8a
> --- /dev/null
> +++ b/Documentation/core-api/pisa.rst

[ ... ]

> +  - ``/sys/devices/*/*/pisa_{coherent,rx_bufs,tx_bufs,tx_skb_heads}``
> +    per-device entries that control whether a device uses PISA for coherent
> +    allocations, RX buffers, TX socket page fragments, and small TX skb heads

[ ... ]

> +- **User pages for MSG_ZEROCOPY** (``drivers/iommu/pisa-user.c``):
> +
> +  - ``madvise(MADV_PISA)`` migrates the present private anonymous pages
> +    of a range into blocks of per-node ``DMA_TO_DEVICE`` allocators, so that
> +    zerocopy sends from them use the PISA window instead of per-send IOMMU
> +    mappings or hypervisor pinning. ``MADV_NOPISA`` migrates them back to
> +    ordinary pages. Both are allowed through ``process_madvise()``.
> +    Freeing the pages (``munmap()``, ``MADV_DONTNEED``, exit, reclaim)
> +    returns the blocks to their allocators.
> +  - ``/sys/module/pisa/parameters/user_max_4K_pages``: Soft cap on user
> +    pages held in PISA blocks, in 4 KB pages (``max_pages`` counts PISA
> +    pages). When non-zero, eligible pages are also migrated on
> +    ``MSG_ZEROCOPY`` sends (best effort, non-blocking, skipping pages still
> +    referenced by in-flight skbs); 0 (default) disables both.

[Severity: Low]
Should these sections also document how pisa_rx_bufs, pisa_tx_bufs, and
user_max_4K_pages apply to block I/O and page-cache folios?

In drivers/iommu/pisa-user.c, user_pa[] maintains per-node allocators for
DMA_BIDIRECTIONAL, DMA_TO_DEVICE, and DMA_FROM_DEVICE.  When
user_max_4K_pages is non-zero and pisa_rx_bufs or pisa_tx_bufs is enabled on
a block device or its parents, PISA also migrates pinned order-0 user pages
for O_DIRECT bios in bio_iov_iter_get_pages(), allocates or migrates order-0
page-cache folios in __filemap_get_folio_mpol(), ractl_alloc_folio(), and
writeback_get_folio(), and skips blk-mq IOVA allocation for PISA pages in
dma_iova_try_alloc().

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20261109182533.3594984-1-lrizzo@google.com?part=24