1IBV_REG_MR(3)           Libibverbs Programmer's Manual           IBV_REG_MR(3)
2
3
4

NAME

6       ibv_reg_mr, ibv_reg_mr_iova, ibv_reg_dmabuf_mr, ibv_dereg_mr - register
7       or deregister a memory region (MR)
8

SYNOPSIS

10       #include <infiniband/verbs.h>
11
12       struct ibv_mr *ibv_reg_mr(struct ibv_pd *pd, void *addr,
13                                 size_t length, int access);
14
15       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
19       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
23       int ibv_dereg_mr(struct ibv_mr *mr);
24

DESCRIPTION

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
32       IBV_ACCESS_LOCAL_WRITE  Enable Local Write Access
33
34       IBV_ACCESS_REMOTE_WRITE  Enable Remote Write Access
35
36       IBV_ACCESS_REMOTE_READ Enable Remote Read Access
37
38       IBV_ACCESS_REMOTE_ATOMIC Enable Remote Atomic Operation Access (if sup‐
39       ported)
40
41       IBV_ACCESS_MW_BIND Enable Memory Window Binding
42
43       IBV_ACCESS_ZERO_BASED  Use  byte  offset from beginning of MR to access
44       this MR, instead of a pointer address
45
46       IBV_ACCESS_ON_DEMAND Create an on-demand paging MR
47
48       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
51       IBV_ACCESS_RELAXED_ORDERING  Allow system to reorder accesses to the MR
52       to improve performance
53
54       If IBV_ACCESS_REMOTE_WRITE or  IBV_ACCESS_REMOTE_ATOMIC  is  set,  then
55       IBV_ACCESS_LOCAL_WRITE must be set too.
56
57       Local read access is always enabled for the MR.
58
59       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
62       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
66       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
72       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
83       ibv_dereg_mr() deregisters the MR mr.
84

RETURN VALUE

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
94       ibv_dereg_mr()  returns  0 on success, or the value of errno on failure
95       (which indicates the failure reason).
96

NOTES

98       ibv_dereg_mr() fails if any memory window is still bound to this MR.
99

SEE ALSO

101       ibv_alloc_pd(3),          ibv_post_send(3),           ibv_post_recv(3),
102       ibv_post_srq_recv(3)
103

AUTHORS

105       Dotan Barak <dotanba@gmail.com>
106
107
108
109libibverbs                        2006-10-31                     IBV_REG_MR(3)
Impressum