libhns: Add hns direct verbs man pages

Document hns direct verbs feature.

Signed-off-by: Junxian Huang <[email protected]>

CMakeLists.txt

@@ -737,6 +737,7 @@ add_subdirectory(providers/efa)
 add_subdirectory(providers/efa/man)
 add_subdirectory(providers/erdma)
 add_subdirectory(providers/hns)
+add_subdirectory(providers/hns/man)
 add_subdirectory(providers/irdma)
 add_subdirectory(providers/mana)
 add_subdirectory(providers/mana/man)

debian/libibverbs-dev.install

@@ -29,13 +29,15 @@ usr/lib/*/pkgconfig/libmana.pc
 usr/lib/*/pkgconfig/libmlx4.pc
 usr/lib/*/pkgconfig/libmlx5.pc
 usr/share/man/man3/efadv_*.3
+usr/share/man/man3/hnsdv_*.3
 usr/share/man/man3/ibv_*
 usr/share/man/man3/mbps_to_ibv_rate.3
 usr/share/man/man3/manadv_*.3
 usr/share/man/man3/mlx4dv_*.3
 usr/share/man/man3/mlx5dv_*.3
 usr/share/man/man3/mult_to_ibv_rate.3
 usr/share/man/man7/efadv.7
+usr/share/man/man7/hnsdv.7
 usr/share/man/man7/manadv.7
 usr/share/man/man7/mlx4dv.7
 usr/share/man/man7/mlx5dv.7

providers/hns/man/CMakeLists.txt

@@ -0,0 +1,6 @@
+rdma_man_pages(
+ hnsdv.7.md
+ hnsdv_create_qp.3.md
+ hnsdv_is_supported.3.md
+ hnsdv_query_device.3.md
+)

providers/hns/man/hnsdv.7.md

@@ -0,0 +1,38 @@
+---
+layout: page
+title: HNSDV
+section: 7
+tagline: Verbs
+date: 2024-02-06
+header: "HNS Direct Verbs Manual"
+footer: hns
+---
+
+# NAME
+
+hnsdv \- Direct verbs for hns devices
+
+This provides low level access to hns devices to perform direct operations,
+without general branching performed by libibverbs.
+
+# DESCRIPTION
+The libibverbs API is an abstract one. It is agnostic to any underlying
+provider specific implementation. While this abstraction has the advantage
+of user applications portability it has a performance penalty. Besides,
+some provider specific features that are directly facing users are not
+available through libibverbs. For some applications these demands are more
+important than portability.
+
+The hns direct verbs API is intended for such applications.
+It exposes hns specific low level operations, allowing the application
+to bypass the libibverbs API and enable some hns specific features.
+
+The direct include of hnsdv.h together with linkage to hns library will allow
+usage of this new interface.
+
+# SEE ALSO
+**verbs**(7)
+
+# AUTHORS
+
+Junxian Huang <[email protected]>

providers/hns/man/hnsdv_create_qp.3.md

@@ -0,0 +1,76 @@
+---
+layout: page
+title: HNSDV_CREATE_QP
+section: 3
+tagline: Verbs
+date: 2024-02-06
+header: "HNS Programmer's Manual"
+footer: hns
+---
+
+# NAME
+
+hnsdv_create_qp - creates a HNS specific queue pair (QP)
+
+# SYNOPSIS
+
+```c
+#include <infiniband/hnsdv.h>
+
+struct ibv_qp *hnsdv_create_qp(struct ibv_context *context,
+ struct ibv_qp_init_attr_ex *qp_attr,
+ struct hnsdv_qp_init_attr *hns_attr);
+```
+
+# DESCRIPTION
+
+**hnsdv_create_qp()** creates a HNS specific queue pair (QP) with specific driver properties.
+
+# ARGUMENTS
+Please see *ibv_create_qp_ex(3)* man page for *context* and *qp_attr*.
+
+## hns_attr
+
+```c
+struct hnsdv_qp_init_attr {
+ uint64_t comp_mask;
+ uint32_t create_flags;
+ uint8_t congest_type;
+ uint8_t reserved[3];
+};
+```
+*comp_mask*
+: Bitmask specifying what fields in the structure are valid:
+
+```
+HNSDV_QP_INIT_ATTR_MASK_QP_CONGEST_TYPE:
+ Valid values in congest_type. Allow setting a congestion control algorithm for QP.
+```
+
+*create_flags*
+: Enable the QP of a feature.
+
+*congest_type*
+: Type of congestion control algorithm:
+
+ HNSDV_QP_CREATE_ENABLE_DCQCN:
+  Data Center Quantized Congestion Notification
+ HNSDV_QP_CREATE_ENABLE_LDCP:
+  Low Delay Control Protocol
+ HNSDV_QP_CREATE_ENABLE_HC3:
+  Huawei Converged Congestion Control
+ HNSDV_QP_CREATE_ENABLE_DIP:
+  Destination IP based Quantized Congestion Notification
+
+# RETURN VALUE
+
+**hnsdv_create_qp()**
+returns a pointer to the created QP, on error NULL will be returned and errno will be set.
+
+# SEE ALSO
+
+**ibv_create_qp_ex**(3)
+
+# AUTHOR
+
+Junxian Huang <[email protected]>

providers/hns/man/hnsdv_is_supported.3.md

@@ -0,0 +1,41 @@
+---
+layout: page
+title: HNSDV_IS_SUPPORTED
+section: 3
+tagline: Verbs
+date: 2024-02-06
+header: "HNS Programmer's Manual"
+footer: hns
+---
+
+# NAME
+
+hnsdv_is_supported - Check whether an RDMA device implemented by the hns provider
+
+# SYNOPSIS
+
+```c
+#include <infiniband/hnsdv.h>
+
+bool hnsdv_is_supported(struct ibv_device *device);
+```
+
+# DESCRIPTION
+
+hnsdv functions may be called only if this function returns true for the RDMA device.
+
+# ARGUMENTS
+
+*device*
+: RDMA device to check.
+
+# RETURN VALUE
+Returns true if device is implemented by hns provider.
+
+# SEE ALSO
+
+*hnsdv(7)*
+
+# AUTHOR
+
+Junxian Huang <[email protected]>

providers/hns/man/hnsdv_query_device.3.md

@@ -0,0 +1,75 @@
+---
+layout: page
+title: HNSDV_QUERY_DEVICE
+section: 3
+tagline: Verbs
+date: 2024-02-06
+header: "HNS Direct Verbs Manual"
+footer: hns
+---
+
+# NAME
+
+hnsdv_query_device - Query hns device specific attributes
+
+# SYNOPSIS
+
+```c
+#include <infiniband/hnsdv.h>
+int hnsdv_query_device(struct ibv_context *context,
+ struct hnsdv_context *attrs_out);
+```
+
+# DESCRIPTION
+
+**hnsdv_query_device()** Queries hns device specific attributes.
+
+# ARGUMENTS
+
+Please see *ibv_query_device(3)* man page for *context*.
+
+## attrs_out
+
+```c
+struct hnsdv_context {
+ uint64_t comp_mask;
+ uint64_t flags;
+ uint8_t congest_type;
+ uint8_t reserved[7];
+};
+```
+
+*comp_mask*
+: Bitmask specifying what fields in the structure are valid:
+
+ HNSDV_CONTEXT_MASK_CONGEST_TYPE:
+  Congestion control algorithm is supported.
+
+*congest_type*
+: Bitmask of supported congestion control algorithms.
+
+ HNSDV_QP_CREATE_ENABLE_DCQCN:
+  Data Center Quantized Congestion Notification
+ HNSDV_QP_CREATE_ENABLE_LDCP:
+  Low Delay Control Protocol
+ HNSDV_QP_CREATE_ENABLE_HC3:
+  Huawei Converged Congestion Control
+ HNSDV_QP_CREATE_ENABLE_DIP:
+  Destination IP based Quantized Congestion Notification
+
+# RETURN VALUE
+
+**hnsdv_query_device()** returns 0 on success, or the value of errno on failure
+(which indicates the failure reason).
+
+# SEE ALSO
+
+**ibv_query_device**(3)
+
+# NOTES
+
+* *flags* is an out field and currently has no values.
+
+# AUTHORS
+
+Junxian Huang <[email protected]>

redhat/rdma-core.spec

@@ -448,6 +448,7 @@ fi
 %{_libdir}/lib*.so
 %{_libdir}/pkgconfig/*.pc
 %{_mandir}/man3/efadv*
+%{_mandir}/man3/hnsdv*
 %{_mandir}/man3/ibv_*
 %{_mandir}/man3/rdma*
 %{_mandir}/man3/umad*
@@ -457,6 +458,7 @@ fi
 %{_mandir}/man3/mlx5dv*
 %{_mandir}/man3/mlx4dv*
 %{_mandir}/man7/efadv*
+%{_mandir}/man7/hnsdv*
 %{_mandir}/man7/manadv*
 %{_mandir}/man7/mlx5dv*
 %{_mandir}/man7/mlx4dv*

suse/rdma-core.spec

@@ -668,10 +668,12 @@ done
 %{_mandir}/man7/rdma_cm.*
 %if 0%{?dma_coherent}
 %{_mandir}/man3/efadv*
+%{_mandir}/man3/hnsdv*
 %{_mandir}/man3/manadv*
 %{_mandir}/man3/mlx5dv*
 %{_mandir}/man3/mlx4dv*
 %{_mandir}/man7/efadv*
+%{_mandir}/man7/hnsdv*
 %{_mandir}/man7/manadv*
 %{_mandir}/man7/mlx5dv*
 %{_mandir}/man7/mlx4dv*