diff --git a/Documentation/index.rst b/Documentation/index.rst index d58f488d90693bc09c145bbb76b0c9b612055056..1f1d464c397c82abc6c3bab8b309e39a08d3d0a8 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -90,6 +90,7 @@ TKernel documentation tkernel/tkernel tkernel/irq-latency tkernel/cgroup-v2-mbuf + tkernel/emm Firmware-related documentation ============================== diff --git a/Documentation/tkernel/emm.rst b/Documentation/tkernel/emm.rst new file mode 100644 index 0000000000000000000000000000000000000000..867b65d63b9bd94499b5efb0c61b0e16510d49f9 --- /dev/null +++ b/Documentation/tkernel/emm.rst @@ -0,0 +1,87 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +========================================== +Enhanced Memory Management (EMM) +========================================== + +Overview +======== + +EMM (``CONFIG_ENHANCED_MM``) is a collection of memory-management +enhancements for memory cgroups maintained in the TKernel source tree. +It builds on ``CONFIG_MEMCG`` and provides in-kernel APIs, extended +cgroup interfaces, and additional per-cgroup data structures used by +the RUE resource-isolation stack. The individual features are enabled +through their own Kconfig options and are described below. + +The EMM kernel-side code lives in ``kernel/tkernel/emm/`` (built when +``CONFIG_EMM_RECLAIM`` is set) and in various ``mm/`` files guarded by +the ``CONFIG_EMM_*`` options. + +Features +======== + +Force swappiness (``CONFIG_EMM_FORCE_SWAPPINESS``) +--------------------------------------------------- + +By default kswapd reclaims anonymous pages for the root cgroup even +when ``vm.swappiness`` is 0, in order to avoid a system-wide OOM. +This option disables that fallback so anon pages of the root cgroup +are never reclaimed when swappiness is 0. + +Ramdisk swap tuning (``CONFIG_EMM_RAMDISK_SWAP``) +------------------------------------------------- + +Enables a set of tunings for ramdisk-backed swap devices so that swap +works better with a memcg-bounded ramdisk. + +Workingset tracking (``CONFIG_EMM_WORKINGSET_TRACKING``) +-------------------------------------------------------- + +Evaluates per-cgroup memory eviction status. Because active +shrinkers reduce the in-memory LRU size and change the workingset +size, estimating a "raw workingset" helps analyse and improve memory +usage. + +Enhanced memcg support (``CONFIG_EMM_MEMCG``) +--------------------------------------------- + +Adds extended memory-management interfaces for memory cgroups, such as +the per-cgroup asynchronous reclaim knobs ``memory.async_ratio``, +``memory.async_high``, ``memory.async_low`` and +``memory.async_distance_factor``. Asynchronous reclaim is gated by +``vm.memcg_async`` (see the TKernel feature guide) and requires the +RUE module to be installed. + +Enhanced reclaim (``CONFIG_EMM_RECLAIM``) +----------------------------------------- + +Adds the enhanced reclaim path used by the above interfaces and pulls +in the EMM module tree under ``kernel/tkernel/emm/``. + +Enhanced ZRAM (``CONFIG_EMM_ZRAM_CONF``) +---------------------------------------- + +A placeholder option that selects the compression backends +(CRYPTO_LZO, CRYPTO_ZSTD, CRYPTO_LZ4, CRYPTO_LZ4HC), ``ZSMALLOC`` and +``MEMCG_ZRAM`` required by the enhanced ZRAM build maintained under +``kernel/tkernel/emm/driver/block/zram/``. + +Batched TLB flush for dirty pages (``CONFIG_EMM_BATCH_DIRTY_TLB_FLUSH``) +------------------------------------------------------------------------- + +The kernel flushes dirty pages one by one on pageout, which can cause +heavy IPI cost on large machines. This option batches the TLB +flushes; it is controlled at runtime through +``vm.batch_dirty_tlb_flush`` and is experimental. + +Module build +============ + +The ``kernel/tkernel/emm/`` tree builds three loadable modules +(``emm_extentions``, ``emm_coreutils`` and ``emm_zram``) with:: + + make M=kernel/tkernel/emm modules + +The same tree is built into the kernel build when +``CONFIG_EMM_RECLAIM`` is enabled.