€•Î:      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ$/translations/zh_CN/infiniband/ucaps”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ$/translations/zh_TW/infiniband/ucaps”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ$/translations/it_IT/infiniband/ucaps”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ$/translations/ja_JP/infiniband/ucaps”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ$/translations/ko_KR/infiniband/ucaps”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒPortuguese (Brazilian)”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ$/translations/pt_BR/infiniband/ucaps”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh–sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ$/translations/sp_SP/infiniband/ucaps”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒ!Infiniband Userspace Capabilities”h]”hŒ!Infiniband Userspace Capabilities”…””}”(hh¼h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhh·h²hh³Œ>/var/lib/git/docbuild/linux/Documentation/infiniband/ucaps.rst”h´KubhŒblock_quote”“”)”}”(hXÈ  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).
”h]”(hŒ	paragraph”“”)”}”(hŒú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.”h]”hŒú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.”…””}”(hhÓh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÑh³hÊh´KhhÍubhÒ)”}”(hŒË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).”h]”hŒË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).”…””}”(hháh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÑh³hÊh´K
hhÍubeh}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´Khh·h²hubh¶)”}”(hhh]”(h»)”}”(hŒUsage”h]”hŒUsage”…””}”(hhøh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhhõh²hh³hÊh´KubhÌ)”}”(hXJ  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.
”h]”(hÒ)”}”(hŒª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:”h]”hŒª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:”…””}”(hj
  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÑh³hÊh´Khj  ubhÌ)”}”(hX‰  * 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.
”h]”hŒbullet_list”“”)”}”(hhh]”(hŒ	list_item”“”)”}”(hŒmA root process grants the user access to the UCAP files that
represents the capabilities (e.g., using chown).”h]”hÒ)”}”(hŒmA root process grants the user access to the UCAP files that
represents the capabilities (e.g., using chown).”h]”hŒmA root process grants the user access to the UCAP files that
represents the capabilities (e.g., using chown).”…””}”(hj'  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÑh³hÊh´Khj#  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j!  hj  ubj"  )”}”(hŒ:The user opens the UCAP files, obtaining file descriptors.”h]”hÒ)”}”(hj=  h]”hŒ:The user opens the UCAP files, obtaining file descriptors.”…””}”(hj?  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÑh³hÊh´Khj;  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j!  hj  ubj"  )”}”(hŒYWhen opening an IB device, include an array of the UCAP file
descriptors as an attribute.”h]”hÒ)”}”(hŒYWhen opening an IB device, include an array of the UCAP file
descriptors as an attribute.”h]”hŒYWhen opening an IB device, include an array of the UCAP file
descriptors as an attribute.”…””}”(hjV  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÑh³hÊh´KhjR  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j!  hj  ubj"  )”}”(hŒxThe ib_uverbs driver recognizes the UCAP file descriptors and enables
the corresponding capabilities for the IB device.
”h]”hÒ)”}”(hŒwThe ib_uverbs driver recognizes the UCAP file descriptors and enables
the corresponding capabilities for the IB device.”h]”hŒwThe ib_uverbs driver recognizes the UCAP file descriptors and enables
the corresponding capabilities for the IB device.”…””}”(hjn  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÑh³hÊh´Khjj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j!  hj  ubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ*”uh1j  h³hÊh´Khj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´Khj  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´Khhõh²hubeh}”(h]”Œusage”ah ]”h"]”Œusage”ah$]”h&]”uh1hµhh·h²hh³hÊh´Kubh¶)”}”(hhh]”(h»)”}”(hŒCreating UCAPs”h]”hŒCreating UCAPs”…””}”(hj¡  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhjž  h²hh³hÊh´KubhÌ)”}”(hXç  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.
”h]”(hÒ)”}”(hXB  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.”h]”hXB  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.”…””}”(hj³  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÑh³hÊh´K hj¯  ubhÒ)”}”(hX  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.”h]”hX  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.”…””}”(hjÁ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÑh³hÊh´K'hj¯  ubhÒ)”}”(hŒThe UCAP character device is created under /dev/infiniband, and its
permissions are set to allow root read and write access only.”h]”hŒThe UCAP character device is created under /dev/infiniband, and its
permissions are set to allow root read and write access only.”…””}”(hjÏ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÑh³hÊh´K-hj¯  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´K hjž  h²hubeh}”(h]”Œcreating-ucaps”ah ]”h"]”Œcreating ucaps”ah$]”h&]”uh1hµhh·h²hh³hÊh´Kubh¶)”}”(hhh]”(h»)”}”(hŒRemoving UCAPs”h]”hŒRemoving UCAPs”…””}”(hjî  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhjë  h²hh³hÊh´K1ubhÌ)”}”(hŒ£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.
”h]”hÒ)”}”(hŒ¢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.”h]”hŒ¢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.”…””}”(hj   h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÑh³hÊh´K3hjü  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´K3hjë  h²hubeh}”(h]”Œremoving-ucaps”ah ]”h"]”Œremoving ucaps”ah$]”h&]”uh1hµhh·h²hh³hÊh´K1ubh¶)”}”(hhh]”(h»)”}”(hŒ/dev and /sys/class files”h]”hŒ/dev and /sys/class files”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhj  h²hh³hÊh´K8ubhÌ)”}”(hX^  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
”h]”(hÒ)”}”(hŒThe class::”h]”hŒ
The class:”…””}”(hj1  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÑh³hÊh´K:hj-  ubhŒliteral_block”“”)”}”(hŒ/sys/class/infiniband_ucaps”h]”hŒ/sys/class/infiniband_ucaps”…””}”hjA  sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1j?  h³hÊh´K<hj-  ubhÒ)”}”(hŒ;is created when the first UCAP character device is created.”h]”hŒ;is created when the first UCAP character device is created.”…””}”(hjQ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÑh³hÊh´K>hj-  ubhÒ)”}”(hŒ;The UCAP character device is created under /dev/infiniband.”h]”hŒ;The UCAP character device is created under /dev/infiniband.”…””}”(hj_  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÑh³hÊh´K@hj-  ubhÒ)”}”(hŒ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::”h]”hŒ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:”…””}”(hjm  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÑh³hÊh´KBhj-  ubj@  )”}”(hŒ$/dev/infiniband/mlx5_perm_ctrl_local”h]”hŒ$/dev/infiniband/mlx5_perm_ctrl_local”…””}”hj{  sbah}”(h]”h ]”h"]”h$]”h&]”jO  jP  uh1j?  h³hÊh´KFhj-  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´K:hj  h²hubeh}”(h]”Œdev-and-sys-class-files”ah ]”h"]”Œ/dev and /sys/class files”ah$]”h&]”uh1hµhh·h²hh³hÊh´K8ubeh}”(h]”Œ!infiniband-userspace-capabilities”ah ]”h"]”Œ!infiniband userspace capabilities”ah$]”h&]”uh1hµhhh²hh³hÊh´Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”hÊuh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(hºNŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”Œentry”Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”jÂ  Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”hÊŒ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”Œnameids”}”(jœ  j™  j›  j˜  jè  jå  j  j  j”  j‘  uŒ	nametypes”}”(jœ  ‰j›  ‰jè  ‰j  ‰j”  ‰uh}”(j™  h·j˜  hõjå  jž  j  jë  j‘  j  uŒfootnote_refs”}”Œcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”Œ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nh²hub.