InfiniBand Userspace Capabilities

UCAP 목적과 사용자 권한 부여 흐름

User CAPabilities(UCAPs)는 InfiniBand 장치의 특정 펌웨어 기능을 세밀하게 제어합니다. 일부 펌웨어 기능에는 기존 Linux capability가 지나치게 포괄적일 수 있으므로, UCAP은 기능별로 더 작은 권한 단위를 제공합니다.

각 사용자 capability는 root만 읽고 쓸 수 있는 문자 장치로 표현됩니다. root 프로세스는 `chown` 같은 방법으로 사용자가 해당 문자 장치에 접근하도록 허용해 특정 특권만 부여할 수 있습니다.

사용자는 허용된 UCAP 파일을 열어 파일 디스크립터를 얻고, IB 장치를 열 때 이 디스크립터 배열을 속성으로 함께 전달합니다. `ib_uverbs` 드라이버는 UCAP 파일 디스크립터를 인식해 해당 IB 장치에 대응 기능을 활성화합니다.

=================================
Infiniband Userspace Capabilities
=================================

   User CAPabilities (UCAPs) provide fine-grained control over specific
   firmware features in Infiniband (IB) devices. This approach offers
   more granular capabilities than the existing Linux capabilities,
   which may be too generic for certain FW features.

   Each user capability is represented as a character device with root
   read-write access. Root processes can grant users special privileges
   by allowing access to these character devices (e.g., using chown).

Usage
=====

   UCAPs allow control over specific features of an IB device using file
   descriptors of UCAP character devices. Here is how a user enables
   specific features of an IB device:

      * A root process grants the user access to the UCAP files that
        represents the capabilities (e.g., using chown).
      * The user opens the UCAP files, obtaining file descriptors.
      * When opening an IB device, include an array of the UCAP file
        descriptors as an attribute.
      * The ib_uverbs driver recognizes the UCAP file descriptors and enables
        the corresponding capabilities for the IB device.

UCAP 생성·참조 계수·제거

새 UCAP을 만들려면 드라이버가 먼저 `rdma/ib_ucaps.h`의 `rdma_user_cap` 열거형에 유형을 정의해야 합니다. 문자 장치 이름은 `drivers/infiniband/core/ucaps.c`의 `ucap_names` 배열에 추가합니다. 이후 UCAP 유형을 인자로 `ib_create_ucap` API를 호출해 문자 장치를 생성합니다.

각 UCAP에는 생성과 제거를 추적하는 참조 계수가 저장됩니다. 같은 유형을 여러 IB 장치에서 생성하면 첫 호출에서만 실제 문자 장치를 만들고, 이후 호출은 참조 계수만 증가시킵니다.

UCAP 문자 장치는 `/dev/infiniband` 아래에 생성되며 기본 권한은 root 읽기·쓰기 전용입니다. 제거 호출마다 참조 계수가 하나 줄고, 계수가 0이 된 경우에만 파일시스템에서 문자 장치를 제거합니다.

Creating UCAPs
==============

   To create a new UCAP, drivers must first define a type in the
   rdma_user_cap enum in rdma/ib_ucaps.h. The name of the UCAP character
   device should be added to the ucap_names array in
   drivers/infiniband/core/ucaps.c. Then, the driver can create the UCAP
   character device by calling the ib_create_ucap API with the UCAP
   type.

   A reference count is stored for each UCAP to track creations and
   removals of the UCAP device. If multiple creation calls are made with
   the same type (e.g., for two IB devices), the UCAP character device
   is created during the first call and subsequent calls increment the
   reference count.

   The UCAP character device is created under /dev/infiniband, and its
   permissions are set to allow root read and write access only.

Removing UCAPs
==============

   Each removal decrements the reference count of the UCAP. The UCAP
   character device is removed from the filesystem only when the
   reference count is decreased to 0.

UCAP /dev 노드와 sysfs 클래스

첫 UCAP 문자 장치가 생성되면 `/sys/class/infiniband_ucaps` 클래스가 만들어집니다. 개별 UCAP 문자 장치는 `/dev/infiniband` 아래에 위치합니다.

예를 들어 `mlx5_ib`가 이름이 `mlx5_perm_ctrl_local`인 `RDMA_UCAP_MLX5_CTRL_LOCAL` capability를 추가하면 `/dev/infiniband/mlx5_perm_ctrl_local` 장치 노드가 생성됩니다.

/dev and /sys/class files
=========================

   The class::

      /sys/class/infiniband_ucaps

   is created when the first UCAP character device is created.

   The UCAP character device is created under /dev/infiniband.

   For example, if mlx5_ib adds the rdma_user_cap
   RDMA_UCAP_MLX5_CTRL_LOCAL with name "mlx5_perm_ctrl_local", this will
   create the device node::

      /dev/infiniband/mlx5_perm_ctrl_local