Skip to contentSkip to conversation

A pair of HMAT docs fixes

PATCH In review Michal Privoznik 3 participants 10 messages Jun 10, 2020 – Jun 22, 2020

lore
Share & tools
lore
#0 lore raw

v2 cover A pair of HMAT docs fixes

Technically, this is a v2 of:

https://lists.nongnu.org/archive/html/qemu-devel/2020-05/msg08316.html

But as it turned out during the review of v1, we don't need to change the code rather than documentation.

Michal Privoznik (2):
qemu-options.hx: Mark all hmat-cache attributes required qemu-options.hx: Document hmat-lb and hmat-cache order

 qemu-options.hx | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)
Signature · 1 line
2.26.2
#1 lore raw

PATCH v2 1/2 qemu-options.hx: Mark all hmat-cache attributes required

The documentation to -numa hmat-cache says that @node-id, @size and @level are the only required attributes. The rest (@associativity, @policy and @line) is optional. Well, not quite
- if I try to start QEMU with only the three required attributes defined the QAPI code is complaining about associativity missing.

According to QAPI all attributes are required. Make the docs reflect that.

---
 qemu-options.hx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
qemu-options.hx +2 -2
index 93bde2bbc8..b1a399079a 100644
@@ -188,7 +188,7 @@ DEF("numa", HAS_ARG, QEMU_OPTION_numa,
     "-numa dist,src=source,dst=destination,val=distance\n"
     "-numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]\n"
     "-numa hmat-lb,initiator=node,target=node,hierarchy=memory|first-level|second-level|third-level,data-type=access-latency|read-latency|write-latency[,latency=lat][,bandwidth=bw]\n"
-    "-numa hmat-cache,node-id=node,size=size,level=level[,associativity=none|direct|complex][,policy=none|write-back|write-through][,line=size]\n",
+    "-numa hmat-cache,node-id=node,size=size,level=level,associativity=none|direct|complex,policy=none|write-back|write-through,line=size\n",
     QEMU_ARCH_ALL)
 SRST
 ``-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=initiator]``
@@ -201,7 +201,7 @@ SRST
   \ 
 ``-numa hmat-lb,initiator=node,target=node,hierarchy=hierarchy,data-type=tpye[,latency=lat][,bandwidth=bw]``
   \ 
-``-numa hmat-cache,node-id=node,size=size,level=level[,associativity=str][,policy=str][,line=size]``
+``-numa hmat-cache,node-id=node,size=size,level=level,associativity=str,policy=str,line=size``
     Define a NUMA node and assign RAM and VCPUs to it. Set the NUMA
     distance from a source node to a destination node. Set the ACPI
     Heterogeneous Memory Attributes for the given nodes.
Signature · 1 line
2.26.2
#5 lore raw

PATCH v2 2/2 qemu-options.hx: Document hmat-lb and hmat-cache order

In reply to Michal Privoznik

To simplify internal implementation the hmat-cache parsing code expects hmat-lb to be already parsed. This means, that hmat-lb arguments must come before hmat-cache. Document this restriction so that management applications can follow it.

---
 qemu-options.hx | 3 +++
 1 file changed, 3 insertions(+)
qemu-options.hx +3 -0
index b1a399079a..3fe9e6d6a0 100644
@@ -319,6 +319,9 @@ SRST
     'none/direct(direct-mapped)/complex(complex cache indexing)'. policy
     is the write policy. line is the cache Line size in bytes.
 
+    Please note, that due to internal implementation, '\ ``hmat-cache``\ '
+    must be configured only after '\ ``hmat-lb``\ ' option.
+
     For example, the following options describe 2 NUMA nodes. Node 0 has
     2 cpus and a ram, node 1 has only a ram. The processors in node 0
     access memory in node 0 with access-latency 5 nanoseconds,
Signature · 1 line
2.26.2
Reviewed-by on v2 1/2
#2 lore raw

Re: [PATCH v2 1/2] qemu-options.hx: Mark all hmat-cache attributes required

In reply to Michal Privoznik

Cc: the people involved in commit c412a48d4d "numa: Extend CLI to provide memory side cache information".

Quoted 5 lines · Michal Privoznik

The documentation to -numa hmat-cache says that @node-id, @size and @level are the only required attributes. The rest (@associativity, @policy and @line) is optional. Well, not quite
- if I try to start QEMU with only the three required attributes defined the QAPI code is complaining about associativity missing.

Only because @associativity visited first.

Quoted 2 lines

According to QAPI all attributes are required. Make the docs reflect that.

Correct.

Quoted 19 lines
---
 qemu-options.hx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
qemu-options.hx +1 -1
index 93bde2bbc8..b1a399079a 100644
@@ -188,7 +188,7 @@ DEF("numa", HAS_ARG, QEMU_OPTION_numa,
     "-numa dist,src=source,dst=destination,val=distance\n"
     "-numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]\n"
     "-numa hmat-lb,initiator=node,target=node,hierarchy=memory|first-level|second-level|third-level,data-type=access-latency|read-latency|write-latency[,latency=lat][,bandwidth=bw]\n"
-    "-numa hmat-cache,node-id=node,size=size,level=level[,associativity=none|direct|complex][,policy=none|write-back|write-through][,line=size]\n",
+    "-numa hmat-cache,node-id=node,size=size,level=level,associativity=none|direct|complex,policy=none|write-back|write-through,line=size\n",
     QEMU_ARCH_ALL)
 SRST
 ``-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=initiator]``

qemu-options.hx SRST · line 207

Quoted 8 lines
qemu-options.hx +1 -1
@@ -201,7 +201,7 @@ SRST
   \ 
 ``-numa hmat-lb,initiator=node,target=node,hierarchy=hierarchy,data-type=tpye[,latency=lat][,bandwidth=bw]``
   \ 
-``-numa hmat-cache,node-id=node,size=size,level=level[,associativity=str][,policy=str][,line=size]``
+``-numa hmat-cache,node-id=node,size=size,level=level,associativity=str,policy=str,line=size``
     Define a NUMA node and assign RAM and VCPUs to it. Set the NUMA
     distance from a source node to a destination node. Set the ACPI
     Heterogeneous Memory Attributes for the given nodes.

Assuming non-optional is what we want:

#6 lore raw

Re: [PATCH v2 2/2] qemu-options.hx: Document hmat-lb and hmat-cache order

In reply to Michal Privoznik
Quoted 15 lines · Michal Privoznik

To simplify internal implementation the hmat-cache parsing code expects hmat-lb to be already parsed. This means, that hmat-lb arguments must come before hmat-cache. Document this restriction so that management applications can follow it.

---
 qemu-options.hx | 3 +++
 1 file changed, 3 insertions(+)
qemu-options.hx +0 -0
index b1a399079a..3fe9e6d6a0 100644

qemu-options.hx SRST · line 327

Quoted 9 lines
qemu-options.hx +3 -0
@@ -319,6 +319,9 @@ SRST
     'none/direct(direct-mapped)/complex(complex cache indexing)'. policy
     is the write policy. line is the cache Line size in bytes.
 
+    Please note, that due to internal implementation, '\ ``hmat-cache``\ '
+    must be configured only after '\ ``hmat-lb``\ ' option.
+
     For example, the following options describe 2 NUMA nodes. Node 0 has
     2 cpus and a ram, node 1 has only a ram. The processors in node 0
     access memory in node 0 with access-latency 5 nanoseconds,

What happens when we do it wrong?

Can we catch doing it wrong somehow? I figure that would be much better than merely documenting it.

#7 lore raw

Re: [PATCH v2 2/2] qemu-options.hx: Document hmat-lb and hmat-cache order

Quoted 20 lines · Markus Armbruster
Quoted 18 lines · Michal Privoznik

To simplify internal implementation the hmat-cache parsing code expects hmat-lb to be already parsed. This means, that hmat-lb arguments must come before hmat-cache. Document this restriction so that management applications can follow it.

---
  qemu-options.hx | 3 +++
  1 file changed, 3 insertions(+)
qemu-options.hx +0 -0
index b1a399079a..3fe9e6d6a0 100644
@@ -319,6 +319,9 @@ SRST
      'none/direct(direct-mapped)/complex(complex cache indexing)'. policy
      is the write policy. line is the cache Line size in bytes.
 
Quoted 9 lines

qemu-options.hx SRST · line 327

Quoted 6 lines
qemu-options.hx +3 -0
+    Please note, that due to internal implementation, '\ ``hmat-cache``\ '
+    must be configured only after '\ ``hmat-lb``\ ' option.
+
      For example, the following options describe 2 NUMA nodes. Node 0 has
      2 cpus and a ram, node 1 has only a ram. The processors in node 0
      access memory in node 0 with access-latency 5 nanoseconds,

What happens when we do it wrong?

We error out.

https://lists.nongnu.org/archive/html/qemu-devel/2020-05/msg08409.html

Quoted 3 lines

Can we catch doing it wrong somehow? I figure that would be much better than merely documenting it.

Sure, but that would require some more code (according to Igor's e-mail and discussion linked from the linked document). And frankly, to libvirt it doesn't matter. For everybody else, let's document it at least and if somebody ever writes the missing piece we can remove the restriction from the docs.

Michal

#3 lore raw

Re: [PATCH v2 1/2] qemu-options.hx: Mark all hmat-cache attributes required

In reply to Markus Armbruster
Quoted 25 lines · Markus Armbruster

Cc: the people involved in commit c412a48d4d "numa: Extend CLI to provide memory side cache information".

Quoted 5 lines · Michal Privoznik

The documentation to -numa hmat-cache says that @node-id, @size and @level are the only required attributes. The rest (@associativity, @policy and @line) is optional. Well, not quite
- if I try to start QEMU with only the three required attributes defined the QAPI code is complaining about associativity missing.

Only because @associativity visited first.

Quoted 2 lines

According to QAPI all attributes are required. Make the docs reflect that.

Correct.

Quoted 5 lines
---
  qemu-options.hx | 4 ++--
  1 file changed, 2 insertions(+), 2 deletions(-)
Quoted 3 lines

Assuming non-optional is what we want:

Indeed, it is:

https://lists.nongnu.org/archive/html/qemu-devel/2020-05/msg08411.html

Thanks,
Michal

Reviewed-by on v2 1/2
#4 lore raw

Re: [PATCH v2 1/2] qemu-options.hx: Mark all hmat-cache attributes required

In reply to Michal Privoznik
Quoted 10 lines · On Wed, 10 Jun 2020 15:17:34 +0200 Michal Privoznik <[email protected]> wrote:

The documentation to -numa hmat-cache says that @node-id, @size and @level are the only required attributes. The rest (@associativity, @policy and @line) is optional. Well, not quite
- if I try to start QEMU with only the three required attributes defined the QAPI code is complaining about associativity missing.

According to QAPI all attributes are required. Make the docs reflect that.

Quoted 26 lines
---
 qemu-options.hx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
qemu-options.hx +2 -2
index 93bde2bbc8..b1a399079a 100644
@@ -188,7 +188,7 @@ DEF("numa", HAS_ARG, QEMU_OPTION_numa,
     "-numa dist,src=source,dst=destination,val=distance\n"
     "-numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]\n"
     "-numa hmat-lb,initiator=node,target=node,hierarchy=memory|first-level|second-level|third-level,data-type=access-latency|read-latency|write-latency[,latency=lat][,bandwidth=bw]\n"
-    "-numa hmat-cache,node-id=node,size=size,level=level[,associativity=none|direct|complex][,policy=none|write-back|write-through][,line=size]\n",
+    "-numa hmat-cache,node-id=node,size=size,level=level,associativity=none|direct|complex,policy=none|write-back|write-through,line=size\n",
     QEMU_ARCH_ALL)
 SRST
 ``-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=initiator]``
@@ -201,7 +201,7 @@ SRST
   \ 
 ``-numa hmat-lb,initiator=node,target=node,hierarchy=hierarchy,data-type=tpye[,latency=lat][,bandwidth=bw]``
   \ 
-``-numa hmat-cache,node-id=node,size=size,level=level[,associativity=str][,policy=str][,line=size]``
+``-numa hmat-cache,node-id=node,size=size,level=level,associativity=str,policy=str,line=size``
     Define a NUMA node and assign RAM and VCPUs to it. Set the NUMA
     distance from a source node to a destination node. Set the ACPI
     Heterogeneous Memory Attributes for the given nodes.
Reviewed-by on v2 2/2
#9 lore raw

Re: [PATCH v2 2/2] qemu-options.hx: Document hmat-lb and hmat-cache order

In reply to Michal Privoznik
Quoted 6 lines · On Wed, 10 Jun 2020 15:17:35 +0200 Michal Privoznik <[email protected]> wrote:

To simplify internal implementation the hmat-cache parsing code expects hmat-lb to be already parsed. This means, that hmat-lb arguments must come before hmat-cache. Document this restriction so that management applications can follow it.

Quoted 18 lines
---
 qemu-options.hx | 3 +++
 1 file changed, 3 insertions(+)
qemu-options.hx +3 -0
index b1a399079a..3fe9e6d6a0 100644
@@ -319,6 +319,9 @@ SRST
     'none/direct(direct-mapped)/complex(complex cache indexing)'. policy
     is the write policy. line is the cache Line size in bytes.
 
+    Please note, that due to internal implementation, '\ ``hmat-cache``\ '
+    must be configured only after '\ ``hmat-lb``\ ' option.
+
     For example, the following options describe 2 NUMA nodes. Node 0 has
     2 cpus and a ram, node 1 has only a ram. The processors in node 0
     access memory in node 0 with access-latency 5 nanoseconds,
#8 lore raw

Re: [PATCH v2 2/2] qemu-options.hx: Document hmat-lb and hmat-cache order

In reply to Michal Privoznik
Quoted 31 lines · Michal Privoznik
Quoted 12 lines · Markus Armbruster
Quoted 10 lines · Michal Privoznik

To simplify internal implementation the hmat-cache parsing code expects hmat-lb to be already parsed. This means, that hmat-lb arguments must come before hmat-cache. Document this restriction so that management applications can follow it.

---
  qemu-options.hx | 3 +++
  1 file changed, 3 insertions(+)
Quoted 17 lines
Quoted 9 lines
qemu-options.hx +0 -0
index b1a399079a..3fe9e6d6a0 100644
@@ -319,6 +319,9 @@ SRST
      'none/direct(direct-mapped)/complex(complex cache indexing)'. policy
      is the write policy. line is the cache Line size in bytes.
  +    Please note, that due to internal implementation, '\

``hmat-cache``\ '

qemu-options.hx SRST · line 327

Quoted 5 lines
qemu-options.hx +2 -0
+    must be configured only after '\ ``hmat-lb``\ ' option.
+
      For example, the following options describe 2 NUMA nodes. Node 0 has
      2 cpus and a ram, node 1 has only a ram. The processors in node 0
      access memory in node 0 with access-latency 5 nanoseconds,

What happens when we do it wrong?

Quoted 3 lines

We error out.

https://lists.nongnu.org/archive/html/qemu-devel/2020-05/msg08409.html

Good.

Quoted 9 lines
Quoted 3 lines

Can we catch doing it wrong somehow? I figure that would be much better than merely documenting it.

Sure, but that would require some more code (according to Igor's e-mail and discussion linked from the linked document). And frankly, to libvirt it doesn't matter. For everybody else, let's document it at least and if somebody ever writes the missing piece we can remove the restriction from the docs.

Misunderstanding. By "catch doing it wrong", I mean "error out when hmat-cache is configured before hmat-lb". I understand we do that.

Avoiding the restriction entirely would be even better, but the maintainer obviously decided it was not worth the trouble. I gladly defer to the maintainer here.

Given the general undocumentedness of similar restrictions elsewhere, I can't bring myself to care for documenting this one. Up to the maintainer.