Compute Express Link Driver Theory of Operation

Compute Express Link driver 동작 원리

.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>

Compute Express Link Memory Device는 `CXL.mem` protocol을 구현하는 CXL component입니다. 이 device에는 volatile memory, persistent memory 또는 두 종류 모두가 들어 있습니다.

configuration과 MMIO mailbox를 통한 message 전달을 위해 PCI device로 enumerate됩니다. System Physical Address space에 기여하는 범위는 HDM(Host Managed Device Memory) decoder가 처리합니다. HDM decoder는 선택적으로 하나의 host bridge 아래 여러 device 사이 또는 여러 host bridge 사이에서 interleaved address range에 각 device가 기여하는 부분을 정의합니다.

CXL bus와 decode topology 조립

RAID driver가 disk object를 가져와 새로운 logical device로 조립하는 것과 비슷하게, CXL subsystem은 PCIe와 ACPI object를 가져와 `CXL.mem` decode topology로 조립해야 합니다.

같은 hardware configuration에서도 환경에 따라 topology를 서로 다르게 조립할 수 있으므로 runtime configuration이 필요합니다. 한 환경은 여러 Host Bridge와 endpoint에 memory를 stripe하는 성능 중심 RAID0 방식과 비슷한 구성을 고를 수 있고, 다른 환경은 fault tolerance를 위해 `CXL.mem` topology의 striping을 모두 비활성화할 수 있습니다.

platform firmware는 CXL decode topology의 최상단을 뜻하는 Linux 용어인 `CXL root port`에서 interleave option 메뉴를 enumerate합니다. 그 아래에서는 PCIe topology가 어떤 endpoint가 어떤 Host Bridge decode regime에 참여할 수 있는지를 결정합니다.

root와 endpoint 사이의 각 PCIe Switch는 interleave를 나눌 수 있는 지점을 추가합니다. 예를 들어 firmware가 어떤 range를 Host Bridge 하나로만 decode한다고 선언해도, 그 Host Bridge는 여러 Root Port에 cycle을 interleave할 수 있습니다. port와 endpoint 사이의 Switch도 여러 Downstream Switch Port에 cycle을 interleave할 수 있습니다.

cxl_test가 만드는 sample topology

다음은 `cxl_test`가 정의한 CXL topology의 sample listing입니다. `cxl_test` module은 Host Bridge 두 개를 emulate하고 각 Host Bridge에 Root Port 두 개를 둡니다. 각 Root Port는 2-way switch에 연결되고 그 downstream port마다 endpoint가 있어 총 endpoint는 여덟 개입니다.

# cxl list -BEMPu -b cxl_test
{
  "bus":"root3",
  "provider":"cxl_test",
  "ports:root3":[
    {
      "port":"port5",
      "host":"cxl_host_bridge.1",
      "ports:port5":[
        {
          "port":"port8",
          "host":"cxl_switch_uport.1",
          "endpoints:port8":[
            {
              "endpoint":"endpoint9",
              "host":"mem2",
              "memdev":{
                "memdev":"mem2",
                "pmem_size":"256.00 MiB (268.44 MB)",
                "ram_size":"256.00 MiB (268.44 MB)",
                "serial":"0x1",
                "numa_node":1,
                "host":"cxl_mem.1"
              }
            },
            {
              "endpoint":"endpoint15",
              "host":"mem6",
              "memdev":{
                "memdev":"mem6",
                "pmem_size":"256.00 MiB (268.44 MB)",
                "ram_size":"256.00 MiB (268.44 MB)",
                "serial":"0x5",
                "numa_node":1,
                "host":"cxl_mem.5"
              }
            }
          ]
        },
        {
          "port":"port12",
          "host":"cxl_switch_uport.3",
          "endpoints:port12":[
            {
              "endpoint":"endpoint17",
              "host":"mem8",
              "memdev":{
                "memdev":"mem8",
                "pmem_size":"256.00 MiB (268.44 MB)",
                "ram_size":"256.00 MiB (268.44 MB)",
                "serial":"0x7",
                "numa_node":1,
                "host":"cxl_mem.7"
              }
            },
            {
              "endpoint":"endpoint13",
              "host":"mem4",
              "memdev":{
                "memdev":"mem4",
                "pmem_size":"256.00 MiB (268.44 MB)",
                "ram_size":"256.00 MiB (268.44 MB)",
                "serial":"0x3",
                "numa_node":1,
                "host":"cxl_mem.3"
              }
            }
          ]
        }
      ]
    },
    {
      "port":"port4",
      "host":"cxl_host_bridge.0",
      "ports:port4":[
        {
          "port":"port6",
          "host":"cxl_switch_uport.0",
          "endpoints:port6":[
            {
              "endpoint":"endpoint7",
              "host":"mem1",
              "memdev":{
                "memdev":"mem1",
                "pmem_size":"256.00 MiB (268.44 MB)",
                "ram_size":"256.00 MiB (268.44 MB)",
                "serial":"0",
                "numa_node":0,
                "host":"cxl_mem.0"
              }
            },
            {
              "endpoint":"endpoint14",
              "host":"mem5",
              "memdev":{
                "memdev":"mem5",
                "pmem_size":"256.00 MiB (268.44 MB)",
                "ram_size":"256.00 MiB (268.44 MB)",
                "serial":"0x4",
                "numa_node":0,
                "host":"cxl_mem.4"
              }
            }
          ]
        },
        {
          "port":"port10",
          "host":"cxl_switch_uport.2",
          "endpoints:port10":[
            {
              "endpoint":"endpoint16",
              "host":"mem7",
              "memdev":{
                "memdev":"mem7",
                "pmem_size":"256.00 MiB (268.44 MB)",
                "ram_size":"256.00 MiB (268.44 MB)",
                "serial":"0x6",
                "numa_node":0,
                "host":"cxl_mem.6"
              }
            },
            {
              "endpoint":"endpoint11",
              "host":"mem3",
              "memdev":{
                "memdev":"mem3",
                "pmem_size":"256.00 MiB (268.44 MB)",
                "ram_size":"256.00 MiB (268.44 MB)",
                "serial":"0x2",
                "numa_node":0,
                "host":"cxl_mem.2"
              }
            }
          ]
        }
      ]
    }
  ]
}

cxl_port decode model과 lifecycle

listing의 각 `root`, `port`, `endpoint` object는 kernel의 `struct cxl_port` object에 대응합니다. `cxl_port`는 descendant 쪽으로 `CXL.mem`을 decode할 수 있는 device입니다.

따라서 `root`는 PCIe로 enumerate할 수 없는 platform decode range를 소유하고 `port`로 decode합니다. `port`는 `endpoint`로 decode하며, `endpoint`는 SPA(System Physical Address)에서 DPA(Device Physical Address)로 가는 decode를 나타냅니다.

RAID analogy를 계속 적용하면 disk에는 RAID set 조립을 결정하는 topology metadata와 on-device metadata가 모두 있습니다. CXL Port topology와 CXL Port link status는 `CXL.mem` set을 조립하는 metadata입니다.

CXL Port topology는 `CXL.mem` device가 도착할 때 enumerate됩니다. PCIe core가 CXL Memory Expander에 `cxl_pci` driver를 attach하기 전에는 CXL Port object가 할 역할이 없습니다.

반대로 hot-unplug 또는 removal 때는 Linux PCI core가 switch-level CXL resource를 직접 철거할 필요가 없습니다. endpoint의 `->remove()` event가 해당 Memory Expander를 지원하려고 구성했던 port data를 정리하기 때문입니다.

memory device에서 가능한 decoder 찾기

특정 memory device가 참여할 수 있는 port metadata와 잠재적 decode scheme은 다음 command로 확인할 수 있습니다.

# cxl list -BDMu -d root -m mem3
{
  "bus":"root3",
  "provider":"cxl_test",
  "decoders:root3":[
    {
      "decoder":"decoder3.1",
      "resource":"0x8030000000",
      "size":"512.00 MiB (536.87 MB)",
      "volatile_capable":true,
      "nr_targets":2
    },
    {
      "decoder":"decoder3.3",
      "resource":"0x8060000000",
      "size":"512.00 MiB (536.87 MB)",
      "pmem_capable":true,
      "nr_targets":2
    },
    {
      "decoder":"decoder3.0",
      "resource":"0x8020000000",
      "size":"256.00 MiB (268.44 MB)",
      "volatile_capable":true,
      "nr_targets":1
    },
    {
      "decoder":"decoder3.2",
      "resource":"0x8050000000",
      "size":"256.00 MiB (268.44 MB)",
      "pmem_capable":true,
      "nr_targets":1
    }
  ],
  "memdevs:root3":[
    {
      "memdev":"mem3",
      "pmem_size":"256.00 MiB (268.44 MB)",
      "ram_size":"256.00 MiB (268.44 MB)",
      "serial":"0x2",
      "numa_node":0,
      "host":"cxl_mem.2"
    }
  ]
}

device 중심 질의의 의미

이 command는 CXL topology에 `mem3`라는 kernel device name을 가진 CXL Memory Expander가 어떤 platform-level decode range에 참여할 수 있는지를 묻습니다.

expander가 가진 decoder resource 수에 따라 하나의 expander가 여러 `CXL.mem` interleave set에 동시에 참여할 수 있습니다. 이 example에서 mem3는 Host Bridge 두 개를 가로지르는 PMEM interleave, Host Bridge 하나만 대상으로 하는 PMEM interleave, Host Bridge 두 개를 가로지르는 Volatile memory interleave, Host Bridge 하나만 대상으로 하는 Volatile memory interleave 가운데 하나 이상에 참여할 수 있습니다.

decoder에서 참여 가능한 device 찾기

반대 방향으로, 특정 platform-level decode scheme에 참여할 수 있는 memory device는 다음 command로 확인할 수 있습니다.

# cxl list -MDu -d 3.2
[
  {
    "memdevs":[
      {
        "memdev":"mem1",
        "pmem_size":"256.00 MiB (268.44 MB)",
        "ram_size":"256.00 MiB (268.44 MB)",
        "serial":"0",
        "numa_node":0,
        "host":"cxl_mem.0"
      },
      {
        "memdev":"mem5",
        "pmem_size":"256.00 MiB (268.44 MB)",
        "ram_size":"256.00 MiB (268.44 MB)",
        "serial":"0x4",
        "numa_node":0,
        "host":"cxl_mem.4"
      },
      {
        "memdev":"mem7",
        "pmem_size":"256.00 MiB (268.44 MB)",
        "ram_size":"256.00 MiB (268.44 MB)",
        "serial":"0x6",
        "numa_node":0,
        "host":"cxl_mem.6"
      },
      {
        "memdev":"mem3",
        "pmem_size":"256.00 MiB (268.44 MB)",
        "ram_size":"256.00 MiB (268.44 MB)",
        "serial":"0x2",
        "numa_node":0,
        "host":"cxl_mem.2"
      }
    ]
  },
  {
    "root decoders":[
      {
        "decoder":"decoder3.2",
        "resource":"0x8050000000",
        "size":"256.00 MiB (268.44 MB)",
        "pmem_capable":true,
        "nr_targets":1
      }
    ]
  }
]

decoder naming scheme은 `decoder<port_id>.<instance_id>`입니다. 따라서 `decoder3.2`는 port id 3에 속한 instance id 2 decoder를 뜻합니다.

Driver Infrastructure와 CXL Memory Device

이 section은 CXL memory device를 위한 driver infrastructure를 다룹니다. `CXL Memory Device` subsection은 PCI transport, memory device layer, internal memory structure, memdev core identifier 문서를 kernel-doc에서 가져옵니다.

.. kernel-doc:: drivers/cxl/pci.c
   :doc: cxl pci

.. kernel-doc:: drivers/cxl/pci.c
   :internal:

.. kernel-doc:: drivers/cxl/mem.c
   :doc: cxl mem

.. kernel-doc:: drivers/cxl/cxlmem.h
   :internal:

.. kernel-doc:: drivers/cxl/core/memdev.c
   :identifiers:

• `drivers/cxl/pci.c`: `cxl pci` 문서와 internal symbol
• `drivers/cxl/mem.c`: `cxl mem` 문서
• `drivers/cxl/cxlmem.h`: internal definition
• `drivers/cxl/core/memdev.c`: exported identifier

CXL Port infrastructure

`CXL Port` subsection은 `drivers/cxl/port.c`의 `cxl port` kernel-doc를 포함해 port driver의 동작을 설명합니다.

.. kernel-doc:: drivers/cxl/port.c
   :doc: cxl port

CXL Core infrastructure

`CXL Core` subsection은 object model, ACPI resource 추가, HDM/CDAT, port와 PCI core, persistent memory, register, mailbox, feature setup을 담당하는 source의 문서와 identifier를 모읍니다.

.. kernel-doc:: drivers/cxl/cxl.h
   :doc: cxl objects

.. kernel-doc:: drivers/cxl/cxl.h
   :internal:

.. kernel-doc:: drivers/cxl/acpi.c
   :identifiers: add_cxl_resources

.. kernel-doc:: drivers/cxl/core/hdm.c
   :doc: cxl core hdm

.. kernel-doc:: drivers/cxl/core/hdm.c
   :identifiers:

.. kernel-doc:: drivers/cxl/core/cdat.c
   :identifiers:

.. kernel-doc:: drivers/cxl/core/port.c
   :doc: cxl core

.. kernel-doc:: drivers/cxl/core/port.c
   :identifiers:

.. kernel-doc:: drivers/cxl/core/pci.c
   :doc: cxl core pci

.. kernel-doc:: drivers/cxl/core/pci.c
   :identifiers:

.. kernel-doc:: drivers/cxl/core/pmem.c
   :doc: cxl pmem

.. kernel-doc:: drivers/cxl/core/pmem.c
   :identifiers:

.. kernel-doc:: drivers/cxl/core/regs.c
   :doc: cxl registers

.. kernel-doc:: drivers/cxl/core/regs.c
   :identifiers:

.. kernel-doc:: drivers/cxl/core/mbox.c
   :doc: cxl mbox

.. kernel-doc:: drivers/cxl/core/mbox.c
   :identifiers:

.. kernel-doc:: drivers/cxl/core/features.c
   :doc: cxl features

feature API의 자세한 내용은 :c:func:`devm_cxl_setup_features`를 참조합니다.

CXL Regions

`CXL Regions` subsection은 `drivers/cxl/core/region.c`의 `cxl core region` 문서와 exported identifier를 kernel-doc로 포함합니다.

.. kernel-doc:: drivers/cxl/core/region.c
   :doc: cxl core region

.. kernel-doc:: drivers/cxl/core/region.c
   :identifiers:

External Interfaces와 CXL IOCTL

`External Interfaces`의 `CXL IOCTL Interface` subsection은 `include/uapi/linux/cxl_mem.h`에서 UAPI 문서와 internal definition을 가져옵니다.

.. kernel-doc:: include/uapi/linux/cxl_mem.h
   :doc: UAPI

.. kernel-doc:: include/uapi/linux/cxl_mem.h
   :internal: