Documentation/arch/x86: Add HYGON secure virtualization description

Upstream: no

Add the HYGON secure virtualization document describing the secure
virtualization features.

Signed-off-by: Xin Jiang <jiangxin@hygon.cn>
Signed-off-by: hanliyang <hanliyang@hygon.cn>

Documentation/arch/x86/hygon-secure-virtualization.rst

@@ -0,0 +1,100 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===========================
+HYGON Secure Virtualization
+===========================
+
+China Secure Virtualization (CSV) is a key virtualization feature on Hygon
+processors.
+
+The 1st generation of CSV (CSV for short) is a secure virtualization technology
+to provide memory encryption for the virtual machine (VM), each VM's memory is
+encrypted by its unique encryption key which is managed by secure processor.
+
+The 2nd generation of CSV (CSV2 for short) provides security enhancement to CSV
+by encrypting not only the VM's memory but also the vCPU's registers of the VM.
+
+The 3rd generation of CSV (CSV3 for short) is a more advanced secure
+virtualization technology, it integrates secure processor, memory encryption and
+memory isolation to provide the ability to protect guest's private data. The CSV3
+guest's context like CPU registers, control block and nested page table is accessed
+only by the guest itself and the secure processor. Neither other guests nor the
+host can tamper with the guest's context.
+
+The secure processor is a separate processor inside Hygon hardware. The firmware
+running inside the secure processor performs activities in a secure way, such as
+OVMF encryption, VM launch, secure memory management and nested page table
+management etc. For more information, please see CSV spec and CSV3 spec from Hygon.
+
+A CSV guest is running in the memory that is encrypted with a dedicated encrypt
+key which is set by the secure processor. And CSV guest's memory encrypt key is
+unique from the others. A low latency crypto engine resides on Hygon hardware
+to minimize the negative effect on memory bandwidth. In CSV guest, a guest private
+page will be automatically decrypted when read from memory and encrypted when
+written to memory.
+
+CSV3 provides an enhancement technology named memory isolation to improve the
+security. A dedicated memory isolation hardware is built in Hygon hardware. Only
+the secure processor has privilege to configure the isolation hardware. The VMM
+allocates CMA memory and transfers them to secure processor. The secure processor
+maps the memory to secure nested page table and manages them as guest's private
+memory. Any memory access (read or write) to CSV3 guest's private memory outside
+the guest will be blocked by isolation hardware.
+
+A CSV3 guest may declare some memory regions as shared to share data with the
+host. When a page is set as shared, read/write on the page will bypass the
+isolation hardware and the guest's shared memory can be accessed by the host. A
+method named CSV3 secure call command is designed and CSV3 guest sends the secure
+call command to the secure processor to change private memory to shared memory.
+In the method, 2 dedicated pages are reserved at early stage of the guest. Any
+read/write on the dedicated pages will trigger nested page fault. When NPF
+happens, the host helps to issue an external command to the secure processor but
+cannot tamper with the data in the guest's private memory. Then the secure
+processor checks the fault address and handles the command if the address is
+exactly the dedicated pages.
+
+Support for CSV can be determined through the CPUID instruction. The CPUID
+function 0x8000001f reports information to CSV::
+
+	0x8000001f[eax]:
+		Bit[1]	  indicates support for CSV
+		Bit[3]	  indicates support for CSV2
+		Bit[30]	  indicates support for CSV3
+
+If CSV is support, MSR 0xc0010131 can be used to determine if CSV is active::
+
+	0xc0010131:
+		Bit[0]	  0 = CSV is not active
+			  1 = CSV is active
+		Bit[1]	  0 = CSV2 is not active
+			  1 = CSV2 is active
+		Bit[30]	  0 = CSV3 is not active
+			  1 = CSV3 is active
+
+All CSV/CSV2's configurations must be enabled in CSV3. Linux can activate CSV3 by
+default (CONFIG_HYGON_CSV=y, CONFIG_CMA=y). CSV3 guest's memory is managed by
+CMA (Contiguous Memory Allocation). User must specify CSV3 total secure memory on
+the linux kernel command line with csv_mem_size or csv_mem_percentage::
+
+	csv_mem_size=nn[MG]
+		[KNL,CSV]
+		Reserve specified CSV3 memory size in CMA. CSV3's memory will be
+		allocated from these CMAs.
+		For instance, csv_mem_size=40G, 40G memory is reserved for CSV3.
+
+	csv_mem_percentage=nn
+		[KNL,CSV]
+		Reserve specified memory size which is prorated according to the
+		whole system memory size. CSV3 guest's memory will be allocated
+		from these CMAs.
+		For instance, csv_mem_percentage=60, means 60% system memory is
+		reserved for CSV3.
+		The maximum percentage is 80. And the default percentage is 0.
+
+Limitations
+The reserved CSV3 memory within CMA cannot be used by kernel or any application that
+may pin memory using long term gup during the application's life time.
+For instance, if the whole system memory is 64G and 32G is reserved for CSV3 with
+kernel command line csv_mem_percentage=50, only 32G memory is available for CSV/CSV2.
+As a result, user will fail to run a CSV/CSV2 guest with memory size which exceeds
+32G.