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