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

[PATCH] 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 section explaining:
  - memory.limit_in_bytes must be set before memsw.limit_in_bytes
  - memory.limit_in_bytes <= memsw.limit_in_bytes must always hold
  - Violations result in -EINVAL

Signed-off-by: Shaojie Sun <sunshaojie@kylinos.cn>
---
 Documentation/admin-guide/cgroup-v1/memory.rst | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/Documentation/admin-guide/cgroup-v1/memory.rst b/Documentation/admin-guide/cgroup-v1/memory.rst
index 7db63c002922..92e74ec28822 100644
--- a/Documentation/admin-guide/cgroup-v1/memory.rst
+++ b/Documentation/admin-guide/cgroup-v1/memory.rst
@@ -262,6 +262,15 @@ 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, it must be at least the memory
+   limit.  Therefore, ``memory.limit_in_bytes`` must be set before
+   ``memory.memsw.limit_in_bytes``, and the relation
+   ``memory.limit_in_bytes <= memory.memsw.limit_in_bytes`` must always hold.
+ - If ``memory.memsw.limit_in_bytes`` is set without a properly configured
+   ``memory.limit_in_bytes``, or if the above relation is violated, the write
+   will fail with ``-EINVAL``.
+
 2.4.1 why 'memory+swap' rather than swap
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- 
2.25.1

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

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

[Michal Koutný]

[-- Attachment #1: Type: text/plain, Size: 409 bytes --]

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 265 bytes --]