CXL Driver Operation

CXL driver 장치 경로

.. SPDX-License-Identifier: GPL-2.0

이 문서에서 설명하는 장치는 다음 경로에 있습니다.

/sys/bus/cxl/devices/
/dev/cxl/

NDTCL 프로젝트의 일부로 관리되는 `cxl-cli` library를 사용하면 이 장치들과의 상호작용을 script로 자동화할 수 있습니다.

CXL driver 구성 모듈

CXL driver는 여러 driver로 나뉩니다.

• `cxl_core`: 기본 초기화 interface와 core object 생성을 담당합니다.
• `cxl_port`: root를 초기화하고 port enumeration interface를 제공합니다.
• `cxl_acpi`: root decoder를 초기화하고 ACPI data와 상호작용합니다.
• `cxl_p/mem`: memory device를 초기화합니다.
• `cxl_pci`: `cxl_port`를 이용해 실제 fabric 계층을 열거합니다.

Host Bridge interleave 예제

다음은 Host Bridge가 4개인 single-socket 시스템 예입니다. 두 Host Bridge에 memory device가 하나씩 연결되고, 두 장치는 하나의 memory region으로 interleave돼 있습니다. 이 memory region은 DAX로 변환됐습니다.

# ls /sys/bus/cxl/devices/
  dax_region0  decoder3.0  decoder6.0  mem0   port3
  decoder0.0   decoder4.0  decoder6.1  mem1   port4
  decoder1.0   decoder5.0  endpoint5   port1  region0
  decoder2.0   decoder5.1  endpoint6   port2  root0

.. kernel-render:: DOT
   :alt: Digraph of CXL fabric describing host-bridge interleaving
   :caption: Diagraph of CXL fabric with a host-bridge interleave memory region

   digraph foo {
     "root0" -> "port1";
     "root0" -> "port3";
     "root0" -> "decoder0.0";
     "port1" -> "endpoint5";
     "port3" -> "endpoint6";
     "port1" -> "decoder1.0";
     "port3" -> "decoder3.0";
     "endpoint5" -> "decoder5.0";
     "endpoint6" -> "decoder6.0";
     "decoder0.0" -> "region0";
     "decoder0.0" -> "decoder1.0";
     "decoder0.0" -> "decoder3.0";
     "decoder1.0" -> "decoder5.0";
     "decoder3.0" -> "decoder6.0";
     "decoder5.0" -> "region0";
     "decoder6.0" -> "region0";
     "region0" -> "dax_region0";
     "dax_region0" -> "dax0.0";
   }

이 절에서는 이 구성에 나타나는 장치를 살펴봅니다. 더 다양한 구성은 뒤의 example configuration 문서에서 자세히 다룹니다.

Base Device와 CXL Root

CXL fabric의 대부분 장치는 어떤 종류의 `port`입니다. 각 장치가 직접 서비스를 제공하기보다는 한 장치의 요청을 다음 장치로 routing하는 역할을 주로 하기 때문입니다.

`CXL Root`는 `ACPI0017` Compute Express Link Root Object Device Class를 찾았을 때 `cxl_acpi` driver가 `cxl_acpi_probe` 중 생성하는 logical object입니다.

Root에는 다음 항목을 향한 link가 있습니다.

• CEDT의 CHBS가 정의한 Host Bridge Port
• 보통 Host Bridge Port에 연결되는 Downstream Port
• CEDT의 CFMWS가 정의한 Root Decoder

# ls /sys/bus/cxl/devices/root0
  decoder0.0          dport0  dport5    port2  subsystem
  decoders_committed  dport1  modalias  port3  uevent
  devtype             dport4  port1     port4  uport

# cat /sys/bus/cxl/devices/root0/devtype
  cxl_port

# cat port1/devtype
  cxl_port

# cat decoder0.0/devtype
  cxl_decoder_root

Linux CXL driver가 보여 주는 fabric에서 root는 첫 logical port입니다. CXL root는 downstream port 연결만 가진다는 점에서 특별한 switch port입니다.

Port와 Host Bridge

`port` object는 `switch port`라고 설명하는 편이 정확합니다. root에 연결된 Host Bridge를 나타낼 수도 있고 실제 switch의 port를 나타낼 수도 있습니다.

switch port에는 memory 요청을 downstream port로 routing하는 decoder가 하나 이상 있습니다. downstream은 다른 switch port나 endpoint port에 연결될 수 있습니다.

# ls /sys/bus/cxl/devices/port1
  decoder1.0          dport0    driver     parent_dport  uport
  decoders_committed  dport113  endpoint5  subsystem
  devtype             dport2    modalias   uevent

# cat devtype
  cxl_port

# cat decoder1.0/devtype
  cxl_decoder_switch

# cat endpoint5/devtype
  cxl_port

fabric의 CXL Host Bridge는 CXL Root를 probe하는 `cxl_acpi_probe` 중 함께 probe되므로 root와 Host Bridge 사이의 logical 연결을 즉시 만들 수 있습니다.

• root는 Host Bridge를 향하는 downstream port 연결을 가집니다.
• Host Bridge는 root를 향하는 upstream port 연결을 가집니다.
• Host Bridge는 switch 또는 endpoint port를 향하는 downstream port 연결을 하나 이상 가집니다.

Host Bridge는 특별한 CXL switch port이며 ACPI 사양의 `ACPI0016` ID로 명시됩니다. Host Bridge port는 `acpi_probe` 때 probe되고 실제 switch의 비슷한 port는 나중에 probe됩니다. 두 유형 모두 upstream과 downstream 사이의 접근을 routing하는 switch decoder를 포함하므로 그 밖의 모습은 매우 비슷합니다.

Endpoint port

endpoint는 fabric의 terminal port입니다. memory device가 제시하는 여러 logical device 중 하나일 수 있는 logical device이며, fabric에서는 여전히 port의 한 유형입니다.

endpoint는 endpoint decoder와 장치 capability를 설명하는 Coherent Device Attribute Table(CDAT)을 포함합니다.

# ls /sys/bus/cxl/devices/endpoint5
  CDAT        decoders_committed  modalias      uevent
  decoder5.0  devtype             parent_dport  uport
  decoder5.1  driver              subsystem

# cat /sys/bus/cxl/devices/endpoint5/devtype
  cxl_port

# cat /sys/bus/cxl/devices/endpoint5/decoder5.0/devtype
  cxl_decoder_endpoint

Memory Device(memdev)

`memdev`는 `cxl_pci` driver가 `cxl_pci_probe`에서 probe해 추가하고 `cxl_mem` driver가 관리합니다. 주로 `/dev/cxl/memN`을 통한 memory device IOCTL interface를 제공하고 여러 장치 구성 data를 노출합니다.

# ls /sys/bus/cxl/devices/mem0
  dev       firmware_version    payload_max  security   uevent
  driver    label_storage_size  pmem         serial
  firmware  numa_node           ram          subsystem

Memory Device는 port가 아닌 별도의 base object입니다. 물리 장치가 endpoint도 함께 가질 수 있지만 endpoint와 memdev의 관계는 sysfs에 표현되지 않습니다.

Port 관계

예제에는 root에 연결된 Host Bridge가 네 개 있고, 그중 두 Host Bridge에 endpoint가 하나씩 연결돼 있습니다.

.. kernel-render:: DOT
   :alt: Digraph of CXL fabric describing host-bridge interleaving
   :caption: Diagraph of CXL fabric with a host-bridge interleave memory region

   digraph foo {
     "root0"    -> "port1";
     "root0"    -> "port2";
     "root0"    -> "port3";
     "root0"    -> "port4";
     "port1" -> "endpoint5";
     "port3" -> "endpoint6";
   }

HDM Decoder의 역할

Decoder는 CXL Host-Managed Device Memory(HDM) Decoder를 줄인 말입니다. fabric을 통해 endpoint로 접근을 routing하고, endpoint에서는 Host Physical Address를 Device Physical Address로 변환합니다.

CXL 3.1 사양은 endpoint decoder만 Host Physical Address(HPA)를 Device Physical Address(DPA)로 변환해야 한다는 점을 강하게 시사합니다.

8.2.4.20 CXL HDM Decoder Capability Structure

IMPLEMENTATION NOTE
CXL Host Bridge and Upstream Switch Port Decode Flow

IMPLEMENTATION NOTE
Device Decode Logic

이 구현 참고 사항은 decoder를 두 logical group으로 나눕니다.

• Routing Decoder: 접근을 routing하지만 HPA를 DPA로 변환하지 않습니다.
• Translating Decoder: endpoint가 처리할 수 있도록 접근 주소를 HPA에서 DPA로 변환합니다.

CXL driver는 root, switch, endpoint의 세 decoder 유형을 구별합니다. Endpoint Decoder만 Translating Decoder이고 나머지는 모두 Routing Decoder입니다.

플랫폼 공급자는 Linux가 endpoint decoder만 fabric에서 HPA를 DPA로 실제 변환한다고 강하게 가정한다는 점에 유의해야 합니다. Routing Decoder는 변경하지 않은 HPA를 다음 decoder에 전달한다고 가정합니다.

따라서 fabric의 각 decoder 주소 범위는 upstream port decoder 범위의 부분집합이어야 합니다. 이 방식에서 벗어난 동작은 사양상 정의되지 않았으며 Linux는 사양에 정의된 architecture 동작을 우선합니다.

memory 접근을 interleave하도록 구성한 decoder는 Downstream Target을 하나 이상 가질 수 있고 sysfs의 `target_list` parameter에 표시됩니다.

Root Decoder

Root Decoder는 CEDT의 CFMWS field에 있는 물리 주소와 interleave 구성을 표현하는 logical construct입니다. Linux는 이를 CXL Root에 있는 decoder로 제시합니다. 기술적으로는 CXL 사양과 플랫폼별 CXL root 구현의 경계에 존재하지만 이 문서에서는 Root Decoder라고 부릅니다.

Linux는 이를 Routing Decoder로 간주하며 플랫폼 memory controller에서 온 접근을 처음 받는 CXL fabric decoder입니다.

`cxl_acpi_probe` 중 CEDT CFMWS entry마다 Root Decoder 하나를 만듭니다. `target_list`는 CFMWS target field로 채우며 target은 Host Bridge입니다. 따라서 root decoder 수준의 interleave는 Inter-Host-Bridge Interleave이고 이 기능은 Root Decoder만 수행할 수 있습니다.

이 interleave는 플랫폼이 구성하고 ACPI CEDT CFMWS에 기술해야 합니다. CFMWS의 target CXL Host Bridge UID는 CEDT CHBS와 DSDT에 정의된 CXL Host Bridge UID와 일치해야 합니다.

Root Decoder의 interleave 설정은 전체 interleave set이 아니라 바로 아래 downstream target 사이에서 접근을 interleave하는 방법을 설명합니다.

Root Decoder가 설명하는 memory 범위는 memory region을 만들고, 그 region을 `kernel/resource.c`의 IO Memory Resource와 연결하는 데 사용합니다.

# ls /sys/bus/cxl/devices/decoder0.0/
  cap_pmem           devtype                 region0
  cap_ram            interleave_granularity  size
  cap_type2          interleave_ways         start
  cap_type3          locked                  subsystem
  create_ram_region  modalias                target_list
  delete_region      qos_class               uevent

# cat /sys/bus/cxl/devices/decoder0.0/region0/resource
  0xc050000000

IO Memory Resource는 초기 부팅 중 CFMWS region을 EFI Memory Map 또는 x86의 E820 table에서 찾을 때 생성됩니다.

Root Decoder는 별도 `devtype`으로 정의되지만 downstream target이 있으므로 Switch Decoder의 한 유형이기도 합니다.

# cat /sys/bus/cxl/devices/decoder0.0/devtype
  cxl_decoder_root

Switch Decoder

root가 아닌 routing decoder는 Switch Decoder이며 `cxl_decoder_switch` 유형으로 표시됩니다. Host Bridge와 실제 CXL Switch의 decoder가 모두 이 유형입니다.

# ls /sys/bus/cxl/devices/decoder1.0/
  devtype                 locked    size       target_list
  interleave_granularity  modalias  start      target_type
  interleave_ways         region    subsystem  uevent

# cat /sys/bus/cxl/devices/decoder1.0/devtype
  cxl_decoder_switch

# cat /sys/bus/cxl/devices/decoder1.0/region
  region0

Switch Decoder는 Root Decoder가 정의한 region과 downstream target port 사이의 연관을 가집니다. Switch Decoder 안에서의 interleave는 multi-downstream-port interleave이며, Host Bridge에서는 Intra-Host-Bridge Interleave라고도 부릅니다.

Switch Decoder의 interleave 설정도 전체 interleave set이 아니라 바로 아래 downstream target 사이의 분배를 설명합니다.

Switch Decoder는 `cxl_port` driver의 `cxl_switch_port_probe` 중 PCI 장치 DVSEC register를 바탕으로 생성됩니다. 플랫폼이 부팅 중 프로그래밍한 경우 probe 때 검증하고, 실행 중 프로그래밍한 경우 commit 때 검증합니다.

Endpoint Decoder

CXL fabric의 terminal 지점인 Endpoint에 연결된 decoder는 Endpoint Decoder이며 `cxl_decoder_endpoint` 유형입니다.

# ls /sys/bus/cxl/devices/decoder5.0
  devtype                 locked    start
  dpa_resource            modalias  subsystem
  dpa_size                mode      target_type
  interleave_granularity  region    uevent
  interleave_ways         size

# cat /sys/bus/cxl/devices/decoder5.0/devtype
  cxl_decoder_endpoint

# cat /sys/bus/cxl/devices/decoder5.0/region
  region0

Endpoint Decoder는 Root Decoder가 정의한 region과 연관되며 이 region에 연결된 device-local resource를 설명합니다.

Root 및 Switch Decoder와 달리 Endpoint Decoder는 Host Physical Address 범위를 Device Physical Address 범위로 변환합니다. 따라서 Endpoint Decoder의 interleave 설정은 전체 interleave set을 설명합니다.

Device Physical Address region은 순서대로 commit해야 합니다. 예를 들어 `0x80000000`에서 시작하는 DPA region을 `0x0`에서 시작하는 region보다 먼저 commit할 수 없습니다.

Linux v6.15 기준으로 불균형 interleave 구성을 지원하지 않습니다. 한 interleave set의 모든 endpoint는 granularity와 ways가 같은 설정을 가져야 합니다.

Endpoint Decoder는 `cxl_port` driver의 `cxl_endpoint_port_probe` 중 PCI 장치 DVSEC register를 바탕으로 생성됩니다.

Decoder 계층 관계

예제의 Root Decoder 하나는 두 Host Bridge에 memory 접근을 routing합니다. 각 Host Bridge decoder는 단일 endpoint target으로 접근을 routing하고, 각 Endpoint Decoder는 HPA를 DPA로 변환해 memory 요청을 처리합니다.

driver는 decoder programming으로 port 사이의 관계를 검증하므로 decoder도 port와 비슷한 계층 관계로 생각할 수 있습니다.

.. kernel-render:: DOT
   :alt: Digraph of hierarchical relationship between root, switch, and endpoint decoders.
   :caption: Diagraph of CXL root, switch, and endpoint decoders.

   digraph foo {
     "root0"    -> "decoder0.0";
     "decoder0.0" -> "decoder1.0";
     "decoder0.0" -> "decoder3.0";
     "decoder1.0" -> "decoder5.0";
     "decoder3.0" -> "decoder6.0";
   }

Memory Region과 DAX Region

Memory Region은 fabric의 CXL port 집합을 IO Memory Resource와 연결하는 logical construct입니다. 최종적으로 이 장치의 memory를 DAX Region을 통해 DAX subsystem에 노출하는 데 사용합니다.

# ls /sys/bus/cxl/devices/region0/
  access0      devtype                 modalias  subsystem  uuid
  access1      driver                  mode      target0
  commit       interleave_granularity  resource  target1
  dax_region0  interleave_ways         size      uevent

BIOS/EFI가 decoder를 프로그래밍했다면 endpoint probe 중 memory region을 만들 수 있습니다. 또는 Root Decoder의 `create_ram_region`이나 `create_pmem_region` interface를 통해 수동으로 만들 수 있습니다.

Memory Region의 interleave 설정은 Interleave Set의 구성을 설명하며 Endpoint Decoder의 interleave 설정에서도 같은 값을 볼 수 있어야 합니다.

.. kernel-render:: DOT
   :alt: Digraph of CXL memory region relationships between root and endpoint decoders.
   :caption: Regions are created based on root decoder configurations. Endpoint decoders
             must be programmed with the same interleave settings as the region.

   digraph foo {
     "root0"    -> "decoder0.0";
     "decoder0.0" -> "region0";
     "region0" -> "decoder5.0";
     "region0" -> "decoder6.0";
   }

DAX Region은 CXL Memory Region을 DAX 장치로 변환합니다. DAX 장치는 file descriptor interface로 직접 접근하거나 DAX kmem driver를 통해 System RAM으로 변환할 수 있습니다.

# ls /sys/bus/cxl/devices/dax_region0/
  dax0.0      devtype  modalias   uevent
  dax_region  driver   subsystem

Mailbox interface

각 장치의 mailbox command interface는 다음 경로에 노출됩니다.

/dev/cxl/mem0
/dev/cxl/mem1

이 mailbox는 사양에 정의된 모든 command를 받을 수 있습니다. raw 또는 custom command는 build 설정 `CXL_MEM_RAW_COMMANDS`가 켜진 경우에만 보낼 수 있습니다.

이 기능은 debug·개발 interface이며 vendor-specific command를 만드는 공식 지원 수단이 아닙니다. 그런 용도에는 `fwctl` subsystem을 사용합니다.

Runtime Programming과 Auto Decoder

probe 중 반드시 프로그래밍돼 있어야 하는 decoder는 Root Decoder뿐입니다. 실제로 Root Decoder는 ACPI CEDT CFMWS가 설명하는 Host Bridge 수준의 memory region과 interleave 구성을 나타내는 logical construct입니다.

플랫폼이 허용한다면 나머지 Switch 및 Endpoint Decoder는 사용자가 실행 중 프로그래밍할 수 있습니다. 이 상호작용이 Software Defined Memory 환경을 만듭니다. 실행 중 구성 방법은 `cxl-cli` 문서를 참고하십시오.

Auto Decoder는 BIOS/EFI가 부팅 때 프로그래밍한 decoder이며 거의 항상 잠겨 있어 변경할 수 없습니다. 플랫폼이 정적 구성을 사용하거나 CPU complex 안에서 CXL 범위를 벗어난 추가 controller programming이 필요해 동적 변경을 막는 경우에 사용합니다.

연결된 장치와 memory region이 문제없이 probe되면 Auto Decoder도 자동으로 probe됩니다. driver의 주된 책임은 실행 중 프로그래밍된 region과 decoder를 검증할 때처럼 fabric 구성이 타당한지 확인하는 것입니다.

Linux가 auto-decoder 구성을 검증하지 못하면 memory를 DAX 장치로 노출하지 않으며 page allocator에도 제공하지 못해 사실상 사용할 수 없게 됩니다.

Cross-Link First interleave

Linux CXL driver는 Cross-Link First interleave를 지원합니다. driver가 decoder와 parent의 관계를 검증하므로 이 방식은 각 decoder 단계에서 interleave를 프로그래밍하는 방법을 정합니다.

Host Bridge 4개에 Endpoint 16개가 연결된 4x4 Cross-Link First 구성에서 root, Host Bridge, Endpoint의 ways와 granularity는 다음과 같습니다.

.. flat-table:: 4x4 cross-link first interleave settings

  * - decoder
    - ways
    - granularity

  * - root
    - 4
    - 256

  * - host bridge
    - 4
    - 1024

  * - endpoint
    - 16
    - 256

root에서는 각 접근을 `((HPA / 256) % 4)`번째 target Host Bridge로 routing합니다. Host Bridge 안에서는 `((HPA / 1024) % 4)`번째 target Endpoint로 보냅니다. 각 Endpoint는 장치 16개 전체 interleave set을 기준으로 변환합니다.

불균형 interleave set은 지원하지 않습니다. 계층에서 같은 위치에 있는 decoder, 예를 들어 모든 Host Bridge Decoder는 ways와 granularity가 같아야 합니다.

Root 수준 interleave

Root Decoder interleave는 CEDT의 CFMWS field가 정의합니다. CEDT는 사용자가 실행 중 memory를 interleave 또는 non-interleave로 online할지 선택하게 하려는 목적으로 같은 물리 용량을 설명하는 CFMWS 구성을 여러 개 정의할 수 있습니다.

           Subtable Type : 01 [CXL Fixed Memory Window Structure]
     Window base address : 0000000100000000
             Window size : 0000000100000000
Interleave Members (2^n) : 00
   Interleave Arithmetic : 00
            First Target : 00000007

           Subtable Type : 01 [CXL Fixed Memory Window Structure]
     Window base address : 0000000200000000
             Window size : 0000000100000000
Interleave Members (2^n) : 00
   Interleave Arithmetic : 00
            First Target : 00000006

           Subtable Type : 01 [CXL Fixed Memory Window Structure]
     Window base address : 0000000300000000
             Window size : 0000000200000000
Interleave Members (2^n) : 01
   Interleave Arithmetic : 00
            First Target : 00000007
             Next Target : 00000006

이 예에서 CFMWS는 각 Host Bridge에 대한 서로 분리된 non-interleave 4 GiB region 두 개와 두 Host Bridge 모두를 target으로 하는 interleave 8 GiB region 하나를 정의합니다. 결과적으로 root에는 Root Decoder 세 개가 나타납니다.

# ls /sys/bus/cxl/devices/root0/decoder*
  decoder0.0  decoder0.1  decoder0.2

# cat /sys/bus/cxl/devices/decoder0.0/target_list start size
  7
  0x100000000
  0x100000000

# cat /sys/bus/cxl/devices/decoder0.1/target_list start size
  6
  0x200000000
  0x100000000

# cat /sys/bus/cxl/devices/decoder0.2/target_list start size
  7,6
  0x300000000
  0x200000000

이 decoder들은 실행 중 프로그래밍할 수 없습니다. Memory Region을 생성해 Switch 및 Endpoint Decoder에 실행 중 설정을 프로그래밍하고 이 memory를 online하는 데 사용합니다.

Host Bridge와 Switch 프로그래밍

Host Bridge와 Switch Decoder는 다음 field로 프로그래밍합니다.

• `start`: memory region에 연결된 HPA region
• `size`: region 크기
• `target_list`: downstream port 목록
• `interleave_ways`: interleave할 downstream port 수
• `interleave_granularity`: interleave granularity

Linux는 Switch Decoder의 `interleave_granularity`가 upstream port 연결에서 유도되기를 기대합니다. Cross-Link First 구성에서는 decoder의 granularity가 `parent_interleave_granularity * parent_interleave_ways`와 같습니다.

Endpoint 프로그래밍

Endpoint Decoder도 Host Bridge 및 Switch Decoder와 비슷하게 프로그래밍하지만 ways와 granularity는 연결된 Memory Region이 정의한 전체 interleave set을 따릅니다.

• `start`: memory region에 연결된 HPA region
• `size`: region 크기
• `interleave_ways`: interleave set의 Endpoint 수
• `interleave_granularity`: interleave granularity

Endpoint Decoder는 이 설정을 사용해 memory 요청을 HPA에서 DPA로 변환하므로 전체 interleave set을 알아야 합니다.

Linux는 불균형 interleave 구성을 지원하지 않으므로 한 set의 모든 Endpoint는 ways와 granularity가 같아야 합니다.

예제 구성 문서

하위 문서는 single device, Host Bridge interleave, Host Bridge 내부 interleave와 다중 interleave 예제를 제공합니다.

.. toctree::
   :maxdepth: 1

   example-configurations/single-device.rst
   example-configurations/hb-interleave.rst
   example-configurations/intra-hb-interleave.rst
   example-configurations/multi-interleave.rst