tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: infiniband: document the UCAP API
Add an explanation on the newly added UCAP API.
Signed-off-by: Chiara Meiohas <cmeiohas@nvidia.com>
Link: https://patch.msgid.link/d0e095f9a7601437acc2d2fdf8705136d1edf1c5.1741261611.git.leon@kernel.org
Reviewed-by: Yishai Hadas <yishaih@nvidia.com>
Signed-off-by: Leon Romanovsky <leon@kernel.org>
authored by
Chiara Meiohas
and committed by
Leon Romanovsky
8820965c
74934ddf
+72
+1
Documentation/infiniband/index.rst
+1
Documentation/infiniband/index.rst
+71
Documentation/infiniband/ucaps.rst
+71
Documentation/infiniband/ucaps.rst
···
1
+
=================================
2
+
Infiniband 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
+
14
+
Usage
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
+
29
+
Creating 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
+
48
+
Removing 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
+