1IBV_REG_MR(3) Libibverbs Programmer's Manual IBV_REG_MR(3)
2
6 ibv_reg_mr, ibv_reg_mr_iova, ibv_reg_dmabuf_mr, ibv_dereg_mr - register
7 or deregister a memory region (MR)
8
10 #include <infiniband/verbs.h>
11 struct ibv_mr *ibv_reg_mr(struct ibv_pd *pd, void *addr,
13 size_t length, int access);
14 struct ibv_mr *ibv_reg_mr_iova(struct ibv_pd *pd, void *addr,
16 size_t length, uint64_t hca_va,
17 int access);
18 struct ibv_mr *ibv_reg_dmabuf_mr(struct ibv_pd *pd, uint64_t offset,
20 size_t length, uint64_t iova,
21 int fd, int access);
22 int ibv_dereg_mr(struct ibv_mr *mr);
24
26 ibv_reg_mr() registers a memory region (MR) associated with the protec‐
27 tion domain pd. The MR's starting address is addr and its size is
28 length. The argument access describes the desired memory protection
29 attributes; it is either 0 or the bitwise OR of one or more of the fol‐
30 lowing flags:
31 IBV_ACCESS_LOCAL_WRITE Enable Local Write Access
33 IBV_ACCESS_REMOTE_WRITE Enable Remote Write Access
35 IBV_ACCESS_REMOTE_READ Enable Remote Read Access
37 IBV_ACCESS_REMOTE_ATOMIC Enable Remote Atomic Operation Access (if sup‐
39 ported)
40 IBV_ACCESS_MW_BIND Enable Memory Window Binding
42 IBV_ACCESS_ZERO_BASED Use byte offset from beginning of MR to access
44 this MR, instead of a pointer address
45 IBV_ACCESS_ON_DEMAND Create an on-demand paging MR
47 IBV_ACCESS_HUGETLB Huge pages are guaranteed to be used for this MR,
49 applicable with IBV_ACCESS_ON_DEMAND in explicit mode only
50 IBV_ACCESS_RELAXED_ORDERING Allow system to reorder accesses to the MR
52 to improve performance
53 If IBV_ACCESS_REMOTE_WRITE or IBV_ACCESS_REMOTE_ATOMIC is set, then
55 IBV_ACCESS_LOCAL_WRITE must be set too.
56 Local read access is always enabled for the MR.
58 To create an implicit ODP MR, IBV_ACCESS_ON_DEMAND should be set, addr
60 should be 0 and length should be SIZE_MAX.
61 If IBV_ACCESS_HUGETLB is set, then application awares that for this MR
63 all pages are huge and must promise it will never do anything to break
64 huge pages.
65 ibv_reg_mr_iova() ibv_reg_mr_iova is the same as the normal reg_mr,
67 except that the user is allowed to specify the virtual base address of
68 the MR when accessed through a lkey or rkey. The offset in the memory
69 region is computed as 'addr + (iova - hca_va)'. Specifying 0 for hca_va
70 has the same effect as IBV_ACCESS_ZERO_BASED.
71 ibv_reg_dmabuf_mr() registers a dma-buf based memory region (MR) asso‐
73 ciated with the protection domain pd. The MR starts at offset of the
74 dma-buf and its size is length. The dma-buf is identified by the file
75 descriptor fd. The argument iova specifies the virtual base address of
76 the MR when accessed through a lkey or rkey. It must have the same
77 page offset as offset. The argument access describes the desired mem‐
78 ory protection attributes; it is similar to the ibv_reg_mr case except
79 that only the following flags are supported: IBV_ACCESS_LOCAL_WRITE,
80 IBV_ACCESS_REMOTE_WRITE, IBV_ACCESS_REMOTE_READ,
81 IBV_ACCESS_REMOTE_ATOMIC, IBV_ACCESS_RELAXED_ORDERING.
82 ibv_dereg_mr() deregisters the MR mr.
84
86 ibv_reg_mr() / ibv_reg_mr_iova() / ibv_reg_dmabuf_mr() returns a
87 pointer to the registered MR, or NULL if the request fails. The local
88 key (L_Key) field lkey is used as the lkey field of struct ibv_sge when
89 posting buffers with ibv_post_* verbs, and the the remote key (R_Key)
90 field rkey is used by remote processes to perform Atomic and RDMA oper‐
91 ations. The remote process places this rkey as the rkey field of
92 struct ibv_send_wr passed to the ibv_post_send function.
93 ibv_dereg_mr() returns 0 on success, or the value of errno on failure
95 (which indicates the failure reason).
96
98 ibv_dereg_mr() fails if any memory window is still bound to this MR.
99
101 ibv_alloc_pd(3), ibv_post_send(3), ibv_post_recv(3),
102 ibv_post_srq_recv(3)
103
105 Dotan Barak <dotanba@gmail.com>
106libibverbs 2006-10-31 IBV_REG_MR(3)