[libvirt] [PATCH] docs: formatdomain: Document the CPU feature 'name' attribute
Currently, the CPU feature 'name' XML attribute, as in: [...] <cpu match='exact'> <model fallback='forbid'>IvyBridge</model> <vendor>Intel</vendor> <feature policy='require' name='pcid'/> </cpu> [...] isn't explicitly documented in formatdomain.html. Document it now. Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com> --- docs/formatdomain.html.in | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index d272cc1ba..e717fb3aa 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -1454,6 +1454,23 @@ <span class="since">Since 0.8.5</span> the <code>policy</code> attribute can be omitted and will default to <code>require</code>. + + Individual CPU feature names can be specified as part of the + <code>name</code> attribute. The list of known CPU feature + names (e.g. 'vmx', 'cmt', et cetera) can be found in the same + file as CPU models -- <code>cpu_map.xml</code>. For example, + to explicitly specify the 'pcid' feature with Intel IvyBridge + CPU model: + +<pre> +... +<cpu match='exact'> + <model fallback='forbid'>IvyBridge</model> + <vendor>Intel</vendor> + <feature policy='require' name='pcid'/> +</cpu> +...</pre> + </dd> <dt><code>cache</code></dt> -- 2.13.6
On Fri, Jan 12, 2018 at 08:31:16PM +0100, Kashyap Chamarthy wrote:
Currently, the CPU feature 'name' XML attribute, as in:
[...] <cpu match='exact'> <model fallback='forbid'>IvyBridge</model> <vendor>Intel</vendor> <feature policy='require' name='pcid'/> </cpu> [...]
isn't explicitly documented in formatdomain.html.
Document it now.
Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com> --- docs/formatdomain.html.in | 17 +++++++++++++++++ 1 file changed, 17 insertions(+)
diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index d272cc1ba..e717fb3aa 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -1454,6 +1454,23 @@
<span class="since">Since 0.8.5</span> the <code>policy</code> attribute can be omitted and will default to <code>require</code>. + + Individual CPU feature names can be specified as part of the + <code>name</code> attribute.
Isn't this "should" instead of "can"? Does it make sense to have a 'feature' element without a 'name' attribute?
The list of known CPU feature + names (e.g. 'vmx', 'cmt', et cetera) can be found in the same + file as CPU models -- <code>cpu_map.xml</code>. For example, + to explicitly specify the 'pcid' feature with Intel IvyBridge + CPU model:
Another paragraph above already says "The list of known feature names can be found in the same file as CPU models". If you think the existing paragraph is not enough, I suggest rewriting it so the document won't repeat exactly the same thing.
+ +<pre> +... +<cpu match='exact'> + <model fallback='forbid'>IvyBridge</model> + <vendor>Intel</vendor> + <feature policy='require' name='pcid'/> +</cpu> +...</pre> + </dd>
<dt><code>cache</code></dt> -- 2.13.6
-- Eduardo
On Tue, Jan 16, 2018 at 03:35:20PM -0200, Eduardo Habkost wrote:
On Fri, Jan 12, 2018 at 08:31:16PM +0100, Kashyap Chamarthy wrote:
Currently, the CPU feature 'name' XML attribute, as in:
[...]
--- docs/formatdomain.html.in | 17 +++++++++++++++++ 1 file changed, 17 insertions(+)
diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index d272cc1ba..e717fb3aa 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -1454,6 +1454,23 @@
<span class="since">Since 0.8.5</span> the <code>policy</code> attribute can be omitted and will default to <code>require</code>. + + Individual CPU feature names can be specified as part of the + <code>name</code> attribute.
Isn't this "should" instead of "can"? Does it make sense to have a 'feature' element without a 'name' attribute?
Good catch. Near as I see, it doesn't. So I'll: s/can/should.
The list of known CPU feature + names (e.g. 'vmx', 'cmt', et cetera) can be found in the same + file as CPU models -- <code>cpu_map.xml</code>. For example, + to explicitly specify the 'pcid' feature with Intel IvyBridge + CPU model:
Another paragraph above already says "The list of known feature names can be found in the same file as CPU models". If you think the existing paragraph is not enough, I suggest rewriting it so the document won't repeat exactly the same thing.
True. How about this rewrite: "Once you choose a feature (e.g. 'pcid') from the `cpu_map.xml`, to specify it explicitly with the Intel IvyBridge CPU model [...]" I'll consider whether to also add a note that before specifying extra CPU feature flags, one should check if the named CPU models provided by libvirt already include the said flags. [...] -- /kashyap
On Wed, Jan 17, 2018 at 09:04:26AM +0100, Kashyap Chamarthy wrote:
On Tue, Jan 16, 2018 at 03:35:20PM -0200, Eduardo Habkost wrote:
On Fri, Jan 12, 2018 at 08:31:16PM +0100, Kashyap Chamarthy wrote:
Currently, the CPU feature 'name' XML attribute, as in:
[...]
--- docs/formatdomain.html.in | 17 +++++++++++++++++ 1 file changed, 17 insertions(+)
diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index d272cc1ba..e717fb3aa 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -1454,6 +1454,23 @@
<span class="since">Since 0.8.5</span> the <code>policy</code> attribute can be omitted and will default to <code>require</code>. + + Individual CPU feature names can be specified as part of the + <code>name</code> attribute.
Isn't this "should" instead of "can"? Does it make sense to have a 'feature' element without a 'name' attribute?
Good catch. Near as I see, it doesn't. So I'll: s/can/should.
The list of known CPU feature + names (e.g. 'vmx', 'cmt', et cetera) can be found in the same + file as CPU models -- <code>cpu_map.xml</code>. For example, + to explicitly specify the 'pcid' feature with Intel IvyBridge + CPU model:
Another paragraph above already says "The list of known feature names can be found in the same file as CPU models". If you think the existing paragraph is not enough, I suggest rewriting it so the document won't repeat exactly the same thing.
True. How about this rewrite:
"Once you choose a feature (e.g. 'pcid') from the `cpu_map.xml`, to specify it explicitly with the Intel IvyBridge CPU model [...]"
"Once you choose a feature (e.g. 'pcid') from the `cpu_map.xml`" doesn't seem to convey any additional information that wasn't mentioned before. What about just "For example, to explicitly specify the 'pcid' feature with Intel IvyBridge CPU model:"?
I'll consider whether to also add a note that before specifying extra CPU feature flags, one should check if the named CPU models provided by libvirt already include the said flags.
Maybe this would be too much information. It's harmless to set a feature explicitly to 'require' if the CPU model already contains the feature. -- Eduardo
On Mon, Jan 22, 2018 at 04:43:35PM -0200, Eduardo Habkost wrote:
On Wed, Jan 17, 2018 at 09:04:26AM +0100, Kashyap Chamarthy wrote:
[...]
The list of known CPU feature + names (e.g. 'vmx', 'cmt', et cetera) can be found in the same + file as CPU models -- <code>cpu_map.xml</code>. For example, + to explicitly specify the 'pcid' feature with Intel IvyBridge + CPU model:
Another paragraph above already says "The list of known feature names can be found in the same file as CPU models". If you think the existing paragraph is not enough, I suggest rewriting it so the document won't repeat exactly the same thing.
True. How about this rewrite:
"Once you choose a feature (e.g. 'pcid') from the `cpu_map.xml`, to specify it explicitly with the Intel IvyBridge CPU model [...]"
"Once you choose a feature (e.g. 'pcid') from the `cpu_map.xml`" doesn't seem to convey any additional information that wasn't mentioned before. What about just "For example, to explicitly specify the 'pcid' feature with Intel IvyBridge CPU model:"?
I was just trying to be explicit. But yours sound clearer too -- so can update to yours.
I'll consider whether to also add a note that before specifying extra CPU feature flags, one should check if the named CPU models provided by libvirt already include the said flags.
Maybe this would be too much information. It's harmless to set a feature explicitly to 'require' if the CPU model already contains the feature.
Okay, can remove it. (I was just operating under the principle of "explicit is better than implicit".) Thanks for the review. -- /kashyap
participants (2)
-
Eduardo Habkost -
Kashyap Chamarthy