VFIO AP Locks Overview

VFIO AP 잠금 개요

이 문서는 `GPL-2.0` 라이선스로 제공되며 `vfio_ap` device driver를 안전하게 운용하는 데 관련된 잠금을 설명합니다. 문서 전체에서 다음 변수는 설명 대상 구조체 instance를 나타냅니다.

struct ap_matrix_dev *matrix_dev;
struct ap_matrix_mdev *matrix_mdev;
struct kvm *kvm;

Matrix Devices Lock

Matrix Devices Lock은 `drivers/s390/crypto/vfio_ap_private.h`의 `struct ap_matrix_dev`에 정의됩니다.

struct ap_matrix_dev {
        ...
        struct list_head mdev_list;
        struct mutex mdevs_lock;
        ...
}

`matrix_dev->mdevs_lock`은 유일한 `struct ap_matrix_dev` object 안에 있는 global mutex입니다. 이 잠금은 `matrix_dev->mdev_list`에 속한 각 `matrix_mdev`의 모든 field 접근을 제어합니다.

`vfio_ap` device driver의 mediated device를 나타내는 `matrix_mdev` instance의 field를 읽거나 쓰거나, 그 field에서 얻은 data를 사용할 때는 이 잠금을 보유해야 합니다.

KVM Lock

KVM Lock은 `include/linux/kvm_host.h`의 `struct kvm`에 정의됩니다.

struct kvm {
        ...
        struct mutex lock;
        ...
}

`kvm->lock`은 KVM guest의 state data 접근을 제어합니다. `vfio_ap` device driver가 AP adapter, domain 또는 control domain 하나 이상을 guest에 plug하거나 guest에서 unplug하는 동안 이 잠금을 보유해야 합니다.

KVM pointer는 KVM guest에 attach된 mediated device의 state를 담는 `matrix_mdev` instance에 `matrix_mdev->kvm = kvm` 형태로 저장됩니다.

Guests Lock

Guests Lock은 `drivers/s390/crypto/vfio_ap_private.h`의 `struct ap_matrix_dev`에 정의됩니다.

struct ap_matrix_dev {
        ...
        struct list_head mdev_list;
        struct mutex guests_lock;
        ...
}

`matrix_dev->guests_lock`은 KVM guest에 attach된 mediated device의 state를 보유하는 `matrix_mdev` instance, 즉 `matrix_dev->mdev_list` 접근을 제어합니다.

예를 들어 queue device가 `vfio_ap` device driver에서 제거될 때 adapter가 KVM guest로 passthrough 중이면 이를 unplug해야 합니다. 먼저 queue가 할당된 `matrix_mdev` object를 찾고, `matrix_mdev->kvm != NULL`인지 확인해 mediated device가 passthrough 중인지 판별한 뒤 adapter를 unplug합니다.

Guests Lock이 필요하지 않은 KVM pointer 접근

KVM pointer를 passthrough device의 plug/unplug에 사용하지 않는다면 pointer 접근을 위해 Guests Lock을 잡을 필요는 없습니다. 대신 KVM pointer가 Matrix Devices Lock 보호 아래 설정·해제되므로 `matrix_dev->mdevs_lock`을 보유해야 합니다.

대표 사례는 `PQAP(AQIC)` instruction sub-function interception handler입니다. 이 handler는 IRQ resource를 설정하거나 해제하는 목적으로만 KVM pointer에 접근하므로 `matrix_dev->mdevs_lock`만 보유하면 됩니다.

PQAP Hook Lock

PQAP Hook Lock은 `arch/s390/include/asm/kvm_host.h`의 `struct kvm_s390_crypto`에 정의됩니다.

typedef int (*crypto_hook)(struct kvm_vcpu *vcpu);

struct kvm_s390_crypto {
        ...
        struct rw_semaphore pqap_hook_rwsem;
        crypto_hook *pqap_hook;
        ...
};

`pqap_hook_rwsem`은 host가 `PQAP(AQIC)` instruction sub-function을 intercept할 때 호출할 handler function pointer `(*kvm->arch.crypto.pqap_hook)`의 접근을 제어하는 read/write semaphore입니다.