1=================================
2Infiniband Userspace Capabilities
3=================================
4
5   User CAPabilities (UCAPs) provide fine-grained control over specific
6   firmware features in Infiniband (IB) devices. This approach offers
7   more granular capabilities than the existing Linux capabilities,
8   which may be too generic for certain FW features.
9
10   Each user capability is represented as a character device with root
11   read-write access. Root processes can grant users special privileges
12   by allowing access to these character devices (e.g., using chown).
13
14Usage
15=====
16
17   UCAPs allow control over specific features of an IB device using file
18   descriptors of UCAP character devices. Here is how a user enables
19   specific features of an IB device:
20
21      * A root process grants the user access to the UCAP files that
22        represents the capabilities (e.g., using chown).
23      * The user opens the UCAP files, obtaining file descriptors.
24      * When opening an IB device, include an array of the UCAP file
25        descriptors as an attribute.
26      * The ib_uverbs driver recognizes the UCAP file descriptors and enables
27        the corresponding capabilities for the IB device.
28
29Creating UCAPs
30==============
31
32   To create a new UCAP, drivers must first define a type in the
33   rdma_user_cap enum in rdma/ib_ucaps.h. The name of the UCAP character
34   device should be added to the ucap_names array in
35   drivers/infiniband/core/ucaps.c. Then, the driver can create the UCAP
36   character device by calling the ib_create_ucap API with the UCAP
37   type.
38
39   A reference count is stored for each UCAP to track creations and
40   removals of the UCAP device. If multiple creation calls are made with
41   the same type (e.g., for two IB devices), the UCAP character device
42   is created during the first call and subsequent calls increment the
43   reference count.
44
45   The UCAP character device is created under /dev/infiniband, and its
46   permissions are set to allow root read and write access only.
47
48Removing UCAPs
49==============
50
51   Each removal decrements the reference count of the UCAP. The UCAP
52   character device is removed from the filesystem only when the
53   reference count is decreased to 0.
54
55/dev and /sys/class files
56=========================
57
58   The class::
59
60      /sys/class/infiniband_ucaps
61
62   is created when the first UCAP character device is created.
63
64   The UCAP character device is created under /dev/infiniband.
65
66   For example, if mlx5_ib adds the rdma_user_cap
67   RDMA_UCAP_MLX5_CTRL_LOCAL with name "mlx5_perm_ctrl_local", this will
68   create the device node::
69
70      /dev/infiniband/mlx5_perm_ctrl_local
71
72