Skip to content

Commit 24a1e0f

Browse files
sbasavapatnasbasavapatna
committed
bnxt_re/lib: Direct Verbs: Add man pages
Document direct verbs (DV) feature and related DV APIs . Signed-off-by: Sriharsha Basavapatna <sriharsha.basavapatna@broadcom.com> Reviewed-by: Selvin Xavier <selvin.xavier@broadcom.com>
1 parent 4f04159 commit 24a1e0f

10 files changed

Lines changed: 447 additions & 0 deletions

‎CMakeLists.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -747,6 +747,7 @@ add_subdirectory(librdmacm/man)
747747
# Providers
748748
if (HAVE_COHERENT_DMA)
749749
add_subdirectory(providers/bnxt_re)
750+
add_subdirectory(providers/bnxt_re/man)
750751
add_subdirectory(providers/cxgb4) # NO SPARSE
751752
add_subdirectory(providers/efa)
752753
add_subdirectory(providers/efa/man)

‎providers/bnxt_re/man/CMakeLists.txt‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
rdma_man_pages(
2+
bnxt_re_dv.7.md
3+
bnxt_re_dv_alloc_db_region.3.md
4+
bnxt_re_dv_free_db_region.3.md
5+
bnxt_re_dv_get_default_db_region.3.md
6+
bnxt_re_dv_umem_reg.3.md
7+
bnxt_re_dv_umem_dereg.3.md
8+
bnxt_re_dv_create_cq.3.md
9+
bnxt_re_dv_destroy_cq.3.md
10+
)

‎providers/bnxt_re/man/bnxt_re_dv.7.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
layout: page
3+
title: BNXT_RE_DV
4+
section: 7
5+
tagline: Verbs
6+
date: 2025-06-17
7+
header: "Broadcom BNXT-RE Direct Verbs Manual"
8+
footer: bnxt_re
9+
---
10+
11+
# NAME
12+
13+
bnxt_re_dv - Direct verbs for Broadcom RoCE (bnxt_re) devices
14+
15+
# DESCRIPTION
16+
17+
The libibverbs API is abstract and portable. For workloads that need to
18+
manage some of the RDMA HW resources directly, the bnxt_re provider
19+
exposes **direct verbs**. These are driver-specific routines that work
20+
together with user-registered queue memory and optional doorbell regions.
21+
22+
To use these new interfaces, include `<infiniband/bnxt_re_dv.h>` and link
23+
against **libbnxt_re** (in addition to **libibverbs**).
24+
25+
The following Direct Verbs are supported:
26+
27+
**Doorbell regions**
28+
29+
- **bnxt_re_dv_alloc_db_region**(3), **bnxt_re_dv_free_db_region**(3) allocate
30+
and release extra doorbell mapping regions.
31+
- **bnxt_re_dv_get_default_db_region**(3) returns the default doorbell page index
32+
and user-mapped doorbell address for the context.
33+
34+
**User memory (umem)**
35+
36+
- **bnxt_re_dv_umem_reg**(3) records a user virtual range (and optional dmabuf
37+
metadata) for later use when creating resources. The library does not pin or
38+
map the memory at registration time; mapping occurs when a resource that uses
39+
the umem is created.
40+
- **bnxt_re_dv_umem_dereg**(3) releases the registration.
41+
42+
**Completion queues**
43+
44+
- **bnxt_re_dv_create_cq**(3) creates a CQ backed by memory described by a prior
45+
**bnxt_re_dv_umem_reg**(3) handle and offset.
46+
- **bnxt_re_dv_destroy_cq**(3) destroys such a CQ.
47+
48+
Applications may register one large buffer with **bnxt_re_dv_umem_reg**(3) and
49+
pass different offsets (aligned to the device page size) and lengths when
50+
creating individual CQs.
51+
52+
# SEE ALSO
53+
54+
**verbs**(7),
55+
**bnxt_re_dv_alloc_db_region**(3),
56+
**bnxt_re_dv_free_db_region**(3),
57+
**bnxt_re_dv_get_default_db_region**(3),
58+
**bnxt_re_dv_umem_reg**(3),
59+
**bnxt_re_dv_umem_dereg**(3),
60+
**bnxt_re_dv_create_cq**(3),
61+
**bnxt_re_dv_destroy_cq**(3)
62+
63+
# AUTHORS
64+
65+
Kalesh AP \<kalesh-anakkur.purayil@broadcom.com\>,
66+
Sriharsha Basavapatna \<sriharsha.basavapatna@broadcom.com\>,
67+
Selvin Xavier \<selvin.xavier@broadcom.com\>

‎providers/bnxt_re/man/bnxt_re_dv_alloc_db_region.3.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
---
2+
layout: page
3+
title: bnxt_re_dv_alloc_db_region
4+
section: 3
5+
tagline: Verbs
6+
date: 2025-06-17
7+
header: "Broadcom BNXT-RE Direct Verbs Manual"
8+
footer: bnxt_re
9+
---
10+
11+
# NAME
12+
13+
bnxt_re_dv_alloc_db_region - allocate an additional doorbell region
14+
15+
# SYNOPSIS
16+
17+
```c
18+
#include <infiniband/bnxt_re_dv.h>
19+
20+
struct bnxt_re_dv_db_region_attr *
21+
bnxt_re_dv_alloc_db_region(struct ibv_context *ctx);
22+
```
23+
24+
# DESCRIPTION
25+
26+
**bnxt_re_dv_alloc_db_region**() allocates a new doorbell region for *ctx*.
27+
The kernel returns a doorbell region handle and attributes; the library
28+
memory-maps the doorbell page so the application can post doorbells using the
29+
returned mapping.
30+
31+
The returned pointer must be released with **bnxt_re_dv_free_db_region**(3).
32+
33+
# ARGUMENTS
34+
35+
*ctx*
36+
: Verbs device context returned by **ibv_open_device**(3). Identifies the
37+
device instance on which the new doorbell region is allocated.
38+
39+
# RETURN VALUE
40+
41+
On success, returns a pointer to a **struct bnxt_re_dv_db_region_attr**
42+
with all fields filled in:
43+
44+
```c
45+
struct bnxt_re_dv_db_region_attr {
46+
uint32_t handle; /* kernel handle for this doorbell region */
47+
uint32_t dpi; /* doorbell page index */
48+
uint64_t umdbr; /* unmapped doorbell BAR offset */
49+
uint64_t *dbr; /* mapped doorbell page (user virtual address) */
50+
};
51+
```
52+
53+
On failure, returns NULL and sets errno.
54+
55+
# SEE ALSO
56+
57+
**bnxt_re_dv**(7),
58+
**bnxt_re_dv_free_db_region**(3),
59+
**bnxt_re_dv_get_default_db_region**(3),
60+
**ibv_open_device**(3)
61+
62+
# AUTHOR
63+
64+
Kalesh AP \<kalesh-anakkur.purayil@broadcom.com\>

‎providers/bnxt_re/man/bnxt_re_dv_create_cq.3.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
layout: page
3+
title: bnxt_re_dv_create_cq
4+
section: 3
5+
tagline: Verbs
6+
date: 2025-06-17
7+
header: "Broadcom BNXT-RE Direct Verbs Manual"
8+
footer: bnxt_re
9+
---
10+
11+
# NAME
12+
13+
bnxt_re_dv_create_cq - create a completion queue using application-provided memory
14+
15+
# SYNOPSIS
16+
17+
```c
18+
#include <infiniband/bnxt_re_dv.h>
19+
20+
struct ibv_cq *bnxt_re_dv_create_cq(struct ibv_context *ibvctx,
21+
struct bnxt_re_dv_cq_init_attr *cq_attr);
22+
23+
struct bnxt_re_dv_cq_init_attr {
24+
void *umem_handle; /* opaque handle from bnxt_re_dv_umem_reg() */
25+
uint64_t umem_offset; /* byte offset into the umem, page-aligned */
26+
uint32_t ncqe; /* number of CQ entries requested */
27+
};
28+
```
29+
30+
# DESCRIPTION
31+
32+
**bnxt_re_dv_create_cq**() creates a completion queue using memory registered
33+
with **bnxt_re_dv_umem_reg**(3). The **umem_handle** field must be the opaque
34+
handle returned by that function; **umem_offset** is the byte offset into that
35+
registration, aligned to the device page size; **ncqe** is the requested number
36+
of CQEs.
37+
38+
This path requires **IB_UVERBS_CORE_SUPPORT_ROBUST_UDATA** (robust udata) on the
39+
device; otherwise the call fails.
40+
41+
# RETURN VALUE
42+
43+
Returns a pointer to the created **ibv_cq** on success, or NULL on failure with
44+
errno set.
45+
46+
# SEE ALSO
47+
48+
**bnxt_re_dv**(7),
49+
**bnxt_re_dv_destroy_cq**(3),
50+
**bnxt_re_dv_umem_reg**(3),
51+
**ibv_create_cq**(3)
52+
53+
# AUTHORS
54+
55+
Sriharsha Basavapatna \<sriharsha.basavapatna@broadcom.com\>,
56+
Kalesh AP \<kalesh-anakkur.purayil@broadcom.com\>,
57+
Selvin Xavier \<selvin.xavier@broadcom.com\>

‎providers/bnxt_re/man/bnxt_re_dv_destroy_cq.3.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
layout: page
3+
title: bnxt_re_dv_destroy_cq
4+
section: 3
5+
tagline: Verbs
6+
date: 2025-06-17
7+
header: "Broadcom BNXT-RE Direct Verbs Manual"
8+
footer: bnxt_re
9+
---
10+
11+
# NAME
12+
13+
bnxt_re_dv_destroy_cq - destroy a CQ created with bnxt_re_dv_create_cq
14+
15+
# SYNOPSIS
16+
17+
```c
18+
#include <infiniband/bnxt_re_dv.h>
19+
20+
int bnxt_re_dv_destroy_cq(struct ibv_cq *ibv_cq);
21+
```
22+
23+
# DESCRIPTION
24+
25+
**bnxt_re_dv_destroy_cq**() destroys a completion queue previously created by
26+
**bnxt_re_dv_create_cq**(3), using the provider’s normal CQ teardown path.
27+
28+
# RETURN VALUE
29+
30+
Returns 0 on success, or non-zero on failure (see **errno**).
31+
32+
# SEE ALSO
33+
34+
**bnxt_re_dv**(7),
35+
**bnxt_re_dv_create_cq**(3),
36+
**ibv_destroy_cq**(3)
37+
38+
# AUTHORS
39+
40+
Sriharsha Basavapatna \<sriharsha.basavapatna@broadcom.com\>,
41+
Kalesh AP \<kalesh-anakkur.purayil@broadcom.com\>,
42+
Selvin Xavier \<selvin.xavier@broadcom.com\>

‎providers/bnxt_re/man/bnxt_re_dv_free_db_region.3.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
layout: page
3+
title: bnxt_re_dv_free_db_region
4+
section: 3
5+
tagline: Verbs
6+
date: 2025-06-17
7+
header: "Broadcom BNXT-RE Direct Verbs Manual"
8+
footer: bnxt_re
9+
---
10+
11+
# NAME
12+
13+
bnxt_re_dv_free_db_region - free a doorbell region allocated with bnxt_re_dv_alloc_db_region
14+
15+
# SYNOPSIS
16+
17+
```c
18+
#include <infiniband/bnxt_re_dv.h>
19+
20+
int bnxt_re_dv_free_db_region(struct ibv_context *ctx,
21+
struct bnxt_re_dv_db_region_attr *attr);
22+
```
23+
24+
# DESCRIPTION
25+
26+
**bnxt_re_dv_free_db_region**() unmmaps the doorbell page, requests the driver to
27+
free the region identified by *attr*, and frees the **bnxt_re_dv_db_region_attr**
28+
structure.
29+
30+
*attr* must be the pointer returned by **bnxt_re_dv_alloc_db_region**(3) for the
31+
same *ctx*.
32+
33+
# RETURN VALUE
34+
35+
Returns 0 on success. On ioctl failure returns a non-zero error value and sets
36+
**errno** to that value.
37+
38+
# SEE ALSO
39+
40+
**bnxt_re_dv**(7),
41+
**bnxt_re_dv_alloc_db_region**(3),
42+
**bnxt_re_dv_get_default_db_region**(3)
43+
44+
# AUTHOR
45+
46+
Kalesh AP \<kalesh-anakkur.purayil@broadcom.com\>

‎providers/bnxt_re/man/bnxt_re_dv_get_default_db_region.3.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
layout: page
3+
title: bnxt_re_dv_get_default_db_region
4+
section: 3
5+
tagline: Verbs
6+
date: 2025-06-17
7+
header: "Broadcom BNXT-RE Direct Verbs Manual"
8+
footer: bnxt_re
9+
---
10+
11+
# NAME
12+
13+
bnxt_re_dv_get_default_db_region - query the default doorbell region for a context
14+
15+
# SYNOPSIS
16+
17+
```c
18+
#include <infiniband/bnxt_re_dv.h>
19+
20+
int bnxt_re_dv_get_default_db_region(struct ibv_context *ibvctx,
21+
struct bnxt_re_dv_db_region_attr *out);
22+
```
23+
24+
# DESCRIPTION
25+
26+
**bnxt_re_dv_get_default_db_region**() fills *out* with the default doorbell page
27+
index (**dpi**), user doorbell base (**umdbr**), and a pointer (**dbr**) to the
28+
user-mapped doorbell page already associated with the **ibv_context**.
29+
30+
Unlike **bnxt_re_dv_alloc_db_region**(3), this does not allocate a new region.
31+
32+
# ARGUMENTS
33+
34+
*out*
35+
: Output structure; **handle** is not used for the default region; **dbr**,
36+
**dpi**, and **umdbr** are valid on success.
37+
For the definition of **struct bnxt_re_dv_db_region_attr** and its members, see
38+
**bnxt_re_dv_alloc_db_region**(3).
39+
40+
# RETURN VALUE
41+
42+
Returns 0 on success, or a negative error code on failure.
43+
44+
# SEE ALSO
45+
46+
**bnxt_re_dv**(7),
47+
**bnxt_re_dv_alloc_db_region**(3),
48+
**bnxt_re_dv_free_db_region**(3),
49+
**ibv_open_device**(3)
50+
51+
# AUTHOR
52+
53+
Kalesh AP \<kalesh-anakkur.purayil@broadcom.com\>

‎providers/bnxt_re/man/bnxt_re_dv_umem_dereg.3.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
layout: page
3+
title: bnxt_re_dv_umem_dereg
4+
section: 3
5+
tagline: Verbs
6+
date: 2025-06-17
7+
header: "Broadcom BNXT-RE Direct Verbs Manual"
8+
footer: bnxt_re
9+
---
10+
11+
# NAME
12+
13+
bnxt_re_dv_umem_dereg - deregister user memory registered with bnxt_re_dv_umem_reg
14+
15+
# SYNOPSIS
16+
17+
```c
18+
#include <infiniband/bnxt_re_dv.h>
19+
20+
int bnxt_re_dv_umem_dereg(struct bnxt_re_dv_umem *umem);
21+
```
22+
23+
# DESCRIPTION
24+
25+
**bnxt_re_dv_umem_dereg**() clears **MADV_DONTFORK** for the registered range and
26+
frees the **bnxt_re_dv_umem** object. The application must not use *umem* with
27+
direct verbs after this call.
28+
29+
# RETURN VALUE
30+
31+
Returns 0.
32+
33+
# SEE ALSO
34+
35+
**bnxt_re_dv**(7),
36+
**bnxt_re_dv_umem_reg**(3)
37+
38+
# AUTHORS
39+
40+
Kalesh AP \<kalesh-anakkur.purayil@broadcom.com\>,
41+
Sriharsha Basavapatna \<sriharsha.basavapatna@broadcom.com\>

0 commit comments

Comments
 (0)