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 <mprivozn@redhat.com>
---
 qemu-options.hx | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/qemu-options.hx b/qemu-options.hx
index b1a399079a..3fe9e6d6a0 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -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,
-- 
2.26.2

Michal Privoznik <mprivozn@redhat.com> writes:

> 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 <mprivozn@redhat.com>
> ---
>  qemu-options.hx | 3 +++
>  1 file changed, 3 insertions(+)
>
> diff --git a/qemu-options.hx b/qemu-options.hx
> index b1a399079a..3fe9e6d6a0 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -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.

On 6/15/20 10:02 AM, Markus Armbruster wrote:
> Michal Privoznik <mprivozn@redhat.com> writes:
> 
>> 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 <mprivozn@redhat.com>
>> ---
>>   qemu-options.hx | 3 +++
>>   1 file changed, 3 insertions(+)
>>
>> diff --git a/qemu-options.hx b/qemu-options.hx
>> index b1a399079a..3fe9e6d6a0 100644
>> --- a/qemu-options.hx
>> +++ b/qemu-options.hx
>> @@ -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?
> 

We error out.

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

> 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

Michal Privoznik <mprivozn@redhat.com> writes:

> On 6/15/20 10:02 AM, Markus Armbruster wrote:
>> Michal Privoznik <mprivozn@redhat.com> writes:
>>
>>> 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 <mprivozn@redhat.com>
>>> ---
>>>   qemu-options.hx | 3 +++
>>>   1 file changed, 3 insertions(+)
>>>
>>> diff --git a/qemu-options.hx b/qemu-options.hx
>>> index b1a399079a..3fe9e6d6a0 100644
>>> --- a/qemu-options.hx
>>> +++ b/qemu-options.hx
>>> @@ -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?
>>
>
> We error out.
>
> https://lists.nongnu.org/archive/html/qemu-devel/2020-05/msg08409.html

Good.

>> 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.

On Wed, 10 Jun 2020 15:17:35 +0200
Michal Privoznik <mprivozn@redhat.com> 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 <mprivozn@redhat.com>

Reviewed-by: Igor Mammedov <imammedo@redhat.com>

> ---
>  qemu-options.hx | 3 +++
>  1 file changed, 3 insertions(+)
> 
> diff --git a/qemu-options.hx b/qemu-options.hx
> index b1a399079a..3fe9e6d6a0 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -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,