From 2ecc81c5b3e90b2d0dcd83cb905769a7303fc19e Mon Sep 17 00:00:00 2001 From: Junxian Huang Date: Tue, 5 Mar 2024 13:57:21 +0800 Subject: [PATCH] libhns: Add hns direct verbs man pages Document hns direct verbs feature. Signed-off-by: Junxian Huang --- CMakeLists.txt | 1 + debian/libibverbs-dev.install | 2 + providers/hns/man/CMakeLists.txt | 6 ++ providers/hns/man/hnsdv.7.md | 38 ++++++++++++ providers/hns/man/hnsdv_create_qp.3.md | 76 +++++++++++++++++++++++ providers/hns/man/hnsdv_is_supported.3.md | 41 ++++++++++++ providers/hns/man/hnsdv_query_device.3.md | 75 ++++++++++++++++++++++ redhat/rdma-core.spec | 2 + suse/rdma-core.spec | 2 + 9 files changed, 243 insertions(+) create mode 100644 providers/hns/man/CMakeLists.txt create mode 100644 providers/hns/man/hnsdv.7.md create mode 100644 providers/hns/man/hnsdv_create_qp.3.md create mode 100644 providers/hns/man/hnsdv_is_supported.3.md create mode 100644 providers/hns/man/hnsdv_query_device.3.md diff --git a/CMakeLists.txt b/CMakeLists.txt index b68c04dc3..f326183fc 100644 --- a/CMakeLists.txt +++ b/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) diff --git a/debian/libibverbs-dev.install b/debian/libibverbs-dev.install index 5f2ffd55b..d882ada59 100644 --- a/debian/libibverbs-dev.install +++ b/debian/libibverbs-dev.install @@ -29,6 +29,7 @@ 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 @@ -36,6 +37,7 @@ 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 diff --git a/providers/hns/man/CMakeLists.txt b/providers/hns/man/CMakeLists.txt new file mode 100644 index 000000000..51e02f4cc --- /dev/null +++ b/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 +) diff --git a/providers/hns/man/hnsdv.7.md b/providers/hns/man/hnsdv.7.md new file mode 100644 index 000000000..c4e8864b3 --- /dev/null +++ b/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 diff --git a/providers/hns/man/hnsdv_create_qp.3.md b/providers/hns/man/hnsdv_create_qp.3.md new file mode 100644 index 000000000..d9c60f478 --- /dev/null +++ b/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 + +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 diff --git a/providers/hns/man/hnsdv_is_supported.3.md b/providers/hns/man/hnsdv_is_supported.3.md new file mode 100644 index 000000000..8d578b941 --- /dev/null +++ b/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 + +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 diff --git a/providers/hns/man/hnsdv_query_device.3.md b/providers/hns/man/hnsdv_query_device.3.md new file mode 100644 index 000000000..6e3edeab7 --- /dev/null +++ b/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 +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 diff --git a/redhat/rdma-core.spec b/redhat/rdma-core.spec index fa6bb34e5..ded938350 100644 --- a/redhat/rdma-core.spec +++ b/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* diff --git a/suse/rdma-core.spec b/suse/rdma-core.spec index 6f6c21f78..076170308 100644 --- a/suse/rdma-core.spec +++ b/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*