The kernel enforces the invariant that memory.max <= memsw.max, and
returns -EINVAL when writing an invalid memsw.limit_in_bytes without
first configuring memory.limit_in_bytes.  However, this constraint
is not documented anywhere, leaving users to discover it only through
-EINVAL errors.

Add a note explaining:
  - memory.limit_in_bytes must be configured with a smaller value
    before setting memory.memsw.limit_in_bytes, otherwise -EINVAL
    is returned.
  - The kernel enforces memory.limit_in_bytes <=
    memory.memsw.limit_in_bytes on every write.  When adjusting both
    limits together, set memsw first when increasing and memory
    first when decreasing.

Signed-off-by: Shaojie Sun <sunshaojie@kylinos.cn>
---
v1 -> v2:
  - Correct the ordering guidance: set memsw first when increasing
    limits, set memory first when decreasing limits (spotted by
    Sashiko AI review).
  - Use the ``.. note::`` RST directive instead of plain "Note:".
---

 Documentation/admin-guide/cgroup-v1/memory.rst | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/Documentation/admin-guide/cgroup-v1/memory.rst b/Documentation/admin-guide/cgroup-v1/memory.rst
index 7db63c002922..c52269693fb0 100644
--- a/Documentation/admin-guide/cgroup-v1/memory.rst
+++ b/Documentation/admin-guide/cgroup-v1/memory.rst
@@ -262,6 +262,17 @@ In this case, setting memsw.limit_in_bytes=3G will prevent bad use of swap.
 By using the memsw limit, you can avoid system OOM which can be caused by swap
 shortage.
 
+.. note::
+   - Since memsw is the sum of memory and swap, the kernel enforces the
+     invariant ``memory.limit_in_bytes <= memory.memsw.limit_in_bytes`` on
+     every write, so ``memory.limit_in_bytes`` must be configured with a
+     smaller value before setting ``memory.memsw.limit_in_bytes``.
+     Violating this relation will result in ``-EINVAL``.
+   - When adjusting both limits together, the order matters:
+        - To increase limits, set ``memory.memsw.limit_in_bytes`` first.
+        - To decrease limits, set ``memory.limit_in_bytes`` first.
+     This ensures the intermediate state does not violate the invariant.
+
 2.4.1 why 'memory+swap' rather than swap
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- 
2.25.1

Hello.

On Fri, Jul 24, 2026 at 06:21:48PM +0800, Shaojie Sun <sunshaojie@kylinos.cn> wrote:
>  Documentation/admin-guide/cgroup-v1/memory.rst | 11 +++++++++++
>  1 file changed, 11 insertions(+)

The file has an obsolescence warning at the top (and the number of v1
users is expected to drop in favor of v2).
I don't think it worth the effort upkeeping this one (with such pure-doc
patches).

Thanks,
Michal