Commit afbd4d42 authored by Jonathan Corbet's avatar Jonathan Corbet
Browse files

Merge branch 'x86' into docs-next 

Merge the x86 docs conversion from Changbin Du, who writes:

> The kernel now uses Sphinx to generate intelligent and beautiful
> documentation from reStructuredText files. I converted all of the Linux
> x86 docs to rst format in this serias.
>
> For you to preview, please visit below url:
> http://www.bytemem.com:8080/kernel-doc/index.html


>
> Thank you!

The whole series was:

    Acked-by: default avatarIngo Molnar <mingo@kernel.org>
parents 39a39d5b e115fb4b

Documentation/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -101,6 +101,7 @@ implementation. 
.. toctree::

   :maxdepth: 2



   x86/index

   sh/index



Filesystem Documentation

Documentation/x86/amd-memory-encryption.txt→Documentation/x86/amd-memory-encryption.rst

+10 −3
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



=====================

AMD Memory Encryption

=====================



Secure Memory Encryption (SME) and Secure Encrypted Virtualization (SEV) are

features found on AMD processors.
@@ -34,7 +40,7 @@ is operating in 64-bit or 32-bit PAE mode, in all other modes the SEV hardware 
forces the memory encryption bit to 1.



Support for SME and SEV can be determined through the CPUID instruction. The

CPUID function 0x8000001f reports information related to SME:

CPUID function 0x8000001f reports information related to SME::



	0x8000001f[eax]:

		Bit[0] indicates support for SME
@@ -48,14 +54,14 @@ CPUID function 0x8000001f reports information related to SME: 
			   addresses)



If support for SME is present, MSR 0xc00100010 (MSR_K8_SYSCFG) can be used to

determine if SME is enabled and/or to enable memory encryption:

determine if SME is enabled and/or to enable memory encryption::



	0xc0010010:

		Bit[23]   0 = memory encryption features are disabled

			  1 = memory encryption features are enabled



If SEV is supported, MSR 0xc0010131 (MSR_AMD64_SEV) can be used to determine if

SEV is active:

SEV is active::



	0xc0010131:

		Bit[0]	  0 = memory encryption is not active
@@ -68,6 +74,7 @@ requirements for the system. If this bit is not set upon Linux startup then 
Linux itself will not set it and memory encryption will not be possible.



The state of SME in the Linux kernel can be documented as follows:



	- Supported:

	  The CPU supports SME (determined through CPUID instruction).

Documentation/x86/boot.txt→Documentation/x86/boot.rst

+325 −203

File changed and moved.

Preview size limit exceeded, changes collapsed.

Documentation/x86/earlyprintk.txt→Documentation/x86/earlyprintk.rst

+66 −56
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



============

Early Printk

============



Mini-HOWTO for using the earlyprintk=dbgp boot option with a

USB2 Debug port key and a debug cable, on x86 systems.



You need two computers, the 'USB debug key' special gadget and

and two USB cables, connected like this:

and two USB cables, connected like this::



  [host/target] <-------> [USB debug key] <-------> [client/console]



1. There are a number of specific hardware requirements:

Hardware requirements

=====================



 a.) Host/target system needs to have USB debug port capability.

  a) Host/target system needs to have USB debug port capability.



     You can check this capability by looking at a 'Debug port' bit in

 the lspci -vvv output:

     the lspci -vvv output::



       # lspci -vvv

       ...
@@ -32,20 +38,20 @@ and two USB cables, connected like this: 
               Kernel modules: ehci-hcd

       ...



( If your system does not list a debug port capability then you probably

  won't be able to use the USB debug key. )

     .. note::

       If your system does not list a debug port capability then you probably

       won't be able to use the USB debug key.



 b.) You also need a NetChip USB debug cable/key:

  b) You also need a NetChip USB debug cable/key:



        http://www.plxtech.com/products/NET2000/NET20DC/default.asp



     This is a small blue plastic connector with two USB connections;

     it draws power from its USB connections.



 c.) You need a second client/console system with a high speed USB 2.0

     port.

  c) You need a second client/console system with a high speed USB 2.0 port.



 d.) The NetChip device must be plugged directly into the physical

  d) The NetChip device must be plugged directly into the physical

     debug port on the "host/target" system. You cannot use a USB hub in

     between the physical debug port and the "host/target" system.
@@ -65,29 +71,31 @@ and two USB cables, connected like this: 
     to the hardware vendor, because there is no reason not to wire

     this port into one of the physically accessible ports.



 e.) It is also important to note, that many versions of the NetChip

  e) It is also important to note, that many versions of the NetChip

     device require the "client/console" system to be plugged into the

     right hand side of the device (with the product logo facing up and

     readable left to right).  The reason being is that the 5 volt

     power supply is taken from only one side of the device and it

     must be the side that does not get rebooted.



2. Software requirements:

Software requirements

=====================



 a.) On the host/target system:

  a) On the host/target system:



    You need to enable the following kernel config option:

    You need to enable the following kernel config option::



      CONFIG_EARLY_PRINTK_DBGP=y



    And you need to add the boot command line: "earlyprintk=dbgp".



    (If you are using Grub, append it to the 'kernel' line in

    .. note::

      If you are using Grub, append it to the 'kernel' line in

      /etc/grub.conf.  If you are using Grub2 on a BIOS firmware system,

      append it to the 'linux' line in /boot/grub2/grub.cfg. If you are

      using Grub2 on an EFI firmware system, append it to the 'linux'

      or 'linuxefi' line in /boot/grub2/grub.cfg or

     /boot/efi/EFI/<distro>/grub.cfg.)

      /boot/efi/EFI/<distro>/grub.cfg.



    On systems with more than one EHCI debug controller you must

    specify the correct EHCI debug controller number.  The ordering
@@ -96,14 +104,15 @@ and two USB cables, connected like this: 
    controller.  To use the second EHCI debug controller, you would

    use the command line: "earlyprintk=dbgp1"



    NOTE: normally earlyprintk console gets turned off once the

    .. note::

      normally earlyprintk console gets turned off once the

      regular console is alive - use "earlyprintk=dbgp,keep" to keep

      this channel open beyond early bootup. This can be useful for

      debugging crashes under Xorg, etc.



 b.) On the client/console system:

  b) On the client/console system:



    You should enable the following kernel config option:

    You should enable the following kernel config option::



      CONFIG_USB_SERIAL_DEBUG=y
@@ -115,22 +124,23 @@ and two USB cables, connected like this: 
    it up to use /dev/ttyUSB0 - or use a raw 'cat /dev/ttyUSBx' to

    see the raw output.



 c.) On Nvidia Southbridge based systems: the kernel will try to probe

  c) On Nvidia Southbridge based systems: the kernel will try to probe

     and find out which port has a debug device connected.



3. Testing that it works fine:

Testing

=======



You can test the output by using earlyprintk=dbgp,keep and provoking

kernel messages on the host/target system. You can provoke a harmless

   kernel message by for example doing:

kernel message by for example doing::



     echo h > /proc/sysrq-trigger



   On the host/target system you should see this help line in "dmesg" output:

On the host/target system you should see this help line in "dmesg" output::



     SysRq : HELP : loglevel(0-9) reBoot Crashdump terminate-all-tasks(E) memory-full-oom-kill(F) kill-all-tasks(I) saK show-backtrace-all-active-cpus(L) show-memory-usage(M) nice-all-RT-tasks(N) powerOff show-registers(P) show-all-timers(Q) unRaw Sync show-task-states(T) Unmount show-blocked-tasks(W) dump-ftrace-buffer(Z)



   On the client/console system do:

On the client/console system do::



       cat /dev/ttyUSB0

Documentation/x86/entry_64.txt→Documentation/x86/entry_64.rst

+9 −3
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



==============

Kernel Entries

==============



This file documents some of the kernel entries in

arch/x86/entry/entry_64.S.  A lot of this explanation is adapted from

an email from Ingo Molnar:
@@ -59,7 +65,7 @@ Now, there's a secondary complication: there's a cheap way to test 
which mode the CPU is in and an expensive way.



The cheap way is to pick this info off the entry frame on the kernel

stack, from the CS of the ptregs area of the kernel stack:

stack, from the CS of the ptregs area of the kernel stack::



	xorl %ebx,%ebx

	testl $3,CS+8(%rsp)
@@ -67,7 +73,7 @@ stack, from the CS of the ptregs area of the kernel stack: 
	SWAPGS



The expensive (paranoid) way is to read back the MSR_GS_BASE value

(which is what SWAPGS modifies):

(which is what SWAPGS modifies)::



	movl $1,%ebx

	movl $MSR_GS_BASE,%ecx