Linux: overview update

Author: Gregory Price

doc/linux/overview.rst

@@ -3,82 +3,102 @@
 Overview
 ########
 
-* Early Boot
+This section presents the configuration process of a CXL Type-3 memory device,
+and how it is ultimately exposed to users as either a :code:`DAX` device or
+normal memory pages via the kernel's page allocator.
 
-  * Linux Boot Parameters
+Portions marked with a bullet are points at which certain kernel objects
+are generated.
 
-    * nosoftreserve
+1) Early Boot
 
-  * Memory Map Creation
+  a) BIOS, Build, and Boot Parameters
 
-    * EFI Memory Map / E820 Consulted for Soft-Reserved
+    i) EFI_MEMORY_SP
+    ii) CONFIG_EFI_SOFT_RESERVE
+    iii) CONFIG_MHP_DEFAULT_ONLINE_TYPE
+    iv) nosoftreserve
+
+  b) Memory Map Creation
+
+    i) EFI Memory Map / E820 Consulted for Soft-Reserved
 
       * CXL Memory is set aside to be handled by the CXL driver
 
       * IO Resources are created for CFMWS entry
 
-  * NUMA Node Creation
+  c) NUMA Node Creation
 
     * ACPI CEDT and SRAT table are used to create Nodes from Proximity domains (PXM)
 
-  * Memory Tier Creation
+  d) Memory Tier Creation
 
-    * A default tier is created with all nodes.
+    * A default memory_tier is created with all nodes.
 
-  * Contiguous Memory Allocation
+  e) Contiguous Memory Allocation
 
     * Any requested CMA is allocated from Online nodes
 
-  * Init Finishes, Drivers start probing
+  f) Init Finishes, Drivers start probing
 
-* ACPI and PCI Drivers
+2) ACPI and PCI Drivers
 
-  * Detect CXL device, marking it for probe by CXL driver
+  a) Detect CXL device, marking it for probe by CXL driver
 
-* CXL Driver Operation
+  b) This portion will not be covered specifically.
 
-  * Base object creation (root, port, memdev)
+3) CXL Driver Operation
 
-    * CEDT CFMWS IO Resource creation
+  a) Base device creation
 
-  * Decoder creation (root, switch, endpoint)
-
-  * Logical device creation (region, endpoint)
+    * root, port, and memdev devices created
+    * CEDT CFMWS IO Resource creation
 
-  * Devices are associated with each other
+  b) Decoder creation
 
-    * If auto-decoder (BIOS-programmed decoders), driver validates configurations and locks everything.
+    * root, switch, and endpoint decoders created
 
-  * Regions surfaced as DAX region
+  c) Logical device creation
+  
+    * memory_region and endpoint devices created
 
-    * DAX Region surfaced as DAX device
+  d) Devices are associated with each other
 
-* DAX Driver Operation
+    * If auto-decoder (BIOS-programmed decoders), driver validates
+      configurations, builds associations, and locks configs at probe time.
 
-  * DAX driver surfaces DAX region as one of two dax device modes
+    * If user-configured, validation and associations are built at
+      decoder-commit time.
 
-    * kmem - dax device is converted to hotplug memory
+  e) Regions surfaced as DAX region
 
-    * hmem - dax device is left to be accessed as a file.
+    * dax_region created
 
-  * DAX driver surfaces dax device to /dev/daxX.Y
+    * DAX device created via DAX driver
 
-    * DAX kmem IO resource creation
+4) DAX Driver Operation
 
-    * If hmem, journey ends here.
+  a) DAX driver surfaces DAX region as one of two dax device modes
 
-  * DAX kmem surfaces memory region to Memory Hotplug to add to page allocator as "driver managed memory"
+    * kmem - dax device is converted to hotplug memory blocks
+    
+      * DAX kmem IO resource creation
 
-* Memory Hotplug
+    * hmem - dax device is left as daxdev to be accessed as a file.
+    
+      * If hmem, journey ends here.
 
-  * mhp component surfaces a memory region as multiple memory blocks to the page allocator
+  b) DAX kmem surfaces memory region to Memory Hotplug to add to page
+     allocator as "driver managed memory"
 
-    * blocks appear in /sys/bus/memory/devices and /sys/bus/memory/node/devices/nodeN/
+5) Memory Hotplug
 
-  * blocks are onlined into the requested zone (NORMAL or MOVABLE)
+  a) mhp component surfaces a dax device memory region as multiple memory
+     blocks to the page allocator
 
-    * Build option: CONFIG_MHP_DEFAULT_ONLINE_TYPE_*
+    * blocks appear in :code:`/sys/bus/memory/devices` and linked to a NUMA node
 
-    * Boot option: memhp_default_state
+  b) blocks are onlined into the requested zone (NORMAL or MOVABLE)
 
-  * Memory is marked "Driver Managed" to avoid kexec from using it as region for kernel updates
+    * Memory is marked "Driver Managed" to avoid kexec from using it as region
+      for kernel updates