diff mbox series

[RFC,04/22] x86/msr-index: add references to vendor manuals

Message ID 7e4418cfb1daa172e78fc47098a4018ae0493e23.1698261255.git.edwin.torok@cloud.com (mailing list archive)
State New, archived
Headers show
Series vPMU bugfixes and support for PMUv5 | expand

Commit Message

Edwin Torok Oct. 25, 2023, 7:29 p.m. UTC
From: Edwin Török <edvin.torok@citrix.com>

To more easily lookup the semantics of these MSRs add references to
vendor manuals.

Signed-off-by: Edwin Török <edvin.torok@citrix.com>
---
 xen/arch/x86/include/asm/msr-index.h | 10 ++++++++++
 1 file changed, 10 insertions(+)

Comments

Jan Beulich Oct. 30, 2023, 4:15 p.m. UTC | #1
On 25.10.2023 21:29, Edwin Török wrote:
> To more easily lookup the semantics of these MSRs add references to
> vendor manuals.

As much as I appreciate the intention, ...

> --- a/xen/arch/x86/include/asm/msr-index.h
> +++ b/xen/arch/x86/include/asm/msr-index.h
> @@ -13,6 +13,16 @@
>   * Blocks of related constants should be sorted by MSR index.  The constant
>   * names should be as concise as possible, and the bit names may have an
>   * abbreviated name.  Exceptions will be considered on a case-by-case basis.
> + *
> + * References:
> + * - https://software.intel.com/content/www/us/en/develop/articles/intel-sdm.html
> + *    Intel(R) 64 and IA-32 architectures SDM volume 4: Model-specific registers
> + *    Chapter 2, "Model-Specific Registers (MSRs)"

... at least Intel's URL has changed several times over the years. Volume
and chapter numbers change even more frequently. Any such is liable to go
stale at some point.

Jan

> + * - https://developer.amd.com/resources/developer-guides-manuals/
> + *    AMD64 Architecture Programmer’s Manual Volume 2: System Programming
> + *    Appendix A "MSR Cross-Reference"
> + *
>   */
>  
>  #define MSR_P5_MC_ADDR                      0
Andrew Cooper Oct. 31, 2023, 11:34 a.m. UTC | #2
On 30/10/2023 4:15 pm, Jan Beulich wrote:
>> --- a/xen/arch/x86/include/asm/msr-index.h
>> +++ b/xen/arch/x86/include/asm/msr-index.h
>> @@ -13,6 +13,16 @@
>>   * Blocks of related constants should be sorted by MSR index.  The constant
>>   * names should be as concise as possible, and the bit names may have an
>>   * abbreviated name.  Exceptions will be considered on a case-by-case basis.
>> + *
>> + * References:
>> + * - https://software.intel.com/content/www/us/en/develop/articles/intel-sdm.html
>> + *    Intel(R) 64 and IA-32 architectures SDM volume 4: Model-specific registers
>> + *    Chapter 2, "Model-Specific Registers (MSRs)"
> ... at least Intel's URL has changed several times over the years. Volume
> and chapter numbers change even more frequently. Any such is liable to go
> stale at some point.

https://intel.com/sdm

This one has been valid for roughly the lifetime of intel.com, and is
committed to stay so.

>
> Jan
>
>> + * - https://developer.amd.com/resources/developer-guides-manuals/

whereas AMD really have broken this one, and don't seem to be showing
any urgency in unbreaking it...  Right now there is no landing page at
all for manuals.

~Andrew
Edwin Torok Oct. 31, 2023, 12:18 p.m. UTC | #3
> On 31 Oct 2023, at 11:34, Andrew Cooper <Andrew.Cooper3@citrix.com> wrote:
> 
> On 30/10/2023 4:15 pm, Jan Beulich wrote:
>> 
>>> --- a/xen/arch/x86/include/asm/msr-index.h
>>> +++ b/xen/arch/x86/include/asm/msr-index.h
>>> @@ -13,6 +13,16 @@
>>> * Blocks of related constants should be sorted by MSR index. The constant
>>> * names should be as concise as possible, and the bit names may have an
>>> * abbreviated name. Exceptions will be considered on a case-by-case basis.
>>> + *
>>> + * References:
>>> + * - https://software.intel.com/content/www/us/en/develop/articles/intel-sdm.html
>>> + * Intel(R) 64 and IA-32 architectures SDM volume 4: Model-specific registers
>>> + * Chapter 2, "Model-Specific Registers (MSRs)"
>>> 
>> ... at least Intel's URL has changed several times over the years. Volume
>> and chapter numbers change even more frequently. Any such is liable to go
>> stale at some point.
> 
> https://intel.com/sdm
> 
> This one has been valid for roughly the lifetime of intel.com, and is committed to stay so.

That is useful to know, I'll update the URL.

> 
>> 
>> Jan
>> 
>> 
>>> + * - https://developer.amd.com/resources/developer-guides-manuals/
> 
> whereas AMD really have broken this one, and don't seem to be showing any urgency in unbreaking it...  Right now there is no landing page at all for manuals.
> 


Linux commits appear to reference a certain bugzilla that has the manuals uploaded: https://bugzilla.kernel.org/show_bug.cgi?id=206537
(although they will go stale in another way, e.g. I see no 2023 manuals there, but at least you know which manual a given commit referenced).
Although referencing someone else's bugzilla in the Xen codebase wouldn't be a nice thing to do, so if we do this it'd probably have to be something hosted on Xen infra.

For now I'll probably drop the URL and just keep the name (so at least you'd know what to search for).


Best regards,
--Edwin

> ~Andrew
diff mbox series

Patch

diff --git a/xen/arch/x86/include/asm/msr-index.h b/xen/arch/x86/include/asm/msr-index.h
index 2853a276ca..8601f8f426 100644
--- a/xen/arch/x86/include/asm/msr-index.h
+++ b/xen/arch/x86/include/asm/msr-index.h
@@ -13,6 +13,16 @@ 
  * Blocks of related constants should be sorted by MSR index.  The constant
  * names should be as concise as possible, and the bit names may have an
  * abbreviated name.  Exceptions will be considered on a case-by-case basis.
+ *
+ * References:
+ * - https://software.intel.com/content/www/us/en/develop/articles/intel-sdm.html
+ *    Intel(R) 64 and IA-32 architectures SDM volume 4: Model-specific registers
+ *    Chapter 2, "Model-Specific Registers (MSRs)"
+ *
+ * - https://developer.amd.com/resources/developer-guides-manuals/
+ *    AMD64 Architecture Programmer’s Manual Volume 2: System Programming
+ *    Appendix A "MSR Cross-Reference"
+ *
  */
 
 #define MSR_P5_MC_ADDR                      0