[PATCH v2] Docs/admin-guide/cgroup-v1/memory: document memsw limit constraints

[Shaojie Sun]

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@xxxxxxxxxx>
---
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