Google Git Google Git
Sign in
third-party-mirror/linux-rdma/rdma-core/76bd0b4e2708ecd3e9918becffe5b581edaa3a11^!/.
commit
76bd0b4e2708ecd3e9918becffe5b581edaa3a11
[log]
author
Sriharsha Basavapatna <sriharsha.basavapatna@broadcom.com>
Mon Mar 23 15:49:05 2026 +0530
committer
Selvin Xavier <selvin.xavier@broadcom.com>
Fri Oct 09 04:45:16 2026 -0700
tree
897dd707fa3e9935c33dd3c15caf14db8cc31a9e
parent
56a228452aa3eb25ea33504cf89afcd166dc39a4 [diff] 
bnxt_re/lib: Direct Verbs: Add man pages

Document direct verbs (DV) feature and related DV APIs.
The man page describes these DV APIs:
- Doorbell regions (db)
- Completion Queues (cq)
- Queue pairs (qp)

Signed-off-by: Sriharsha Basavapatna <sriharsha.basavapatna@broadcom.com>
Reviewed-by: Selvin Xavier <selvin.xavier@broadcom.com>

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 3ccd87f..0071766 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt

@@ -804,6 +804,7 @@
 # Providers
 if (HAVE_COHERENT_DMA)
 add_subdirectory(providers/bnxt_re)
+add_subdirectory(providers/bnxt_re/man)
 add_subdirectory(providers/cxgb4) # NO SPARSE
 add_subdirectory(providers/efa)
 add_subdirectory(providers/efa/man)

diff --git a/debian/libibverbs-dev.install b/debian/libibverbs-dev.install
index 065c9ec..ecf6d36 100644
--- a/debian/libibverbs-dev.install
+++ b/debian/libibverbs-dev.install

@@ -41,6 +41,7 @@
 usr/lib/*/pkgconfig/libmana.pc
 usr/lib/*/pkgconfig/libmlx4.pc
 usr/lib/*/pkgconfig/libmlx5.pc
+usr/share/man/man3/bnxt_re_dv*.3
 usr/share/man/man3/efadv_*.3
 usr/share/man/man3/hnsdv_*.3
 usr/share/man/man3/ibv_*
@@ -50,6 +51,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/bnxt_re_dv.7
 usr/share/man/man7/efadv.7
 usr/share/man/man7/hnsdv.7
 usr/share/man/man7/ionicdv.7

diff --git a/providers/bnxt_re/man/CMakeLists.txt b/providers/bnxt_re/man/CMakeLists.txt
new file mode 100644
index 0000000..6e4637d
--- /dev/null
+++ b/providers/bnxt_re/man/CMakeLists.txt

@@ -0,0 +1,8 @@
+rdma_man_pages(
+  bnxt_re_dv.7.md
+  bnxt_re_dv_alloc_db_region.3.md
+  bnxt_re_dv_free_db_region.3.md
+  bnxt_re_dv_get_default_db_region.3.md
+  bnxt_re_dv_create_cq.3.md
+  bnxt_re_dv_create_qp.3.md
+)

diff --git a/providers/bnxt_re/man/bnxt_re_dv.7.md b/providers/bnxt_re/man/bnxt_re_dv.7.md
new file mode 100644
index 0000000..a8701fd
--- /dev/null
+++ b/providers/bnxt_re/man/bnxt_re_dv.7.md

@@ -0,0 +1,68 @@
+---
+layout: page
+title: BNXT_RE_DV
+section: 7
+tagline: Verbs
+date: 2025-06-17
+header: "Broadcom BNXT-RE Direct Verbs Manual"
+footer: bnxt_re
+---
+
+# NAME
+
+bnxt_re_dv - Direct verbs for Broadcom RoCE (bnxt_re) devices
+
+# DESCRIPTION
+
+The libibverbs API is abstract and portable. For workloads that need to
+manage some of the RDMA HW resources directly, the bnxt_re provider
+exposes **direct verbs**. These are driver-specific routines that work
+together with user-registered queue memory and optional doorbell regions.
+
+To use these new interfaces, include `<infiniband/bnxt_re_dv.h>` and link
+against **libbnxt_re** (in addition to **libibverbs**).
+
+The following Direct Verbs are supported:
+
+**Doorbell regions**
+
+- **bnxt_re_dv_alloc_db_region**(3), **bnxt_re_dv_free_db_region**(3) allocate
+  and release extra doorbell mapping regions.
+- **bnxt_re_dv_get_default_db_region**(3) returns the default doorbell page index
+  and user-mapped doorbell address for the context.
+
+**Completion queues**
+
+- **bnxt_re_dv_create_cq**(3) creates a CQ backed by a prior
+  **ibv_alloc_user_buf**(3) handle and offset. Such a CQ is destroyed like any
+  other CQ, using **ibv_destroy_cq**(3).
+
+Applications may create one large buffer with **ibv_alloc_user_buf**(3) and
+pass different offsets (aligned to the device page size) and lengths when
+creating individual CQs or QP rings.
+
+**Queue pairs**
+
+- **bnxt_re_dv_create_qp**(3) creates a QP whose SQ and RQ rings are backed by
+  prior **ibv_alloc_user_buf**(3) handles and offsets. An optional doorbell
+  region from **bnxt_re_dv_alloc_db_region**(3) may be supplied; if omitted
+  the context default is used. Such a QP is destroyed like any other QP,
+  using **ibv_destroy_qp**(3). Its attributes are modified using the standard
+  **ibv_modify_qp**(3).
+
+# SEE ALSO
+
+**verbs**(7),
+**bnxt_re_dv_alloc_db_region**(3),
+**bnxt_re_dv_free_db_region**(3),
+**bnxt_re_dv_get_default_db_region**(3),
+**bnxt_re_dv_create_cq**(3),
+**bnxt_re_dv_create_qp**(3),
+**ibv_alloc_user_buf**(3),
+**ibv_modify_qp**(3)
+
+# AUTHORS
+
+Kalesh AP \<kalesh-anakkur.purayil@broadcom.com\>,
+Sriharsha Basavapatna \<sriharsha.basavapatna@broadcom.com\>,
+Selvin Xavier \<selvin.xavier@broadcom.com\>

diff --git a/providers/bnxt_re/man/bnxt_re_dv_alloc_db_region.3.md b/providers/bnxt_re/man/bnxt_re_dv_alloc_db_region.3.md
new file mode 100644
index 0000000..3fd7d3b
--- /dev/null
+++ b/providers/bnxt_re/man/bnxt_re_dv_alloc_db_region.3.md

@@ -0,0 +1,63 @@
+---
+layout: page
+title: bnxt_re_dv_alloc_db_region
+section: 3
+tagline: Verbs
+date: 2025-06-17
+header: "Broadcom BNXT-RE Direct Verbs Manual"
+footer: bnxt_re
+---
+
+# NAME
+
+bnxt_re_dv_alloc_db_region - allocate an additional doorbell region
+
+# SYNOPSIS
+
+```c
+#include <infiniband/bnxt_re_dv.h>
+
+struct bnxt_re_dv_db_region_attr *
+bnxt_re_dv_alloc_db_region(struct ibv_context *ctx);
+```
+
+# DESCRIPTION
+
+**bnxt_re_dv_alloc_db_region**() allocates a new doorbell region for *ctx*.
+The kernel returns a doorbell region handle and attributes; the library
+memory-maps the doorbell page so the application can post doorbells using the
+returned mapping.
+
+The returned pointer must be released with **bnxt_re_dv_free_db_region**(3).
+
+# ARGUMENTS
+
+*ctx*
+:   Verbs device context returned by **ibv_open_device**(3). Identifies the
+    device instance on which the new doorbell region is allocated.
+
+# RETURN VALUE
+
+On success, returns a pointer to a **struct bnxt_re_dv_db_region_attr**
+with all fields filled in:
+
+```c
+struct bnxt_re_dv_db_region_attr {
+        uint32_t  handle;   /* kernel handle for this doorbell region */
+        uint32_t  dpi;      /* doorbell page index */
+        uint64_t *dbr;      /* mapped doorbell page (user virtual address) */
+};
+```
+
+On failure, returns NULL and sets errno.
+
+# SEE ALSO
+
+**bnxt_re_dv**(7),
+**bnxt_re_dv_free_db_region**(3),
+**bnxt_re_dv_get_default_db_region**(3),
+**ibv_open_device**(3)
+
+# AUTHOR
+
+Kalesh AP \<kalesh-anakkur.purayil@broadcom.com\>

diff --git a/providers/bnxt_re/man/bnxt_re_dv_create_cq.3.md b/providers/bnxt_re/man/bnxt_re_dv_create_cq.3.md
new file mode 100644
index 0000000..6335a21
--- /dev/null
+++ b/providers/bnxt_re/man/bnxt_re_dv_create_cq.3.md

@@ -0,0 +1,59 @@
+---
+layout: page
+title: bnxt_re_dv_create_cq
+section: 3
+tagline: Verbs
+date: 2025-06-17
+header: "Broadcom BNXT-RE Direct Verbs Manual"
+footer: bnxt_re
+---
+
+# NAME
+
+bnxt_re_dv_create_cq - create a completion queue using application-provided memory
+
+# SYNOPSIS
+
+```c
+#include <infiniband/bnxt_re_dv.h>
+
+struct ibv_cq *bnxt_re_dv_create_cq(struct ibv_context *ibvctx,
+				    struct bnxt_re_dv_cq_init_attr *cq_attr);
+
+struct bnxt_re_dv_cq_init_attr {
+	struct ibv_buf *umem_handle; /* handle from ibv_alloc_user_buf() */
+	uint64_t        umem_offset; /* byte offset into umem, page-aligned */
+	uint32_t        ncqe;        /* number of CQ entries requested */
+};
+```
+
+# DESCRIPTION
+
+**bnxt_re_dv_create_cq**() creates a completion queue using memory described
+by **ibv_alloc_user_buf**(3). The **umem_handle** field must be the handle
+returned by that function; **umem_offset** is the byte offset into that
+buffer, aligned to the device page size; **ncqe** is the requested number
+of CQEs.
+
+This call requires Linux kernel 7.2 or later; on older kernels it fails.
+
+A CQ created this way is destroyed like any other CQ, using
+**ibv_destroy_cq**(3).
+
+# RETURN VALUE
+
+Returns a pointer to the created **ibv_cq** on success, or NULL on failure with
+errno set.
+
+# SEE ALSO
+
+**bnxt_re_dv**(7),
+**ibv_alloc_user_buf**(3),
+**ibv_create_cq**(3),
+**ibv_destroy_cq**(3)
+
+# AUTHORS
+
+Sriharsha Basavapatna \<sriharsha.basavapatna@broadcom.com\>,
+Kalesh AP \<kalesh-anakkur.purayil@broadcom.com\>,
+Selvin Xavier \<selvin.xavier@broadcom.com\>

diff --git a/providers/bnxt_re/man/bnxt_re_dv_create_qp.3.md b/providers/bnxt_re/man/bnxt_re_dv_create_qp.3.md
new file mode 100644
index 0000000..a4fbfa0
--- /dev/null
+++ b/providers/bnxt_re/man/bnxt_re_dv_create_qp.3.md

@@ -0,0 +1,100 @@
+---
+layout: page
+title: bnxt_re_dv_create_qp
+section: 3
+tagline: Verbs
+date: 2026-06-05
+header: "Broadcom BNXT-RE Direct Verbs Manual"
+footer: bnxt_re
+---
+
+# NAME
+
+bnxt_re_dv_create_qp - create a queue pair using application-provided memory
+
+# SYNOPSIS
+
+```c
+#include <infiniband/bnxt_re_dv.h>
+
+struct ibv_qp *bnxt_re_dv_create_qp(struct ibv_pd *pd,
+                                    struct bnxt_re_dv_qp_init_attr *qp_attr);
+
+struct bnxt_re_dv_qp_init_attr {
+    /* Standard ibv parameters */
+    enum ibv_qp_type  qp_type;
+    uint32_t          max_send_wr;
+    uint32_t          max_recv_wr;
+    uint32_t          max_send_sge;
+    uint32_t          max_recv_sge;
+    uint32_t          max_inline_data;
+    struct ibv_cq    *send_cq;
+    struct ibv_cq    *recv_cq;
+    struct ibv_srq   *srq;           /* NULL if not using an SRQ */
+
+    /* Direct verbs parameters */
+    uint64_t          qp_handle;         /* opaque handle embedded in CQEs */
+    void             *dbr_handle;        /* bnxt_re_dv_alloc_db_region() handle,
+                                            or NULL for the context default */
+    struct ibv_buf   *sq_umem_handle;    /* handle from ibv_alloc_user_buf() */
+    uint64_t          sq_umem_offset;    /* byte offset into SQ umem, page-aligned */
+    uint32_t          sq_len;            /* SQ ring length in bytes (incl. MSN area) */
+    uint32_t          sq_slots;          /* SQ depth in WQE slots */
+    uint32_t          sq_npsn;           /* number of PSN entries */
+    struct ibv_buf   *rq_umem_handle;    /* handle from ibv_alloc_user_buf() */
+    uint64_t          rq_umem_offset;    /* byte offset into RQ umem, page-aligned */
+    uint32_t          rq_len;            /* RQ ring length in bytes */
+    uint64_t          comp_mask;         /* reserved, set to 0 */
+};
+```
+
+# DESCRIPTION
+
+**bnxt_re_dv_create_qp**() creates a queue pair whose send queue (SQ) and
+receive queue (RQ) rings are backed by memory described by
+**ibv_alloc_user_buf**(3). This allows the application to manage QP ring
+memory directly.
+
+**qp_handle** is an opaque value set by the library on successful return. It
+is embedded in completion queue entries (CQEs) so the application can
+correlate completions back to this QP. The application must not set this
+field before the call; it is populated by the library.
+
+**sq_umem_handle** must be a handle returned by **ibv_alloc_user_buf**(3).
+**sq_umem_offset** is the page-aligned byte offset into that buffer
+where the SQ ring starts. **sq_len** must cover the full ring including the
+MSN (message sequence number) area. **sq_slots** is the SQ depth in WQE
+slots and **sq_npsn** is the number of PSN entries; both must be set by the
+application based on the ring memory it has allocated.
+
+**rq_umem_handle** must be a handle returned by **ibv_alloc_user_buf**(3)
+for the RQ ring. If **srq** is set, **rq_umem_handle** and **rq_umem_offset**
+are ignored.
+
+If **dbr_handle** is NULL, the context's default doorbell page is used.
+Otherwise it must be a pointer returned by **bnxt_re_dv_alloc_db_region**(3).
+
+This call requires Linux kernel 7.2 or later when **sq_umem_handle** is
+provided; on older kernels it fails.
+
+A QP created this way is destroyed like any other QP, using
+**ibv_destroy_qp**(3).
+
+# RETURN VALUE
+
+Returns a pointer to the created **ibv_qp** on success, or NULL on failure
+with errno set.
+
+# SEE ALSO
+
+**bnxt_re_dv**(7),
+**ibv_alloc_user_buf**(3),
+**bnxt_re_dv_alloc_db_region**(3),
+**ibv_create_qp**(3),
+**ibv_destroy_qp**(3),
+**ibv_modify_qp**(3)
+
+# AUTHORS
+
+Sriharsha Basavapatna \<sriharsha.basavapatna@broadcom.com\>,
+Selvin Xavier \<selvin.xavier@broadcom.com\>

diff --git a/providers/bnxt_re/man/bnxt_re_dv_free_db_region.3.md b/providers/bnxt_re/man/bnxt_re_dv_free_db_region.3.md
new file mode 100644
index 0000000..fb3bcc7
--- /dev/null
+++ b/providers/bnxt_re/man/bnxt_re_dv_free_db_region.3.md

@@ -0,0 +1,46 @@
+---
+layout: page
+title: bnxt_re_dv_free_db_region
+section: 3
+tagline: Verbs
+date: 2025-06-17
+header: "Broadcom BNXT-RE Direct Verbs Manual"
+footer: bnxt_re
+---
+
+# NAME
+
+bnxt_re_dv_free_db_region - free a doorbell region allocated with bnxt_re_dv_alloc_db_region
+
+# SYNOPSIS
+
+```c
+#include <infiniband/bnxt_re_dv.h>
+
+int bnxt_re_dv_free_db_region(struct ibv_context *ctx,
+			      struct bnxt_re_dv_db_region_attr *attr);
+```
+
+# DESCRIPTION
+
+**bnxt_re_dv_free_db_region**() unmmaps the doorbell page, requests the driver to
+free the region identified by *attr*, and frees the **bnxt_re_dv_db_region_attr**
+structure.
+
+*attr* must be the pointer returned by **bnxt_re_dv_alloc_db_region**(3) for the
+same *ctx*.
+
+# RETURN VALUE
+
+Returns 0 on success. On ioctl failure returns a non-zero error value and sets
+**errno** to that value.
+
+# SEE ALSO
+
+**bnxt_re_dv**(7),
+**bnxt_re_dv_alloc_db_region**(3),
+**bnxt_re_dv_get_default_db_region**(3)
+
+# AUTHOR
+
+Kalesh AP \<kalesh-anakkur.purayil@broadcom.com\>

diff --git a/providers/bnxt_re/man/bnxt_re_dv_get_default_db_region.3.md b/providers/bnxt_re/man/bnxt_re_dv_get_default_db_region.3.md
new file mode 100644
index 0000000..c233390
--- /dev/null
+++ b/providers/bnxt_re/man/bnxt_re_dv_get_default_db_region.3.md

@@ -0,0 +1,53 @@
+---
+layout: page
+title: bnxt_re_dv_get_default_db_region
+section: 3
+tagline: Verbs
+date: 2025-06-17
+header: "Broadcom BNXT-RE Direct Verbs Manual"
+footer: bnxt_re
+---
+
+# NAME
+
+bnxt_re_dv_get_default_db_region - query the default doorbell region for a context
+
+# SYNOPSIS
+
+```c
+#include <infiniband/bnxt_re_dv.h>
+
+int bnxt_re_dv_get_default_db_region(struct ibv_context *ibvctx,
+				     struct bnxt_re_dv_db_region_attr *out);
+```
+
+# DESCRIPTION
+
+**bnxt_re_dv_get_default_db_region**() fills *out* with the default doorbell page
+index (**dpi**) and a pointer (**dbr**) to the user-mapped doorbell page
+already associated with the **ibv_context**.
+
+Unlike **bnxt_re_dv_alloc_db_region**(3), this does not allocate a new region.
+
+# ARGUMENTS
+
+*out*
+:	Output structure; **handle** is not used for the default region; **dbr**
+	and **dpi** are valid on success.
+	For the definition of **struct bnxt_re_dv_db_region_attr** and its members, see
+	**bnxt_re_dv_alloc_db_region**(3).
+
+# RETURN VALUE
+
+Returns 0 on success, or a negative error code on failure.
+
+# SEE ALSO
+
+**bnxt_re_dv**(7),
+**bnxt_re_dv_alloc_db_region**(3),
+**bnxt_re_dv_free_db_region**(3),
+**ibv_open_device**(3)
+
+# AUTHOR
+
+Kalesh AP \<kalesh-anakkur.purayil@broadcom.com\>

diff --git a/redhat/rdma-core.spec b/redhat/rdma-core.spec
index c088269..6cc9e1f 100644
--- a/redhat/rdma-core.spec
+++ b/redhat/rdma-core.spec

@@ -468,6 +468,7 @@
 %endif
 %{_libdir}/lib*.so
 %{_libdir}/pkgconfig/*.pc
+%{_mandir}/man3/bnxt_re_dv*
 %{_mandir}/man3/efadv*
 %{_mandir}/man3/hnsdv*
 %{_mandir}/man3/ibv_*
@@ -480,6 +481,7 @@
 %{_mandir}/man3/manadv*
 %{_mandir}/man3/mlx5dv*
 %{_mandir}/man3/mlx4dv*
+%{_mandir}/man7/bnxt_re_dv*
 %{_mandir}/man7/efadv*
 %{_mandir}/man7/hnsdv*
 %{_mandir}/man7/ionicdv*

diff --git a/suse/rdma-core.spec b/suse/rdma-core.spec
index fbd776b..a9290a2 100644
--- a/suse/rdma-core.spec
+++ b/suse/rdma-core.spec

@@ -696,12 +696,14 @@
 %{_mandir}/man3/*_to_ibv_rate.*
 %{_mandir}/man7/rdma_cm.*
 %if 0%{?dma_coherent}
+%{_mandir}/man3/bnxt_re_dv*
 %{_mandir}/man3/efadv*
 %{_mandir}/man3/hnsdv*
 %{_mandir}/man3/ionic_dv*
 %{_mandir}/man3/manadv*
 %{_mandir}/man3/mlx5dv*
 %{_mandir}/man3/mlx4dv*
+%{_mandir}/man7/bnxt_re_dv*
 %{_mandir}/man7/efadv*
 %{_mandir}/man7/hnsdv*
 %{_mandir}/man7/ionicdv*