Update the AMD memory encryption documentation to include information on
the Reverse Map Table (RMP) and the two table formats.

Signed-off-by: Tom Lendacky <thomas.lendacky@amd.com>
---
 .../arch/x86/amd-memory-encryption.rst        | 118 ++++++++++++++++++
 1 file changed, 118 insertions(+)

diff --git a/Documentation/arch/x86/amd-memory-encryption.rst b/Documentation/arch/x86/amd-memory-encryption.rst
index 6df3264f23b9..bd840df708ea 100644
--- a/Documentation/arch/x86/amd-memory-encryption.rst
+++ b/Documentation/arch/x86/amd-memory-encryption.rst
@@ -130,8 +130,126 @@ SNP feature support.
 
 More details in AMD64 APM[1] Vol 2: 15.34.10 SEV_STATUS MSR
 
+Reverse Map Table (RMP)
+=======================
+
+The RMP is a structure in system memory that is used to ensure a one-to-one
+mapping between system physical addresses and guest physical addresses. Each
+page of memory that is potentially assignable to guests has one entry within
+the RMP.
+
+The RMP table can be either contiguous in memory or a collection of segments
+in memory.
+
+Contiguous RMP
+--------------
+
+Support for this form of the RMP is present when support for SEV-SNP is
+present, which can be determined using the CPUID instruction::
+
+	0x8000001f[eax]:
+		Bit[4] indicates support for SEV-SNP
+
+The location of the RMP is identified to the hardware through two MSRs::
+
+        0xc0010132 (RMP_BASE):
+                System physical address of the first byte of the RMP
+
+        0xc0010133 (RMP_END):
+                System physical address of the last byte of the RMP
+
+Hardware requires that RMP_BASE and (RPM_END + 1) be 8KB aligned, but SEV
+firmware increases the alignment requirement to require a 1MB alignment.
+
+The RMP consists of a 16KB region used for processor bookkeeping followed
+by the RMP entries, which are 16 bytes in size. The size of the RMP
+determines the range of physical memory that the hypervisor can assign to
+SEV-SNP guests. The RMP covers the system physical address from::
+
+        0 to ((RMP_END + 1 - RMP_BASE - 16KB) / 16B) x 4KB.
+
+The current Linux support relies on BIOS to allocate/reserve the memory for
+the RMP and to set RMP_BASE and RMP_END appropriately. Linux uses the MSR
+values to locate the RMP and determine the size of the RMP. The RMP must
+cover all of system memory in order for Linux to enable SEV-SNP.
+
+Segmented RMP
+-------------
+
+Segmented RMP support is a new way of representing the layout of an RMP.
+Initial RMP support required the RMP table to be contiguous in memory.
+RMP accesses from a NUMA node on which the RMP doesn't reside
+can take longer than accesses from a NUMA node on which the RMP resides.
+Segmented RMP support allows the RMP entries to be located on the same
+node as the memory the RMP is covering, potentially reducing latency
+associated with accessing an RMP entry associated with the memory. Each
+RMP segment covers a specific range of system physical addresses.
+
+Support for this form of the RMP can be determined using the CPUID
+instruction::
+
+        0x8000001f[eax]:
+                Bit[23] indicates support for segmented RMP
+
+If supported, segmented RMP attributes can be found using the CPUID
+instruction::
+
+        0x80000025[eax]:
+                Bits[5:0]  minimum supported RMP segment size
+                Bits[11:6] maximum supported RMP segment size
+
+        0x80000025[ebx]:
+                Bits[9:0]  number of cacheable RMP segment definitions
+                Bit[10]    indicates if the number of cacheable RMP segments
+                           is a hard limit
+
+To enable a segmented RMP, a new MSR is available::
+
+        0xc0010136 (RMP_CFG):
+                Bit[0]     indicates if segmented RMP is enabled
+                Bits[13:8] contains the size of memory covered by an RMP
+                           segment (expressed as a power of 2)
+
+The RMP segment size defined in the RMP_CFG MSR applies to all segments
+of the RMP. Therefore each RMP segment covers a specific range of system
+physical addresses. For example, if the RMP_CFG MSR value is 0x2401, then
+the RMP segment coverage value is 0x24 => 36, meaning the size of memory
+covered by an RMP segment is 64GB (1 << 36). So the first RMP segment
+covers physical addresses from 0 to 0xF_FFFF_FFFF, the second RMP segment
+covers physical addresses from 0x10_0000_0000 to 0x1F_FFFF_FFFF, etc.
+
+When a segmented RMP is enabled, RMP_BASE points to the RMP bookkeeping
+area as it does today (16K in size). However, instead of RMP entries
+beginning immediately after the bookkeeping area, there is a 4K RMP
+segment table (RST). Each entry in the RST is 8-bytes in size and represents
+an RMP segment::
+
+        Bits[19:0]  mapped size (in GB)
+                    The mapped size can be less than the defined segment size.
+                    A value of zero, indicates that no RMP exists for the range
+                    of system physical addresses associated with this segment.
+        Bits[51:20] segment physical address
+                    This address is left shift 20-bits (or just masked when
+                    read) to form the physical address of the segment (1MB
+                    alignment).
+
+The RST can hold 512 segment entries but can be limited in size to the number
+of cacheable RMP segments (CPUID 0x80000025_EBX[9:0]) if the number of cacheable
+RMP segments is a hard limit (CPUID 0x80000025_EBX[10]).
+
+The current Linux support relies on BIOS to allocate/reserve the memory for
+the segmented RMP (the bookkeeping area, RST, and all segments), build the RST
+and to set RMP_BASE, RMP_END, and RMP_CFG appropriately. Linux uses the MSR
+values to locate the RMP and determine the size and location of the RMP
+segments. The RMP must cover all of system memory in order for Linux to enable
+SEV-SNP.
+
+More details in the AMD64 APM Vol 2, section "15.36.3 Reverse Map Table",
+docID: 24593.
+
 Secure VM Service Module (SVSM)
 ===============================
+
 SNP provides a feature called Virtual Machine Privilege Levels (VMPL) which
 defines four privilege levels at which guest software can run. The most
 privileged level is 0 and numerically higher numbers have lesser privileges.
-- 
2.43.2

On 9/30/2024 8:52 PM, Tom Lendacky wrote:
> Update the AMD memory encryption documentation to include information on
> the Reverse Map Table (RMP) and the two table formats.
> 
> Signed-off-by: Tom Lendacky <thomas.lendacky@amd.com>

Reviewed-by: Neeraj Upadhyay <Neeraj.Upadhyay@amd.com>

On 9/30/2024 8:52 PM, Tom Lendacky wrote:
> Update the AMD memory encryption documentation to include information on
> the Reverse Map Table (RMP) and the two table formats.
> 
> Signed-off-by: Tom Lendacky <thomas.lendacky@amd.com>
> ---
>  .../arch/x86/amd-memory-encryption.rst        | 118 ++++++++++++++++++
>  1 file changed, 118 insertions(+)
> 
> diff --git a/Documentation/arch/x86/amd-memory-encryption.rst b/Documentation/arch/x86/amd-memory-encryption.rst
> index 6df3264f23b9..bd840df708ea 100644
> --- a/Documentation/arch/x86/amd-memory-encryption.rst
> +++ b/Documentation/arch/x86/amd-memory-encryption.rst
> @@ -130,8 +130,126 @@ SNP feature support.
>  
>  More details in AMD64 APM[1] Vol 2: 15.34.10 SEV_STATUS MSR
>  
> +Reverse Map Table (RMP)
> +=======================
> +
> +The RMP is a structure in system memory that is used to ensure a one-to-one
> +mapping between system physical addresses and guest physical addresses. Each
> +page of memory that is potentially assignable to guests has one entry within
> +the RMP.
> +
> +The RMP table can be either contiguous in memory or a collection of segments
> +in memory.
> +
> +Contiguous RMP
> +--------------
> +
> +Support for this form of the RMP is present when support for SEV-SNP is
> +present, which can be determined using the CPUID instruction::
> +
> +	0x8000001f[eax]:
> +		Bit[4] indicates support for SEV-SNP
> +
> +The location of the RMP is identified to the hardware through two MSRs::
> +
> +        0xc0010132 (RMP_BASE):
> +                System physical address of the first byte of the RMP
> +
> +        0xc0010133 (RMP_END):
> +                System physical address of the last byte of the RMP
> +
> +Hardware requires that RMP_BASE and (RPM_END + 1) be 8KB aligned, but SEV
> +firmware increases the alignment requirement to require a 1MB alignment.
> +
> +The RMP consists of a 16KB region used for processor bookkeeping followed
> +by the RMP entries, which are 16 bytes in size. The size of the RMP
> +determines the range of physical memory that the hypervisor can assign to
> +SEV-SNP guests. The RMP covers the system physical address from::
> +
> +        0 to ((RMP_END + 1 - RMP_BASE - 16KB) / 16B) x 4KB.
> +
> +The current Linux support relies on BIOS to allocate/reserve the memory for
> +the RMP and to set RMP_BASE and RMP_END appropriately. Linux uses the MSR
> +values to locate the RMP and determine the size of the RMP. The RMP must
> +cover all of system memory in order for Linux to enable SEV-SNP.
> +
> +Segmented RMP
> +-------------
> +
> +Segmented RMP support is a new way of representing the layout of an RMP.
> +Initial RMP support required the RMP table to be contiguous in memory.
> +RMP accesses from a NUMA node on which the RMP doesn't reside
> +can take longer than accesses from a NUMA node on which the RMP resides.
> +Segmented RMP support allows the RMP entries to be located on the same
> +node as the memory the RMP is covering, potentially reducing latency
> +associated with accessing an RMP entry associated with the memory. Each
> +RMP segment covers a specific range of system physical addresses.
> +
> +Support for this form of the RMP can be determined using the CPUID
> +instruction::
> +
> +        0x8000001f[eax]:
> +                Bit[23] indicates support for segmented RMP
> +
> +If supported, segmented RMP attributes can be found using the CPUID
> +instruction::
> +
> +        0x80000025[eax]:
> +                Bits[5:0]  minimum supported RMP segment size
> +                Bits[11:6] maximum supported RMP segment size
> +
> +        0x80000025[ebx]:
> +                Bits[9:0]  number of cacheable RMP segment definitions
> +                Bit[10]    indicates if the number of cacheable RMP segments
> +                           is a hard limit
> +
> +To enable a segmented RMP, a new MSR is available::

This may be more appropriate:

To discover segmented RMP support, a new MSR is available::

> +
> +        0xc0010136 (RMP_CFG):
> +                Bit[0]     indicates if segmented RMP is enabled
> +                Bits[13:8] contains the size of memory covered by an RMP
> +                           segment (expressed as a power of 2)
> +
> +The RMP segment size defined in the RMP_CFG MSR applies to all segments
> +of the RMP. Therefore each RMP segment covers a specific range of system
> +physical addresses. For example, if the RMP_CFG MSR value is 0x2401, then
> +the RMP segment coverage value is 0x24 => 36, meaning the size of memory
> +covered by an RMP segment is 64GB (1 << 36). So the first RMP segment
> +covers physical addresses from 0 to 0xF_FFFF_FFFF, the second RMP segment
> +covers physical addresses from 0x10_0000_0000 to 0x1F_FFFF_FFFF, etc.
> +
> +When a segmented RMP is enabled, RMP_BASE points to the RMP bookkeeping
> +area as it does today (16K in size). However, instead of RMP entries
> +beginning immediately after the bookkeeping area, there is a 4K RMP
> +segment table (RST). Each entry in the RST is 8-bytes in size and represents
> +an RMP segment::
> +
> +        Bits[19:0]  mapped size (in GB)
> +                    The mapped size can be less than the defined segment size.
> +                    A value of zero, indicates that no RMP exists for the range
> +                    of system physical addresses associated with this segment.
> +        Bits[51:20] segment physical address
> +                    This address is left shift 20-bits (or just masked when
> +                    read) to form the physical address of the segment (1MB
> +                    alignment).
> +
> +The RST can hold 512 segment entries but can be limited in size to the number
> +of cacheable RMP segments (CPUID 0x80000025_EBX[9:0]) if the number of cacheable
> +RMP segments is a hard limit (CPUID 0x80000025_EBX[10]).
> +
> +The current Linux support relies on BIOS to allocate/reserve the memory for
> +the segmented RMP (the bookkeeping area, RST, and all segments), build the RST
> +and to set RMP_BASE, RMP_END, and RMP_CFG appropriately. Linux uses the MSR
> +values to locate the RMP and determine the size and location of the RMP
> +segments. The RMP must cover all of system memory in order for Linux to enable
> +SEV-SNP.
> +
> +More details in the AMD64 APM Vol 2, section "15.36.3 Reverse Map Table",
> +docID: 24593.
> +
>  Secure VM Service Module (SVSM)
>  ===============================
> +
>  SNP provides a feature called Virtual Machine Privilege Levels (VMPL) which
>  defines four privilege levels at which guest software can run. The most
>  privileged level is 0 and numerically higher numbers have lesser privileges.

On 10/18/24 01:56, Nikunj A. Dadhania wrote:
> On 9/30/2024 8:52 PM, Tom Lendacky wrote:
>> Update the AMD memory encryption documentation to include information on
>> the Reverse Map Table (RMP) and the two table formats.
>>
>> Signed-off-by: Tom Lendacky <thomas.lendacky@amd.com>
>> ---
>>  .../arch/x86/amd-memory-encryption.rst        | 118 ++++++++++++++++++
>>  1 file changed, 118 insertions(+)
>>
>> diff --git a/Documentation/arch/x86/amd-memory-encryption.rst b/Documentation/arch/x86/amd-memory-encryption.rst
>> index 6df3264f23b9..bd840df708ea 100644
>> --- a/Documentation/arch/x86/amd-memory-encryption.rst
>> +++ b/Documentation/arch/x86/amd-memory-encryption.rst
>> @@ -130,8 +130,126 @@ SNP feature support.
>>  
>>  More details in AMD64 APM[1] Vol 2: 15.34.10 SEV_STATUS MSR
>>  
>> +Reverse Map Table (RMP)
>> +=======================
>> +
>> +The RMP is a structure in system memory that is used to ensure a one-to-one
>> +mapping between system physical addresses and guest physical addresses. Each
>> +page of memory that is potentially assignable to guests has one entry within
>> +the RMP.
>> +
>> +The RMP table can be either contiguous in memory or a collection of segments
>> +in memory.
>> +
>> +Contiguous RMP
>> +--------------
>> +
>> +Support for this form of the RMP is present when support for SEV-SNP is
>> +present, which can be determined using the CPUID instruction::
>> +
>> +	0x8000001f[eax]:
>> +		Bit[4] indicates support for SEV-SNP
>> +
>> +The location of the RMP is identified to the hardware through two MSRs::
>> +
>> +        0xc0010132 (RMP_BASE):
>> +                System physical address of the first byte of the RMP
>> +
>> +        0xc0010133 (RMP_END):
>> +                System physical address of the last byte of the RMP
>> +
>> +Hardware requires that RMP_BASE and (RPM_END + 1) be 8KB aligned, but SEV
>> +firmware increases the alignment requirement to require a 1MB alignment.
>> +
>> +The RMP consists of a 16KB region used for processor bookkeeping followed
>> +by the RMP entries, which are 16 bytes in size. The size of the RMP
>> +determines the range of physical memory that the hypervisor can assign to
>> +SEV-SNP guests. The RMP covers the system physical address from::
>> +
>> +        0 to ((RMP_END + 1 - RMP_BASE - 16KB) / 16B) x 4KB.
>> +
>> +The current Linux support relies on BIOS to allocate/reserve the memory for
>> +the RMP and to set RMP_BASE and RMP_END appropriately. Linux uses the MSR
>> +values to locate the RMP and determine the size of the RMP. The RMP must
>> +cover all of system memory in order for Linux to enable SEV-SNP.
>> +
>> +Segmented RMP
>> +-------------
>> +
>> +Segmented RMP support is a new way of representing the layout of an RMP.
>> +Initial RMP support required the RMP table to be contiguous in memory.
>> +RMP accesses from a NUMA node on which the RMP doesn't reside
>> +can take longer than accesses from a NUMA node on which the RMP resides.
>> +Segmented RMP support allows the RMP entries to be located on the same
>> +node as the memory the RMP is covering, potentially reducing latency
>> +associated with accessing an RMP entry associated with the memory. Each
>> +RMP segment covers a specific range of system physical addresses.
>> +
>> +Support for this form of the RMP can be determined using the CPUID
>> +instruction::
>> +
>> +        0x8000001f[eax]:
>> +                Bit[23] indicates support for segmented RMP
>> +
>> +If supported, segmented RMP attributes can be found using the CPUID
>> +instruction::
>> +
>> +        0x80000025[eax]:
>> +                Bits[5:0]  minimum supported RMP segment size
>> +                Bits[11:6] maximum supported RMP segment size
>> +
>> +        0x80000025[ebx]:
>> +                Bits[9:0]  number of cacheable RMP segment definitions
>> +                Bit[10]    indicates if the number of cacheable RMP segments
>> +                           is a hard limit
>> +
>> +To enable a segmented RMP, a new MSR is available::
> 
> This may be more appropriate:
> 
> To discover segmented RMP support, a new MSR is available::

Not really. You discover the ability to use segmented RMP (and the
availability of the MSR) through CPUID and then enable it through the MSR.
It's just that Linux relies on BIOS to set everything up and then we look
at the MSR to see if BIOS built a segmented RMP (I allude to that a few
paragraphs below).

Thanks,
Tom

> 
>> +
>> +        0xc0010136 (RMP_CFG):
>> +                Bit[0]     indicates if segmented RMP is enabled
>> +                Bits[13:8] contains the size of memory covered by an RMP
>> +                           segment (expressed as a power of 2)
>> +
>> +The RMP segment size defined in the RMP_CFG MSR applies to all segments
>> +of the RMP. Therefore each RMP segment covers a specific range of system
>> +physical addresses. For example, if the RMP_CFG MSR value is 0x2401, then
>> +the RMP segment coverage value is 0x24 => 36, meaning the size of memory
>> +covered by an RMP segment is 64GB (1 << 36). So the first RMP segment
>> +covers physical addresses from 0 to 0xF_FFFF_FFFF, the second RMP segment
>> +covers physical addresses from 0x10_0000_0000 to 0x1F_FFFF_FFFF, etc.
>> +
>> +When a segmented RMP is enabled, RMP_BASE points to the RMP bookkeeping
>> +area as it does today (16K in size). However, instead of RMP entries
>> +beginning immediately after the bookkeeping area, there is a 4K RMP
>> +segment table (RST). Each entry in the RST is 8-bytes in size and represents
>> +an RMP segment::
>> +
>> +        Bits[19:0]  mapped size (in GB)
>> +                    The mapped size can be less than the defined segment size.
>> +                    A value of zero, indicates that no RMP exists for the range
>> +                    of system physical addresses associated with this segment.
>> +        Bits[51:20] segment physical address
>> +                    This address is left shift 20-bits (or just masked when
>> +                    read) to form the physical address of the segment (1MB
>> +                    alignment).
>> +
>> +The RST can hold 512 segment entries but can be limited in size to the number
>> +of cacheable RMP segments (CPUID 0x80000025_EBX[9:0]) if the number of cacheable
>> +RMP segments is a hard limit (CPUID 0x80000025_EBX[10]).
>> +
>> +The current Linux support relies on BIOS to allocate/reserve the memory for
>> +the segmented RMP (the bookkeeping area, RST, and all segments), build the RST
>> +and to set RMP_BASE, RMP_END, and RMP_CFG appropriately. Linux uses the MSR
>> +values to locate the RMP and determine the size and location of the RMP
>> +segments. The RMP must cover all of system memory in order for Linux to enable
>> +SEV-SNP.
>> +
>> +More details in the AMD64 APM Vol 2, section "15.36.3 Reverse Map Table",
>> +docID: 24593.
>> +
>>  Secure VM Service Module (SVSM)
>>  ===============================
>> +
>>  SNP provides a feature called Virtual Machine Privilege Levels (VMPL) which
>>  defines four privilege levels at which guest software can run. The most
>>  privileged level is 0 and numerically higher numbers have lesser privileges.
>