docs: arm64: convert docs to ReST and rename to .rst

The documentation is in a format that is very close to ReST format.

The conversion is actually:
  - add blank lines in order to identify paragraphs;
  - fixing tables markups;
  - adding some lists markups;
  - marking literal blocks;
  - adjust some title markups.

At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Documentation/arm64/arm-acpi.txt → Documentation/arm64/arm-acpi.rst

+=====================
 ACPI on ARMv8 Servers
----------------------
+=====================
+
 ACPI can be used for ARMv8 general purpose servers designed to follow
 the ARM SBSA (Server Base System Architecture) [0] and SBBR (Server
 Base Boot Requirements) [1] specifications.  Please note that the SBBR
@@ -34,28 +36,28 @@ of the summary text almost directly, to be honest.
 
 The short form of the rationale for ACPI on ARM is:
 
--- ACPI’s byte code (AML) allows the platform to encode hardware behavior,
+-  ACPI’s byte code (AML) allows the platform to encode hardware behavior,
    while DT explicitly does not support this.  For hardware vendors, being
    able to encode behavior is a key tool used in supporting operating
    system releases on new hardware.
 
--- ACPI’s OSPM defines a power management model that constrains what the
+-  ACPI’s OSPM defines a power management model that constrains what the
    platform is allowed to do into a specific model, while still providing
    flexibility in hardware design.
 
--- In the enterprise server environment, ACPI has established bindings (such
+-  In the enterprise server environment, ACPI has established bindings (such
    as for RAS) which are currently used in production systems.  DT does not.
    Such bindings could be defined in DT at some point, but doing so means ARM
    and x86 would end up using completely different code paths in both firmware
    and the kernel.
 
--- Choosing a single interface to describe the abstraction between a platform
+-  Choosing a single interface to describe the abstraction between a platform
    and an OS is important.  Hardware vendors would not be required to implement
    both DT and ACPI if they want to support multiple operating systems.  And,
    agreeing on a single interface instead of being fragmented into per OS
    interfaces makes for better interoperability overall.
 
--- The new ACPI governance process works well and Linux is now at the same
+-  The new ACPI governance process works well and Linux is now at the same
    table as hardware vendors and other OS vendors.  In fact, there is no
    longer any reason to feel that ACPI only belongs to Windows or that
    Linux is in any way secondary to Microsoft in this arena.  The move of
@@ -169,31 +171,31 @@ For the ACPI core to operate properly, and in turn provide the information
 the kernel needs to configure devices, it expects to find the following
 tables (all section numbers refer to the ACPI 6.1 specification):
 
-    -- RSDP (Root System Description Pointer), section 5.2.5
+    -  RSDP (Root System Description Pointer), section 5.2.5
 
-    -- XSDT (eXtended System Description Table), section 5.2.8
+    -  XSDT (eXtended System Description Table), section 5.2.8
 
-    -- FADT (Fixed ACPI Description Table), section 5.2.9
+    -  FADT (Fixed ACPI Description Table), section 5.2.9
 
-    -- DSDT (Differentiated System Description Table), section
+    -  DSDT (Differentiated System Description Table), section
        5.2.11.1
 
-    -- MADT (Multiple APIC Description Table), section 5.2.12
+    -  MADT (Multiple APIC Description Table), section 5.2.12
 
-    -- GTDT (Generic Timer Description Table), section 5.2.24
+    -  GTDT (Generic Timer Description Table), section 5.2.24
 
-    -- If PCI is supported, the MCFG (Memory mapped ConFiGuration
+    -  If PCI is supported, the MCFG (Memory mapped ConFiGuration
        Table), section 5.2.6, specifically Table 5-31.
 
-    -- If booting without a console=<device> kernel parameter is
+    -  If booting without a console=<device> kernel parameter is
        supported, the SPCR (Serial Port Console Redirection table),
        section 5.2.6, specifically Table 5-31.
 
-    -- If necessary to describe the I/O topology, SMMUs and GIC ITSs,
+    -  If necessary to describe the I/O topology, SMMUs and GIC ITSs,
        the IORT (Input Output Remapping Table, section 5.2.6, specifically
        Table 5-31).
 
-    -- If NUMA is supported, the SRAT (System Resource Affinity Table)
+    -  If NUMA is supported, the SRAT (System Resource Affinity Table)
        and SLIT (System Locality distance Information Table), sections
        5.2.16 and 5.2.17, respectively.
 
@@ -269,9 +271,9 @@ describes how to define the structure of an object returned via _DSD, and
 how specific data structures are defined by specific UUIDs.  Linux should
 only use the _DSD Device Properties UUID [5]:
 
-   -- UUID: daffd814-6eba-4d8c-8a91-bc9bbf4aa301
+   - UUID: daffd814-6eba-4d8c-8a91-bc9bbf4aa301
 
-   -- http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf
+   - http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf
 
 The UEFI Forum provides a mechanism for registering device properties [4]
 so that they may be used across all operating systems supporting ACPI.
@@ -327,10 +329,10 @@ turning a device full off.
 
 There are two options for using those Power Resources.  They can:
 
-   -- be managed in a _PSx method which gets called on entry to power
+   -  be managed in a _PSx method which gets called on entry to power
       state Dx.
 
-   -- be declared separately as power resources with their own _ON and _OFF
+   -  be declared separately as power resources with their own _ON and _OFF
       methods.  They are then tied back to D-states for a particular device
       via _PRx which specifies which power resources a device needs to be on
       while in Dx.  Kernel then tracks number of devices using a power resource
@@ -339,16 +341,16 @@ There are two options for using those Power Resources.  They can:
 The kernel ACPI code will also assume that the _PSx methods follow the normal
 ACPI rules for such methods:
 
-   -- If either _PS0 or _PS3 is implemented, then the other method must also
+   -  If either _PS0 or _PS3 is implemented, then the other method must also
       be implemented.
 
-   -- If a device requires usage or setup of a power resource when on, the ASL
+   -  If a device requires usage or setup of a power resource when on, the ASL
       should organize that it is allocated/enabled using the _PS0 method.
 
-   -- Resources allocated or enabled in the _PS0 method should be disabled
+   -  Resources allocated or enabled in the _PS0 method should be disabled
       or de-allocated in the _PS3 method.
 
-   -- Firmware will leave the resources in a reasonable state before handing
+   -  Firmware will leave the resources in a reasonable state before handing
       over control to the kernel.
 
 Such code in _PSx methods will of course be very platform specific.  But,
@@ -394,52 +396,52 @@ else must be discovered by the driver probe function.  Then, have the rest
 of the driver operate off of the contents of that struct.  Doing so should
 allow most divergence between ACPI and DT functionality to be kept local to
 the probe function instead of being scattered throughout the driver.  For
-example:
-
-static int device_probe_dt(struct platform_device *pdev)
-{
-       /* DT specific functionality */
-       ...
-}
-
-static int device_probe_acpi(struct platform_device *pdev)
-{
-       /* ACPI specific functionality */
-       ...
-}
-
-static int device_probe(struct platform_device *pdev)
-{
-       ...
-       struct device_node node = pdev->dev.of_node;
-       ...
-
-       if (node)
-               ret = device_probe_dt(pdev);
-       else if (ACPI_HANDLE(&pdev->dev))
-               ret = device_probe_acpi(pdev);
-       else
-               /* other initialization */
-               ...
-       /* Continue with any generic probe operations */
-       ...
-}
+example::
+
+  static int device_probe_dt(struct platform_device *pdev)
+  {
+         /* DT specific functionality */
+         ...
+  }
+
+  static int device_probe_acpi(struct platform_device *pdev)
+  {
+         /* ACPI specific functionality */
+         ...
+  }
+
+  static int device_probe(struct platform_device *pdev)
+  {
+         ...
+         struct device_node node = pdev->dev.of_node;
+         ...
+
+         if (node)
+                 ret = device_probe_dt(pdev);
+         else if (ACPI_HANDLE(&pdev->dev))
+                 ret = device_probe_acpi(pdev);
+         else
+                 /* other initialization */
+                 ...
+         /* Continue with any generic probe operations */
+         ...
+  }
 
 DO keep the MODULE_DEVICE_TABLE entries together in the driver to make it
 clear the different names the driver is probed for, both from DT and from
-ACPI:
+ACPI::
 
-static struct of_device_id virtio_mmio_match[] = {
-        { .compatible = "virtio,mmio", },
-        { }
-};
-MODULE_DEVICE_TABLE(of, virtio_mmio_match);
+  static struct of_device_id virtio_mmio_match[] = {
+          { .compatible = "virtio,mmio", },
+          { }
+  };
+  MODULE_DEVICE_TABLE(of, virtio_mmio_match);
 
-static const struct acpi_device_id virtio_mmio_acpi_match[] = {
-        { "LNRO0005", },
-        { }
-};
-MODULE_DEVICE_TABLE(acpi, virtio_mmio_acpi_match);
+  static const struct acpi_device_id virtio_mmio_acpi_match[] = {
+          { "LNRO0005", },
+          { }
+  };
+  MODULE_DEVICE_TABLE(acpi, virtio_mmio_acpi_match);
 
 
 ASWG
@@ -471,7 +473,8 @@ Linux Code
 Individual items specific to Linux on ARM, contained in the the Linux
 source code, are in the list that follows:
 
-ACPI_OS_NAME           This macro defines the string to be returned when
+ACPI_OS_NAME
+                       This macro defines the string to be returned when
                        an ACPI method invokes the _OS method.  On ARM64
                        systems, this macro will be "Linux" by default.
                        The command line parameter acpi_os=<string>
@@ -482,38 +485,44 @@ ACPI_OS_NAME           This macro defines the string to be returned when
 ACPI Objects
 ------------
 Detailed expectations for ACPI tables and object are listed in the file
-Documentation/arm64/acpi_object_usage.txt.
+Documentation/arm64/acpi_object_usage.rst.
 
 
 References
 ----------
-[0] http://silver.arm.com -- document ARM-DEN-0029, or newer
+[0] http://silver.arm.com
+    document ARM-DEN-0029, or newer:
     "Server Base System Architecture", version 2.3, dated 27 Mar 2014
 
 [1] http://infocenter.arm.com/help/topic/com.arm.doc.den0044a/Server_Base_Boot_Requirements.pdf
     Document ARM-DEN-0044A, or newer: "Server Base Boot Requirements, System
     Software on ARM Platforms", dated 16 Aug 2014
 
-[2] http://www.secretlab.ca/archives/151, 10 Jan 2015, Copyright (c) 2015,
+[2] http://www.secretlab.ca/archives/151,
+    10 Jan 2015, Copyright (c) 2015,
     Linaro Ltd., written by Grant Likely.
 
-[3] AMD ACPI for Seattle platform documentation:
+[3] AMD ACPI for Seattle platform documentation
     http://amd-dev.wpengine.netdna-cdn.com/wordpress/media/2012/10/Seattle_ACPI_Guide.pdf
 
-[4] http://www.uefi.org/acpi -- please see the link for the "ACPI _DSD Device
+
+[4] http://www.uefi.org/acpi
+    please see the link for the "ACPI _DSD Device
     Property Registry Instructions"
 
-[5] http://www.uefi.org/acpi -- please see the link for the "_DSD (Device
+[5] http://www.uefi.org/acpi
+    please see the link for the "_DSD (Device
     Specific Data) Implementation Guide"
 
-[6] Kernel code for the unified device property interface can be found in
+[6] Kernel code for the unified device
+    property interface can be found in
     include/linux/property.h and drivers/base/property.c.
 
 
 Authors
 -------
-Al Stone <al.stone@linaro.org>
-Graeme Gregory <graeme.gregory@linaro.org>
-Hanjun Guo <hanjun.guo@linaro.org>
+- Al Stone <al.stone@linaro.org>
+- Graeme Gregory <graeme.gregory@linaro.org>
+- Hanjun Guo <hanjun.guo@linaro.org>
 
-Grant Likely <grant.likely@linaro.org>, for the "Why ACPI on ARM?" section
+- Grant Likely <grant.likely@linaro.org>, for the "Why ACPI on ARM?" section

Documentation/arm64/booting.txt → Documentation/arm64/booting.rst

-			Booting AArch64 Linux
-			=====================
+=====================
+Booting AArch64 Linux
+=====================
 
 Author: Will Deacon <will.deacon@arm.com>
+
 Date  : 07 September 2012
 
 This document is based on the ARM booting document by Russell King and
@@ -12,7 +14,7 @@ The AArch64 exception model is made up of a number of exception levels
 counterpart.  EL2 is the hypervisor level and exists only in non-secure
 mode. EL3 is the highest priority level and exists only in secure mode.
 
-For the purposes of this document, we will use the term `boot loader'
+For the purposes of this document, we will use the term `boot loader`
 simply to define all software that executes on the CPU(s) before control
 is passed to the Linux kernel.  This may include secure monitor and
 hypervisor code, or it may just be a handful of instructions for
@@ -70,7 +72,7 @@ Image target is available instead.
 
 Requirement: MANDATORY
 
-The decompressed kernel image contains a 64-byte header as follows:
+The decompressed kernel image contains a 64-byte header as follows::
 
   u32 code0;			/* Executable code */
   u32 code1;			/* Executable code */
@@ -103,19 +105,26 @@ Header notes:
 
 - The flags field (introduced in v3.17) is a little-endian 64-bit field
   composed as follows:
-  Bit 0:	Kernel endianness.  1 if BE, 0 if LE.
-  Bit 1-2:	Kernel Page size.
-			0 - Unspecified.
-			1 - 4K
-			2 - 16K
-			3 - 64K
-  Bit 3:	Kernel physical placement
-			0 - 2MB aligned base should be as close as possible
-			    to the base of DRAM, since memory below it is not
-			    accessible via the linear mapping
-			1 - 2MB aligned base may be anywhere in physical
-			    memory
-  Bits 4-63:	Reserved.
+
+  ============= ===============================================================
+  Bit 0		Kernel endianness.  1 if BE, 0 if LE.
+  Bit 1-2	Kernel Page size.
+
+			* 0 - Unspecified.
+			* 1 - 4K
+			* 2 - 16K
+			* 3 - 64K
+  Bit 3		Kernel physical placement
+
+			0
+			  2MB aligned base should be as close as possible
+			  to the base of DRAM, since memory below it is not
+			  accessible via the linear mapping
+			1
+			  2MB aligned base may be anywhere in physical
+			  memory
+  Bits 4-63	Reserved.
+  ============= ===============================================================
 
 - When image_size is zero, a bootloader should attempt to keep as much
   memory as possible free for use by the kernel immediately after the
@@ -147,19 +156,22 @@ Before jumping into the kernel, the following conditions must be met:
   corrupted by bogus network packets or disk data.  This will save
   you many hours of debug.
 
-- Primary CPU general-purpose register settings
-  x0 = physical address of device tree blob (dtb) in system RAM.
-  x1 = 0 (reserved for future use)
-  x2 = 0 (reserved for future use)
-  x3 = 0 (reserved for future use)
+- Primary CPU general-purpose register settings:
+
+    - x0 = physical address of device tree blob (dtb) in system RAM.
+    - x1 = 0 (reserved for future use)
+    - x2 = 0 (reserved for future use)
+    - x3 = 0 (reserved for future use)
 
 - CPU mode
+
   All forms of interrupts must be masked in PSTATE.DAIF (Debug, SError,
   IRQ and FIQ).
   The CPU must be in either EL2 (RECOMMENDED in order to have access to
   the virtualisation extensions) or non-secure EL1.
 
 - Caches, MMUs
+
   The MMU must be off.
   Instruction cache may be on or off.
   The address range corresponding to the loaded kernel image must be
@@ -172,18 +184,21 @@ Before jumping into the kernel, the following conditions must be met:
   operations (not recommended) must be configured and disabled.
 
 - Architected timers
+
   CNTFRQ must be programmed with the timer frequency and CNTVOFF must
   be programmed with a consistent value on all CPUs.  If entering the
   kernel at EL1, CNTHCTL_EL2 must have EL1PCTEN (bit 0) set where
   available.
 
 - Coherency
+
   All CPUs to be booted by the kernel must be part of the same coherency
   domain on entry to the kernel.  This may require IMPLEMENTATION DEFINED
   initialisation to enable the receiving of maintenance operations on
   each CPU.
 
 - System registers
+
   All writable architected system registers at the exception level where
   the kernel image will be entered must be initialised by software at a
   higher exception level to prevent execution in an UNKNOWN state.
@@ -195,28 +210,40 @@ Before jumping into the kernel, the following conditions must be met:
 
   For systems with a GICv3 interrupt controller to be used in v3 mode:
   - If EL3 is present:
-    ICC_SRE_EL3.Enable (bit 3) must be initialiased to 0b1.
-    ICC_SRE_EL3.SRE (bit 0) must be initialised to 0b1.
+
+      - ICC_SRE_EL3.Enable (bit 3) must be initialiased to 0b1.
+      - ICC_SRE_EL3.SRE (bit 0) must be initialised to 0b1.
+
   - If the kernel is entered at EL1:
-    ICC.SRE_EL2.Enable (bit 3) must be initialised to 0b1
-    ICC_SRE_EL2.SRE (bit 0) must be initialised to 0b1.
+
+      - ICC.SRE_EL2.Enable (bit 3) must be initialised to 0b1
+      - ICC_SRE_EL2.SRE (bit 0) must be initialised to 0b1.
+
   - The DT or ACPI tables must describe a GICv3 interrupt controller.
 
   For systems with a GICv3 interrupt controller to be used in
   compatibility (v2) mode:
+
   - If EL3 is present:
-    ICC_SRE_EL3.SRE (bit 0) must be initialised to 0b0.
+
+      ICC_SRE_EL3.SRE (bit 0) must be initialised to 0b0.
+
   - If the kernel is entered at EL1:
-    ICC_SRE_EL2.SRE (bit 0) must be initialised to 0b0.
+
+      ICC_SRE_EL2.SRE (bit 0) must be initialised to 0b0.
+
   - The DT or ACPI tables must describe a GICv2 interrupt controller.
 
   For CPUs with pointer authentication functionality:
   - If EL3 is present:
-    SCR_EL3.APK (bit 16) must be initialised to 0b1
-    SCR_EL3.API (bit 17) must be initialised to 0b1
+
+    - SCR_EL3.APK (bit 16) must be initialised to 0b1
+    - SCR_EL3.API (bit 17) must be initialised to 0b1
+
   - If the kernel is entered at EL1:
-    HCR_EL2.APK (bit 40) must be initialised to 0b1
-    HCR_EL2.API (bit 41) must be initialised to 0b1
+
+    - HCR_EL2.APK (bit 40) must be initialised to 0b1
+    - HCR_EL2.API (bit 41) must be initialised to 0b1
 
 The requirements described above for CPU mode, caches, MMUs, architected
 timers, coherency and system registers apply to all CPUs.  All CPUs must

Documentation/arm64/cpu-feature-registers.txt → Documentation/arm64/cpu-feature-registers.rst

-		ARM64 CPU Feature Registers
-		===========================
+===========================
+ARM64 CPU Feature Registers
+===========================
 
 Author: Suzuki K Poulose <suzuki.poulose@arm.com>
 
@@ -9,7 +10,7 @@ registers to userspace. The availability of this ABI is advertised
 via the HWCAP_CPUID in HWCAPs.
 
 1. Motivation
----------------
+-------------
 
 The ARM architecture defines a set of feature registers, which describe
 the capabilities of the CPU/system. Access to these system registers is
@@ -33,9 +34,10 @@ there are some issues with their usage.
 
 
 2. Requirements
------------------
+---------------
+
+ a) Safety:
 
- a) Safety :
     Applications should be able to use the information provided by the
     infrastructure to run safely across the system. This has greater
     implications on a system with heterogeneous CPUs.
@@ -47,7 +49,8 @@ there are some issues with their usage.
     Otherwise an application could crash when scheduled on the CPU
     which doesn't support CRC32.
 
- b) Security :
+ b) Security:
+
     Applications should only be able to receive information that is
     relevant to the normal operation in userspace. Hence, some of the
     fields are masked out(i.e, made invisible) and their values are set to
@@ -58,10 +61,12 @@ there are some issues with their usage.
     (even when the CPU provides it).
 
  c) Implementation Defined Features
+
     The infrastructure doesn't expose any register which is
     IMPLEMENTATION DEFINED as per ARMv8-A Architecture.
 
- d) CPU Identification :
+ d) CPU Identification:
+
     MIDR_EL1 is exposed to help identify the processor. On a
     heterogeneous system, this could be racy (just like getcpu()). The
     process could be migrated to another CPU by the time it uses the
@@ -70,7 +75,7 @@ there are some issues with their usage.
     currently executing on. The REVIDR is not exposed due to this
     constraint, as REVIDR makes sense only in conjunction with the
     MIDR. Alternately, MIDR_EL1 and REVIDR_EL1 are exposed via sysfs
-    at:
+    at::
 
 	/sys/devices/system/cpu/cpu$ID/regs/identification/
 	                                              \- midr
@@ -85,7 +90,8 @@ exception and ends up in SIGILL being delivered to the process.
 The infrastructure hooks into the exception handler and emulates the
 operation if the source belongs to the supported system register space.
 
-The infrastructure emulates only the following system register space:
+The infrastructure emulates only the following system register space::
+
 	Op0=3, Op1=0, CRn=0, CRm=0,4,5,6,7
 
 (See Table C5-6 'System instruction encodings for non-Debug System
@@ -107,73 +113,76 @@ infrastructure:
 -------------------------------------------
 
   1) ID_AA64ISAR0_EL1 - Instruction Set Attribute Register 0
-     x--------------------------------------------------x
+
+     +------------------------------+---------+---------+
      | Name                         |  bits   | visible |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | TS                           | [55-52] |    y    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | FHM                          | [51-48] |    y    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | DP                           | [47-44] |    y    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | SM4                          | [43-40] |    y    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | SM3                          | [39-36] |    y    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | SHA3                         | [35-32] |    y    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | RDM                          | [31-28] |    y    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | ATOMICS                      | [23-20] |    y    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | CRC32                        | [19-16] |    y    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | SHA2                         | [15-12] |    y    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | SHA1                         | [11-8]  |    y    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | AES                          | [7-4]   |    y    |
-     x--------------------------------------------------x
+     +------------------------------+---------+---------+
 
 
   2) ID_AA64PFR0_EL1 - Processor Feature Register 0
-     x--------------------------------------------------x
+
+     +------------------------------+---------+---------+
      | Name                         |  bits   | visible |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | DIT                          | [51-48] |    y    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | SVE                          | [35-32] |    y    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | GIC                          | [27-24] |    n    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | AdvSIMD                      | [23-20] |    y    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | FP                           | [19-16] |    y    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | EL3                          | [15-12] |    n    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | EL2                          | [11-8]  |    n    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | EL1                          | [7-4]   |    n    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | EL0                          | [3-0]   |    n    |
-     x--------------------------------------------------x
+     +------------------------------+---------+---------+
 
 
   3) MIDR_EL1 - Main ID Register
-     x--------------------------------------------------x
+
+     +------------------------------+---------+---------+
      | Name                         |  bits   | visible |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | Implementer                  | [31-24] |    y    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | Variant                      | [23-20] |    y    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | Architecture                 | [19-16] |    y    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | PartNum                      | [15-4]  |    y    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | Revision                     | [3-0]   |    y    |
-     x--------------------------------------------------x
+     +------------------------------+---------+---------+
 
    NOTE: The 'visible' fields of MIDR_EL1 will contain the value
    as available on the CPU where it is fetched and is not a system
@@ -181,90 +190,92 @@ infrastructure:
 
   4) ID_AA64ISAR1_EL1 - Instruction set attribute register 1
 
-     x--------------------------------------------------x
+     +------------------------------+---------+---------+
      | Name                         |  bits   | visible |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | GPI                          | [31-28] |    y    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | GPA                          | [27-24] |    y    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | LRCPC                        | [23-20] |    y    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | FCMA                         | [19-16] |    y    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | JSCVT                        | [15-12] |    y    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | API                          | [11-8]  |    y    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | APA                          | [7-4]   |    y    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | DPB                          | [3-0]   |    y    |
-     x--------------------------------------------------x
+     +------------------------------+---------+---------+
 
   5) ID_AA64MMFR2_EL1 - Memory model feature register 2
 
-     x--------------------------------------------------x
+     +------------------------------+---------+---------+
      | Name                         |  bits   | visible |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | AT                           | [35-32] |    y    |
-     x--------------------------------------------------x
+     +------------------------------+---------+---------+
 
   6) ID_AA64ZFR0_EL1 - SVE feature ID register 0
 
-     x--------------------------------------------------x
+     +------------------------------+---------+---------+
      | Name                         |  bits   | visible |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | SM4                          | [43-40] |    y    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | SHA3                         | [35-32] |    y    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | BitPerm                      | [19-16] |    y    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | AES                          | [7-4]   |    y    |
-     |--------------------------------------------------|
+     +------------------------------+---------+---------+
      | SVEVer                       | [3-0]   |    y    |
-     x--------------------------------------------------x
+     +------------------------------+---------+---------+
 
 Appendix I: Example
----------------------------
-
-/*
- * Sample program to demonstrate the MRS emulation ABI.
- *
- * Copyright (C) 2015-2016, ARM Ltd
- *
- * Author: Suzuki K Poulose <suzuki.poulose@arm.com>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2 as
- * published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2 as
- * published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- */
-
-#include <asm/hwcap.h>
-#include <stdio.h>
-#include <sys/auxv.h>
-
-#define get_cpu_ftr(id) ({					\
+-------------------
+
+::
+
+  /*
+   * Sample program to demonstrate the MRS emulation ABI.
+   *
+   * Copyright (C) 2015-2016, ARM Ltd
+   *
+   * Author: Suzuki K Poulose <suzuki.poulose@arm.com>
+   *
+   * This program is free software; you can redistribute it and/or modify
+   * it under the terms of the GNU General Public License version 2 as
+   * published by the Free Software Foundation.
+   *
+   * This program is distributed in the hope that it will be useful,
+   * but WITHOUT ANY WARRANTY; without even the implied warranty of
+   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   * GNU General Public License for more details.
+   * This program is free software; you can redistribute it and/or modify
+   * it under the terms of the GNU General Public License version 2 as
+   * published by the Free Software Foundation.
+   *
+   * This program is distributed in the hope that it will be useful,
+   * but WITHOUT ANY WARRANTY; without even the implied warranty of
+   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   * GNU General Public License for more details.
+   */
+
+  #include <asm/hwcap.h>
+  #include <stdio.h>
+  #include <sys/auxv.h>
+
+  #define get_cpu_ftr(id) ({					\
 		unsigned long __val;				\
 		asm("mrs %0, "#id : "=r" (__val));		\
 		printf("%-20s: 0x%016lx\n", #id, __val);	\
 	})
 
-int main(void)
-{
+  int main(void)
+  {
 
 	if (!(getauxval(AT_HWCAP) & HWCAP_CPUID)) {
 		fputs("CPUID registers unavailable\n", stderr);
@@ -284,13 +295,10 @@ int main(void)
 	get_cpu_ftr(MPIDR_EL1);
 	get_cpu_ftr(REVIDR_EL1);
 
-#if 0
+  #if 0
 	/* Unexposed register access causes SIGILL */
 	get_cpu_ftr(ID_MMFR0_EL1);
-#endif
+  #endif
 
 	return 0;
-}
-
-
-
+  }

Documentation/arm64/elf_hwcaps.txt → Documentation/arm64/elf_hwcaps.rst

+================
 ARM64 ELF hwcaps
 ================
 
@@ -15,16 +16,16 @@ of flags called hwcaps, exposed in the auxilliary vector.
 
 Userspace software can test for features by acquiring the AT_HWCAP or
 AT_HWCAP2 entry of the auxiliary vector, and testing whether the relevant
-flags are set, e.g.
+flags are set, e.g.::
 
-bool floating_point_is_present(void)
-{
-	unsigned long hwcaps = getauxval(AT_HWCAP);
-	if (hwcaps & HWCAP_FP)
-		return true;
+	bool floating_point_is_present(void)
+	{
+		unsigned long hwcaps = getauxval(AT_HWCAP);
+		if (hwcaps & HWCAP_FP)
+			return true;
 
-	return false;
-}
+		return false;
+	}
 
 Where software relies on a feature described by a hwcap, it should check
 the relevant hwcap flag to verify that the feature is present before
@@ -45,7 +46,7 @@ userspace code at EL0. These hwcaps are defined in terms of ID register
 fields, and should be interpreted with reference to the definition of
 these fields in the ARM Architecture Reference Manual (ARM ARM).
 
-Such hwcaps are described below in the form:
+Such hwcaps are described below in the form::
 
     Functionality implied by idreg.field == val.
 
@@ -64,75 +65,58 @@ reference to ID registers, and may refer to other documentation.
 ---------------------------------
 
 HWCAP_FP
-
     Functionality implied by ID_AA64PFR0_EL1.FP == 0b0000.
 
 HWCAP_ASIMD
-
     Functionality implied by ID_AA64PFR0_EL1.AdvSIMD == 0b0000.
 
 HWCAP_EVTSTRM
-
     The generic timer is configured to generate events at a frequency of
     approximately 100KHz.
 
 HWCAP_AES
-
     Functionality implied by ID_AA64ISAR0_EL1.AES == 0b0001.
 
 HWCAP_PMULL
-
     Functionality implied by ID_AA64ISAR0_EL1.AES == 0b0010.
 
 HWCAP_SHA1
-
     Functionality implied by ID_AA64ISAR0_EL1.SHA1 == 0b0001.
 
 HWCAP_SHA2
-
     Functionality implied by ID_AA64ISAR0_EL1.SHA2 == 0b0001.
 
 HWCAP_CRC32
-
     Functionality implied by ID_AA64ISAR0_EL1.CRC32 == 0b0001.
 
 HWCAP_ATOMICS
-
     Functionality implied by ID_AA64ISAR0_EL1.Atomic == 0b0010.
 
 HWCAP_FPHP
-
     Functionality implied by ID_AA64PFR0_EL1.FP == 0b0001.
 
 HWCAP_ASIMDHP
-
     Functionality implied by ID_AA64PFR0_EL1.AdvSIMD == 0b0001.
 
 HWCAP_CPUID
-
     EL0 access to certain ID registers is available, to the extent
-    described by Documentation/arm64/cpu-feature-registers.txt.
+    described by Documentation/arm64/cpu-feature-registers.rst.
 
     These ID registers may imply the availability of features.
 
 HWCAP_ASIMDRDM
-
     Functionality implied by ID_AA64ISAR0_EL1.RDM == 0b0001.
 
 HWCAP_JSCVT
-
     Functionality implied by ID_AA64ISAR1_EL1.JSCVT == 0b0001.
 
 HWCAP_FCMA
-
     Functionality implied by ID_AA64ISAR1_EL1.FCMA == 0b0001.
 
 HWCAP_LRCPC
-
     Functionality implied by ID_AA64ISAR1_EL1.LRCPC == 0b0001.
 
 HWCAP_DCPOP
-
     Functionality implied by ID_AA64ISAR1_EL1.DPB == 0b0001.
 
 HWCAP2_DCPODP
@@ -140,27 +124,21 @@ HWCAP2_DCPODP
     Functionality implied by ID_AA64ISAR1_EL1.DPB == 0b0010.
 
 HWCAP_SHA3
-
     Functionality implied by ID_AA64ISAR0_EL1.SHA3 == 0b0001.
 
 HWCAP_SM3
-
     Functionality implied by ID_AA64ISAR0_EL1.SM3 == 0b0001.
 
 HWCAP_SM4
-
     Functionality implied by ID_AA64ISAR0_EL1.SM4 == 0b0001.
 
 HWCAP_ASIMDDP
-
     Functionality implied by ID_AA64ISAR0_EL1.DP == 0b0001.
 
 HWCAP_SHA512
-
     Functionality implied by ID_AA64ISAR0_EL1.SHA2 == 0b0010.
 
 HWCAP_SVE
-
     Functionality implied by ID_AA64PFR0_EL1.SVE == 0b0001.
 
 HWCAP2_SVE2
@@ -188,40 +166,32 @@ HWCAP2_SVESM4
     Functionality implied by ID_AA64ZFR0_EL1.SM4 == 0b0001.
 
 HWCAP_ASIMDFHM
-
    Functionality implied by ID_AA64ISAR0_EL1.FHM == 0b0001.
 
 HWCAP_DIT
-
     Functionality implied by ID_AA64PFR0_EL1.DIT == 0b0001.
 
 HWCAP_USCAT
-
     Functionality implied by ID_AA64MMFR2_EL1.AT == 0b0001.
 
 HWCAP_ILRCPC
-
     Functionality implied by ID_AA64ISAR1_EL1.LRCPC == 0b0010.
 
 HWCAP_FLAGM
-
     Functionality implied by ID_AA64ISAR0_EL1.TS == 0b0001.
 
 HWCAP_SSBS
-
     Functionality implied by ID_AA64PFR1_EL1.SSBS == 0b0010.
 
 HWCAP_PACA
-
     Functionality implied by ID_AA64ISAR1_EL1.APA == 0b0001 or
     ID_AA64ISAR1_EL1.API == 0b0001, as described by
-    Documentation/arm64/pointer-authentication.txt.
+    Documentation/arm64/pointer-authentication.rst.
 
 HWCAP_PACG
-
     Functionality implied by ID_AA64ISAR1_EL1.GPA == 0b0001 or
     ID_AA64ISAR1_EL1.GPI == 0b0001, as described by
-    Documentation/arm64/pointer-authentication.txt.
+    Documentation/arm64/pointer-authentication.rst.
 
 
 4. Unused AT_HWCAP bits

Documentation/arm64/hugetlbpage.txt → Documentation/arm64/hugetlbpage.rst

+====================
 HugeTLBpage on ARM64
 ====================
 
@@ -31,8 +32,10 @@ and level of the page table.
 
 The following hugepage sizes are supported -
 
-         CONT PTE    PMD    CONT PMD    PUD
-         --------    ---    --------    ---
+  ====== ========   ====    ========    ===
+  -      CONT PTE    PMD    CONT PMD    PUD
+  ====== ========   ====    ========    ===
   4K:         64K     2M         32M     1G
   16K:         2M    32M          1G
   64K:         2M   512M         16G
+  ====== ========   ====    ========    ===

Documentation/arm64/index.rst

+:orphan:
+
+==================
+ARM64 Architecture
+==================
+
+.. toctree::
+    :maxdepth: 1
+
+    acpi_object_usage
+    arm-acpi
+    booting
+    cpu-feature-registers
+    elf_hwcaps
+    hugetlbpage
+    legacy_instructions
+    memory
+    pointer-authentication
+    silicon-errata
+    sve
+    tagged-pointers
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`

Documentation/arm64/legacy_instructions.txt → Documentation/arm64/legacy_instructions.rst

+===================
+Legacy instructions
+===================
+
 The arm64 port of the Linux kernel provides infrastructure to support
 emulation of instructions which have been deprecated, or obsoleted in
 the architecture. The infrastructure code uses undefined instruction
@@ -9,19 +13,22 @@ The emulation mode can be controlled by writing to sysctl nodes
 behaviours and the corresponding values of the sysctl nodes -
 
 * Undef
-  Value: 0
+    Value: 0
+
   Generates undefined instruction abort. Default for instructions that
   have been obsoleted in the architecture, e.g., SWP
 
 * Emulate
-  Value: 1
+    Value: 1
+
   Uses software emulation. To aid migration of software, in this mode
   usage of emulated instruction is traced as well as rate limited
   warnings are issued. This is the default for deprecated
   instructions, .e.g., CP15 barriers
 
 * Hardware Execution
-  Value: 2
+    Value: 2
+
   Although marked as deprecated, some implementations may support the
   enabling/disabling of hardware support for the execution of these
   instructions. Using hardware execution generally provides better
@@ -38,20 +45,24 @@ individual instruction notes for further information.
 Supported legacy instructions
 -----------------------------
 * SWP{B}
-Node: /proc/sys/abi/swp
-Status: Obsolete
-Default: Undef (0)
+
+:Node: /proc/sys/abi/swp
+:Status: Obsolete
+:Default: Undef (0)
 
 * CP15 Barriers
-Node: /proc/sys/abi/cp15_barrier
-Status: Deprecated
-Default: Emulate (1)
+
+:Node: /proc/sys/abi/cp15_barrier
+:Status: Deprecated
+:Default: Emulate (1)
 
 * SETEND
-Node: /proc/sys/abi/setend
-Status: Deprecated
-Default: Emulate (1)*
-Note: All the cpus on the system must have mixed endian support at EL0
-for this feature to be enabled. If a new CPU - which doesn't support mixed
-endian - is hotplugged in after this feature has been enabled, there could
-be unexpected results in the application.
+
+:Node: /proc/sys/abi/setend
+:Status: Deprecated
+:Default: Emulate (1)*
+
+  Note: All the cpus on the system must have mixed endian support at EL0
+  for this feature to be enabled. If a new CPU - which doesn't support mixed
+  endian - is hotplugged in after this feature has been enabled, there could
+  be unexpected results in the application.

Documentation/arm64/memory.txt → Documentation/arm64/memory.rst

-		     Memory Layout on AArch64 Linux
-		     ==============================
+==============================
+Memory Layout on AArch64 Linux
+==============================
 
 Author: Catalin Marinas <catalin.marinas@arm.com>
 
@@ -21,69 +22,69 @@ The swapper_pg_dir address is written to TTBR1 and never written to
 TTBR0.
 
 
-AArch64 Linux memory layout with 4KB pages + 3 levels:
+AArch64 Linux memory layout with 4KB pages + 3 levels::
 
-Start			End			Size		Use
------------------------------------------------------------------------
-0000000000000000	0000007fffffffff	 512GB		user
-ffffff8000000000	ffffffffffffffff	 512GB		kernel
+  Start			End			Size		Use
+  -----------------------------------------------------------------------
+  0000000000000000	0000007fffffffff	 512GB		user
+  ffffff8000000000	ffffffffffffffff	 512GB		kernel
 
 
-AArch64 Linux memory layout with 4KB pages + 4 levels:
+AArch64 Linux memory layout with 4KB pages + 4 levels::
 
-Start			End			Size		Use
------------------------------------------------------------------------
-0000000000000000	0000ffffffffffff	 256TB		user
-ffff000000000000	ffffffffffffffff	 256TB		kernel
+  Start			End			Size		Use
+  -----------------------------------------------------------------------
+  0000000000000000	0000ffffffffffff	 256TB		user
+  ffff000000000000	ffffffffffffffff	 256TB		kernel
 
 
-AArch64 Linux memory layout with 64KB pages + 2 levels:
+AArch64 Linux memory layout with 64KB pages + 2 levels::
 
-Start			End			Size		Use
------------------------------------------------------------------------
-0000000000000000	000003ffffffffff	   4TB		user
-fffffc0000000000	ffffffffffffffff	   4TB		kernel
+  Start			End			Size		Use
+  -----------------------------------------------------------------------
+  0000000000000000	000003ffffffffff	   4TB		user
+  fffffc0000000000	ffffffffffffffff	   4TB		kernel
 
 
-AArch64 Linux memory layout with 64KB pages + 3 levels:
+AArch64 Linux memory layout with 64KB pages + 3 levels::
 
-Start			End			Size		Use
------------------------------------------------------------------------
-0000000000000000	0000ffffffffffff	 256TB		user
-ffff000000000000	ffffffffffffffff	 256TB		kernel
+  Start			End			Size		Use
+  -----------------------------------------------------------------------
+  0000000000000000	0000ffffffffffff	 256TB		user
+  ffff000000000000	ffffffffffffffff	 256TB		kernel
 
 
 For details of the virtual kernel memory layout please see the kernel
 booting log.
 
 
-Translation table lookup with 4KB pages:
-
-+--------+--------+--------+--------+--------+--------+--------+--------+
-|63    56|55    48|47    40|39    32|31    24|23    16|15     8|7      0|
-+--------+--------+--------+--------+--------+--------+--------+--------+
- |                 |         |         |         |         |
- |                 |         |         |         |         v
- |                 |         |         |         |   [11:0]  in-page offset
- |                 |         |         |         +-> [20:12] L3 index
- |                 |         |         +-----------> [29:21] L2 index
- |                 |         +---------------------> [38:30] L1 index
- |                 +-------------------------------> [47:39] L0 index
- +-------------------------------------------------> [63] TTBR0/1
-
-
-Translation table lookup with 64KB pages:
-
-+--------+--------+--------+--------+--------+--------+--------+--------+
-|63    56|55    48|47    40|39    32|31    24|23    16|15     8|7      0|
-+--------+--------+--------+--------+--------+--------+--------+--------+
- |                 |    |               |              |
- |                 |    |               |              v
- |                 |    |               |            [15:0]  in-page offset
- |                 |    |               +----------> [28:16] L3 index
- |                 |    +--------------------------> [41:29] L2 index
- |                 +-------------------------------> [47:42] L1 index
- +-------------------------------------------------> [63] TTBR0/1
+Translation table lookup with 4KB pages::
+
+  +--------+--------+--------+--------+--------+--------+--------+--------+
+  |63    56|55    48|47    40|39    32|31    24|23    16|15     8|7      0|
+  +--------+--------+--------+--------+--------+--------+--------+--------+
+   |                 |         |         |         |         |
+   |                 |         |         |         |         v
+   |                 |         |         |         |   [11:0]  in-page offset
+   |                 |         |         |         +-> [20:12] L3 index
+   |                 |         |         +-----------> [29:21] L2 index
+   |                 |         +---------------------> [38:30] L1 index
+   |                 +-------------------------------> [47:39] L0 index
+   +-------------------------------------------------> [63] TTBR0/1
+
+
+Translation table lookup with 64KB pages::
+
+  +--------+--------+--------+--------+--------+--------+--------+--------+
+  |63    56|55    48|47    40|39    32|31    24|23    16|15     8|7      0|
+  +--------+--------+--------+--------+--------+--------+--------+--------+
+   |                 |    |               |              |
+   |                 |    |               |              v
+   |                 |    |               |            [15:0]  in-page offset
+   |                 |    |               +----------> [28:16] L3 index
+   |                 |    +--------------------------> [41:29] L2 index
+   |                 +-------------------------------> [47:42] L1 index
+   +-------------------------------------------------> [63] TTBR0/1
 
 
 When using KVM without the Virtualization Host Extensions, the

Documentation/arm64/pointer-authentication.txt → Documentation/arm64/pointer-authentication.rst

+=======================================
 Pointer authentication in AArch64 Linux
 =======================================
 
 Author: Mark Rutland <mark.rutland@arm.com>
+
 Date: 2017-07-19
 
 This document briefly describes the provision of pointer authentication

Documentation/arm64/silicon-errata.txt → Documentation/arm64/silicon-errata.rst

-                Silicon Errata and Software Workarounds
-                =======================================
+=======================================
+Silicon Errata and Software Workarounds
+=======================================
 
 Author: Will Deacon <will.deacon@arm.com>
+
 Date  : 27 November 2015
 
 It is an unfortunate fact of life that hardware is often produced with
@@ -9,11 +11,13 @@ so-called "errata", which can cause it to deviate from the architecture
 under specific circumstances.  For hardware produced by ARM, these
 errata are broadly classified into the following categories:
 
-  Category A: A critical error without a viable workaround.
-  Category B: A significant or critical error with an acceptable
+  ==========  ========================================================
+  Category A  A critical error without a viable workaround.
+  Category B  A significant or critical error with an acceptable
               workaround.
-  Category C: A minor error that is not expected to occur under normal
+  Category C  A minor error that is not expected to occur under normal
               operation.
+  ==========  ========================================================
 
 For more information, consult one of the "Software Developers Errata
 Notice" documents available on infocenter.arm.com (registration
@@ -42,47 +46,86 @@ file acts as a registry of software workarounds in the Linux Kernel and
 will be updated when new workarounds are committed and backported to
 stable kernels.
 
-| Implementor    | Component       | Erratum ID      | Kconfig                     |
 +----------------+-----------------+-----------------+-----------------------------+
+| Implementor    | Component       | Erratum ID      | Kconfig                     |
++================+=================+=================+=============================+
 | Allwinner      | A64/R18         | UNKNOWN1        | SUN50I_ERRATUM_UNKNOWN1     |
-|                |                 |                 |                             |
++----------------+-----------------+-----------------+-----------------------------+
++----------------+-----------------+-----------------+-----------------------------+
 | ARM            | Cortex-A53      | #826319         | ARM64_ERRATUM_826319        |
++----------------+-----------------+-----------------+-----------------------------+
 | ARM            | Cortex-A53      | #827319         | ARM64_ERRATUM_827319        |
++----------------+-----------------+-----------------+-----------------------------+
 | ARM            | Cortex-A53      | #824069         | ARM64_ERRATUM_824069        |
++----------------+-----------------+-----------------+-----------------------------+
 | ARM            | Cortex-A53      | #819472         | ARM64_ERRATUM_819472        |
++----------------+-----------------+-----------------+-----------------------------+
 | ARM            | Cortex-A53      | #845719         | ARM64_ERRATUM_845719        |
++----------------+-----------------+-----------------+-----------------------------+
 | ARM            | Cortex-A53      | #843419         | ARM64_ERRATUM_843419        |
++----------------+-----------------+-----------------+-----------------------------+
 | ARM            | Cortex-A57      | #832075         | ARM64_ERRATUM_832075        |
++----------------+-----------------+-----------------+-----------------------------+
 | ARM            | Cortex-A57      | #852523         | N/A                         |
++----------------+-----------------+-----------------+-----------------------------+
 | ARM            | Cortex-A57      | #834220         | ARM64_ERRATUM_834220        |
++----------------+-----------------+-----------------+-----------------------------+
 | ARM            | Cortex-A72      | #853709         | N/A                         |
++----------------+-----------------+-----------------+-----------------------------+
 | ARM            | Cortex-A73      | #858921         | ARM64_ERRATUM_858921        |
++----------------+-----------------+-----------------+-----------------------------+
 | ARM            | Cortex-A55      | #1024718        | ARM64_ERRATUM_1024718       |
++----------------+-----------------+-----------------+-----------------------------+
 | ARM            | Cortex-A76      | #1188873,1418040| ARM64_ERRATUM_1418040       |
++----------------+-----------------+-----------------+-----------------------------+
 | ARM            | Cortex-A76      | #1165522        | ARM64_ERRATUM_1165522       |
++----------------+-----------------+-----------------+-----------------------------+
 | ARM            | Cortex-A76      | #1286807        | ARM64_ERRATUM_1286807       |
++----------------+-----------------+-----------------+-----------------------------+
 | ARM            | Cortex-A76      | #1463225        | ARM64_ERRATUM_1463225       |
++----------------+-----------------+-----------------+-----------------------------+
 | ARM            | Neoverse-N1     | #1188873,1418040| ARM64_ERRATUM_1418040       |
++----------------+-----------------+-----------------+-----------------------------+
 | ARM            | MMU-500         | #841119,826419  | N/A                         |
-|                |                 |                 |                             |
++----------------+-----------------+-----------------+-----------------------------+
++----------------+-----------------+-----------------+-----------------------------+
 | Cavium         | ThunderX ITS    | #22375,24313    | CAVIUM_ERRATUM_22375        |
++----------------+-----------------+-----------------+-----------------------------+
 | Cavium         | ThunderX ITS    | #23144          | CAVIUM_ERRATUM_23144        |
++----------------+-----------------+-----------------+-----------------------------+
 | Cavium         | ThunderX GICv3  | #23154          | CAVIUM_ERRATUM_23154        |
++----------------+-----------------+-----------------+-----------------------------+
 | Cavium         | ThunderX Core   | #27456          | CAVIUM_ERRATUM_27456        |
++----------------+-----------------+-----------------+-----------------------------+
 | Cavium         | ThunderX Core   | #30115          | CAVIUM_ERRATUM_30115        |
++----------------+-----------------+-----------------+-----------------------------+
 | Cavium         | ThunderX SMMUv2 | #27704          | N/A                         |
++----------------+-----------------+-----------------+-----------------------------+
 | Cavium         | ThunderX2 SMMUv3| #74             | N/A                         |
++----------------+-----------------+-----------------+-----------------------------+
 | Cavium         | ThunderX2 SMMUv3| #126            | N/A                         |
-|                |                 |                 |                             |
++----------------+-----------------+-----------------+-----------------------------+
++----------------+-----------------+-----------------+-----------------------------+
 | Freescale/NXP  | LS2080A/LS1043A | A-008585        | FSL_ERRATUM_A008585         |
-|                |                 |                 |                             |
++----------------+-----------------+-----------------+-----------------------------+
++----------------+-----------------+-----------------+-----------------------------+
 | Hisilicon      | Hip0{5,6,7}     | #161010101      | HISILICON_ERRATUM_161010101 |
++----------------+-----------------+-----------------+-----------------------------+
 | Hisilicon      | Hip0{6,7}       | #161010701      | N/A                         |
++----------------+-----------------+-----------------+-----------------------------+
 | Hisilicon      | Hip07           | #161600802      | HISILICON_ERRATUM_161600802 |
++----------------+-----------------+-----------------+-----------------------------+
 | Hisilicon      | Hip08 SMMU PMCG | #162001800      | N/A                         |
-|                |                 |                 |                             |
++----------------+-----------------+-----------------+-----------------------------+
++----------------+-----------------+-----------------+-----------------------------+
 | Qualcomm Tech. | Kryo/Falkor v1  | E1003           | QCOM_FALKOR_ERRATUM_1003    |
++----------------+-----------------+-----------------+-----------------------------+
 | Qualcomm Tech. | Falkor v1       | E1009           | QCOM_FALKOR_ERRATUM_1009    |
++----------------+-----------------+-----------------+-----------------------------+
 | Qualcomm Tech. | QDF2400 ITS     | E0065           | QCOM_QDF2400_ERRATUM_0065   |
++----------------+-----------------+-----------------+-----------------------------+
 | Qualcomm Tech. | Falkor v{1,2}   | E1041           | QCOM_FALKOR_ERRATUM_1041    |
++----------------+-----------------+-----------------+-----------------------------+
++----------------+-----------------+-----------------+-----------------------------+
 | Fujitsu        | A64FX           | E#010001        | FUJITSU_ERRATUM_010001      |
++----------------+-----------------+-----------------+-----------------------------+

Documentation/arm64/sve.txt → Documentation/arm64/sve.rst

-            Scalable Vector Extension support for AArch64 Linux
-            ===================================================
+===================================================
+Scalable Vector Extension support for AArch64 Linux
+===================================================
 
 Author: Dave Martin <Dave.Martin@arm.com>
+
 Date:   4 August 2017
 
 This document outlines briefly the interface provided to userspace by Linux in
@@ -426,7 +428,7 @@ In A64 state, SVE adds the following:
 
 * FPSR and FPCR are retained from ARMv8-A, and interact with SVE floating-point
   operations in a similar way to the way in which they interact with ARMv8
-  floating-point operations.
+  floating-point operations::
 
          8VL-1                       128               0  bit index
         +----          ////            -----------------+
@@ -483,6 +485,8 @@ ARMv8-A defines the following floating-point / SIMD register state:
 * 32 128-bit vector registers V0..V31
 * 2 32-bit status/control registers FPSR, FPCR
 
+::
+
          127           0  bit index
         +---------------+
      V0 |               |
@@ -517,7 +521,7 @@ References
 [2] arch/arm64/include/uapi/asm/ptrace.h
     AArch64 Linux ptrace ABI definitions
 
-[3] Documentation/arm64/cpu-feature-registers.txt
+[3] Documentation/arm64/cpu-feature-registers.rst
 
 [4] ARM IHI0055C
     http://infocenter.arm.com/help/topic/com.arm.doc.ihi0055c/IHI0055C_beta_aapcs64.pdf

Documentation/arm64/tagged-pointers.txt → Documentation/arm64/tagged-pointers.rst

-		Tagged virtual addresses in AArch64 Linux
-		=========================================
+=========================================
+Tagged virtual addresses in AArch64 Linux
+=========================================
 
 Author: Will Deacon <will.deacon@arm.com>
+
 Date  : 12 June 2013
 
 This document briefly describes the provision of tagged virtual

Documentation/translations/zh_CN/arm64/booting.txt

-Chinese translated version of Documentation/arm64/booting.txt
+Chinese translated version of Documentation/arm64/booting.rst
 
 If you have any comment or update to the content, please contact the
 original document maintainer directly.  However, if you have a problem
@@ -10,7 +10,7 @@ M:	Will Deacon <will.deacon@arm.com>
 zh_CN:	Fu Wei <wefu@redhat.com>
 C:	55f058e7574c3615dea4615573a19bdb258696c6
 ---------------------------------------------------------------------
-Documentation/arm64/booting.txt 的中文翻译
+Documentation/arm64/booting.rst 的中文翻译
 
 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻

Documentation/translations/zh_CN/arm64/legacy_instructions.txt

-Chinese translated version of Documentation/arm64/legacy_instructions.txt
+Chinese translated version of Documentation/arm64/legacy_instructions.rst
 
 If you have any comment or update to the content, please contact the
 original document maintainer directly.  However, if you have a problem
@@ -10,7 +10,7 @@ Maintainer: Punit Agrawal <punit.agrawal@arm.com>
             Suzuki K. Poulose <suzuki.poulose@arm.com>
 Chinese maintainer: Fu Wei <wefu@redhat.com>
 ---------------------------------------------------------------------
-Documentation/arm64/legacy_instructions.txt 的中文翻译
+Documentation/arm64/legacy_instructions.rst 的中文翻译
 
 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻

Documentation/translations/zh_CN/arm64/memory.txt

-Chinese translated version of Documentation/arm64/memory.txt
+Chinese translated version of Documentation/arm64/memory.rst
 
 If you have any comment or update to the content, please contact the
 original document maintainer directly.  However, if you have a problem
@@ -9,7 +9,7 @@ or if there is a problem with the translation.
 Maintainer: Catalin Marinas <catalin.marinas@arm.com>
 Chinese maintainer: Fu Wei <wefu@redhat.com>
 ---------------------------------------------------------------------
-Documentation/arm64/memory.txt 的中文翻译
+Documentation/arm64/memory.rst 的中文翻译
 
 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻

Documentation/translations/zh_CN/arm64/silicon-errata.txt

-Chinese translated version of Documentation/arm64/silicon-errata.txt
+Chinese translated version of Documentation/arm64/silicon-errata.rst
 
 If you have any comment or update to the content, please contact the
 original document maintainer directly.  However, if you have a problem
@@ -10,7 +10,7 @@ M:	Will Deacon <will.deacon@arm.com>
 zh_CN:	Fu Wei <wefu@redhat.com>
 C:	1926e54f115725a9248d0c4c65c22acaf94de4c4
 ---------------------------------------------------------------------
-Documentation/arm64/silicon-errata.txt 的中文翻译
+Documentation/arm64/silicon-errata.rst 的中文翻译
 
 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻

Documentation/translations/zh_CN/arm64/tagged-pointers.txt

-Chinese translated version of Documentation/arm64/tagged-pointers.txt
+Chinese translated version of Documentation/arm64/tagged-pointers.rst
 
 If you have any comment or update to the content, please contact the
 original document maintainer directly.  However, if you have a problem
@@ -9,7 +9,7 @@ or if there is a problem with the translation.
 Maintainer: Will Deacon <will.deacon@arm.com>
 Chinese maintainer: Fu Wei <wefu@redhat.com>
 ---------------------------------------------------------------------
-Documentation/arm64/tagged-pointers.txt 的中文翻译
+Documentation/arm64/tagged-pointers.rst 的中文翻译
 
 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻

Documentation/virtual/kvm/api.txt

@@ -2205,7 +2205,7 @@ max_vq.  This is the maximum vector length available to the guest on
 this vcpu, and determines which register slices are visible through
 this ioctl interface.
 
-(See Documentation/arm64/sve.txt for an explanation of the "vq"
+(See Documentation/arm64/sve.rst for an explanation of the "vq"
 nomenclature.)
 
 KVM_REG_ARM64_SVE_VLS is only accessible after KVM_ARM_VCPU_INIT.

arch/arm64/include/asm/efi.h

@@ -83,7 +83,7 @@ static inline unsigned long efi_get_max_fdt_addr(unsigned long dram_base)
  * guaranteed to cover the kernel Image.
  *
  * Since the EFI stub is part of the kernel Image, we can relax the
- * usual requirements in Documentation/arm64/booting.txt, which still
+ * usual requirements in Documentation/arm64/booting.rst, which still
  * apply to other bootloaders, and are required for some kernel
  * configurations.
  */

arch/arm64/include/asm/image.h

@@ -27,7 +27,7 @@
 
 /*
  * struct arm64_image_header - arm64 kernel image header
- * See Documentation/arm64/booting.txt for details
+ * See Documentation/arm64/booting.rst for details
  *
  * @code0:		Executable code, or
  *   @mz_header		  alternatively used for part of MZ header

arch/arm64/include/uapi/asm/sigcontext.h

@@ -137,7 +137,7 @@ struct sve_context {
  * vector length beyond its initial architectural limit of 2048 bits
  * (16 quadwords).
  *
- * See linux/Documentation/arm64/sve.txt for a description of the VL/VQ
+ * See linux/Documentation/arm64/sve.rst for a description of the VL/VQ
  * terminology.
  */
 #define SVE_VQ_BYTES		__SVE_VQ_BYTES	/* bytes per quadword */

arch/arm64/kernel/kexec_image.c

@@ -53,7 +53,7 @@ static void *image_load(struct kimage *image,
 
 	/*
 	 * We require a kernel with an unambiguous Image header. Per
-	 * Documentation/arm64/booting.txt, this is the case when image_size
+	 * Documentation/arm64/booting.rst, this is the case when image_size
 	 * is non-zero (practically speaking, since v3.17).
 	 */
 	h = (struct arm64_image_header *)kernel;