A pair of HMAT docs fixes
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
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
@@ -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
PATCH v2 2/2 qemu-options.hx: Document hmat-lb and hmat-cache order
In reply to Michal PrivoznikTo 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
@@ -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
Re: [PATCH v2 1/2] qemu-options.hx: Mark all hmat-cache attributes required
In reply to Michal PrivoznikCc: 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-cachesays 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
Signed-off-by Michal Privoznik <[email protected]>--- qemu-options.hx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)qemu-options.hx +1
-1@@ -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:
Re: [PATCH v2 2/2] qemu-options.hx: Document hmat-lb and hmat-cache order
In reply to Michal PrivoznikQuoted 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.
Signed-off-by Michal Privoznik <[email protected]>--- qemu-options.hx | 3 +++ 1 file changed, 3 insertions(+)qemu-options.hx +0
-0
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.
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.
Signed-off-by Michal Privoznik <[email protected]>--- qemu-options.hx | 3 +++ 1 file changed, 3 insertions(+)qemu-options.hx +0
-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.
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
Re: [PATCH v2 1/2] qemu-options.hx: Mark all hmat-cache attributes required
In reply to Markus ArmbrusterQuoted 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-cachesays 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
Signed-off-by Michal Privoznik <[email protected]>--- qemu-options.hx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
Quoted 3 lines
Assuming non-optional is what we want:
Reviewed-by Markus Armbruster <[email protected]>
Indeed, it is:
https://lists.nongnu.org/archive/html/qemu-devel/2020-05/msg08411.html
Thanks,
Michal
Re: [PATCH v2 1/2] qemu-options.hx: Mark all hmat-cache attributes required
In reply to Michal PrivoznikQuoted 10 lines · On Wed, 10 Jun 2020 15:17:34 +0200 Michal Privoznik <[email protected]> wrote:
The documentation to
-numa hmat-cachesays 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.
Signed-off-by Michal Privoznik <[email protected]>
Quoted 26 lines
--- qemu-options.hx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)qemu-options.hx +2
-2@@ -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.
Re: [PATCH v2 2/2] qemu-options.hx: Document hmat-lb and hmat-cache order
In reply to Michal PrivoznikQuoted 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.
Signed-off-by Michal Privoznik <[email protected]>
Quoted 18 lines
--- qemu-options.hx | 3 +++ 1 file changed, 3 insertions(+)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,
Re: [PATCH v2 2/2] qemu-options.hx: Document hmat-lb and hmat-cache order
In reply to Michal PrivoznikQuoted 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.
Signed-off-by Michal Privoznik <[email protected]>--- qemu-options.hx | 3 +++ 1 file changed, 3 insertions(+)Quoted 17 lines
Quoted 9 lines
qemu-options.hx +0
-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``\ '
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.