Skip to contentSkip to conversation

test/common: document magic number CXL_TEST_QOS_CLASS=42

PATCH In review [email protected] 3 participants 5 messages Aug 22, 2025 – Aug 25, 2025 libnvdimm: non-volatile memory device

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 test/common: document magic number CXL_TEST_QOS_CLASS=42

From: Marc Herbert <[email protected]>

This magic number must match kernel code. Make that corresponding kernel code much less time-consuming to find.

Additionally, that same one-line reference indirectly documents the minimum kernel version required by the test(s) using this value (only cxl-qos-class.sh at this time)

---
 test/common | 1 +
 1 file changed, 1 insertion(+)
test/common +1 -0
index 2d076402ef7c..1ab62be6994f 100644
@@ -155,4 +155,5 @@ check_dmesg()
 }
 
 # CXL COMMON
+# Test constant defined in kernel commit v6.8-rc2-9-g117132edc690
 CXL_TEST_QOS_CLASS=42
Signature · 1 line
2.50.1
maintainer Reviewed-by on v1 1/1
#1 lore raw
Quoted 10 lines · On 8/21/25 7:55 PM, [email protected] wrote:

From: Marc Herbert <[email protected]>

This magic number must match kernel code. Make that corresponding kernel code much less time-consuming to find.

Additionally, that same one-line reference indirectly documents the minimum kernel version required by the test(s) using this value (only cxl-qos-class.sh at this time)

Quoted 14 lines
---
 test/common | 1 +
 1 file changed, 1 insertion(+)
test/common +1 -0
index 2d076402ef7c..1ab62be6994f 100644
@@ -155,4 +155,5 @@ check_dmesg()
 }
 
 # CXL COMMON
+# Test constant defined in kernel commit v6.8-rc2-9-g117132edc690
 CXL_TEST_QOS_CLASS=42
maintainer
#2 lore raw
In reply to [email protected]
Quoted 4 lines · On Fri, Aug 22, 2025 at 02:55:34AM +0000, [email protected] wrote:

From: Marc Herbert <[email protected]>

This magic number must match kernel code. Make that corresponding kernel code much less time-consuming to find.

The 'must match' is the important part. Include that in the comment. Why expect the user to parse a git describe string and go fishing. Just tell them it is defined in the cxl-test module.

See below...

Quoted 15 lines

Additionally, that same one-line reference indirectly documents the minimum kernel version required by the test(s) using this value (only cxl-qos-class.sh at this time)

---
 test/common | 1 +
 1 file changed, 1 insertion(+)
test/common +0 -0
index 2d076402ef7c..1ab62be6994f 100644

test/common check_dmesg() · line 158

Quoted 4 lines
test/common +1 -0
@@ -155,4 +155,5 @@ check_dmesg()
 }
 
 # CXL COMMON
+# Test constant defined in kernel commit v6.8-rc2-9-g117132edc690

# Must match the FAKE_QTG_ID defined in the cxl-test module

Quoted 4 lines
test/common +0 -0
 CXL_TEST_QOS_CLASS=42
Signature · 1 line
2.50.1
#3 lore raw
Quoted 7 lines · Alison Schofield
Quoted 4 lines · On Fri, Aug 22, 2025 at 02:55:34AM +0000, [email protected] wrote:

From: Marc Herbert <[email protected]>

This magic number must match kernel code. Make that corresponding kernel code much less time-consuming to find.

The 'must match' is the important part. Include that in the comment.

Good point, will do!

Quoted 3 lines

Why expect the user to parse a git describe string and go fishing. Just tell them it is defined in the cxl-test module.

git knows how to parse back the git describe string; readers don't need to parse anything. As explained in the commit message, it's convenient because it holds in a single string both the immutable commit ID _and_ an indication of the minimum kernel version required.

Why tell users to "go fishing" for the cxl-test module when they can find the location directly with a single git command. This is real: I actually wasted a fair amount of time searching for that constant in drivers/cxl/ because I assumed the cxl-test driver was there. This comment is not meant for experts; if they needed it then it would not have been missing for so long.

Last but not least, code and files move around and get renamed. This commit will never change, so it provides an immutable starting point in case things change.

I'll add both, it should still fit on one line.

maintainer
#4 lore raw
Quoted 29 lines · Marc Herbert
Quoted 7 lines · Alison Schofield
Quoted 4 lines · On Fri, Aug 22, 2025 at 02:55:34AM +0000, [email protected] wrote:

From: Marc Herbert <[email protected]>

This magic number must match kernel code. Make that corresponding kernel code much less time-consuming to find.

The 'must match' is the important part. Include that in the comment.

Good point, will do!

Quoted 3 lines

Why expect the user to parse a git describe string and go fishing. Just tell them it is defined in the cxl-test module.

git knows how to parse back the git describe string; readers don't need to parse anything. As explained in the commit message, it's convenient because it holds in a single string both the immutable commit ID _and_ an indication of the minimum kernel version required.

Why tell users to "go fishing" for the cxl-test module when they can find the location directly with a single git command. This is real: I actually wasted a fair amount of time searching for that constant in drivers/cxl/ because I assumed the cxl-test driver was there. This comment is not meant for experts; if they needed it then it would not have been missing for so long.

Quoted 5 lines

Last but not least, code and files move around and get renamed. This commit will never change, so it provides an immutable starting point in case things change.

I'll add both, it should still fit on one line.

Marc,

I didn't infer the pain you go on to describe here in the original commit message. I read this as a trivial patch, and even questioned (but didn't comment) usage of 'magic number' language on value that had a define.

ICYMI
"Describe your problem. Whether your patch is a one-line bug fix or 5000 lines of a new feature, there must be an underlying problem that motivated you to do this work. Convince the reviewer that there is a problem worth fixing and that it makes sense for them to read past the first paragraph."

That's from
https://www.kernel.org/doc/html/latest/process/submitting-patches.html
and ndctl/Contributing.md notes that ndctl follows those guidelines.

There's a lot more guidance at that link, but following the basic 1-2-3, emphasis on #2 for this patch, will help me review without missing the point:

1- State current situation
2- State why #1 is lacking, painful, broken, needs enhancing, etc. 3- State how this patch addresses #2.

Perhaps:
[ndctl PATCH] test/common: document the CXL_TEST_QOS_CLASS kernel dependency

1-
The CXL_TEST_QOS_CLASS define lacks documentation about its kernel counterpart, making it difficult to locate the corresponding kernel code when debugging or verifying compatibility.

2-
When tests depend on kernel-specific constants, like this one does, the lack of clear documentation leads to tedious manual searching.

3-
Add a comment that identifies...

May also be worth mentioning that this issue is arising during the testing of kernels with backported features where test failures may be due to missing kernel support rather than actual bugs. If that is indeed what is happening and is part of the pain.

I'll watch for v2.

--Alison