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_FLUSH_GLOBAL Enable Remote Flush Operation with global visi‐
42       bility placement type (if supported)
43
44       IBV_ACCESS_FLUSH_PERSISTENT Enable Remote Flush Operation with  persis‐
45       tence placement type (if supported)
46
47       IBV_ACCESS_MW_BIND Enable Memory Window Binding
48
49       IBV_ACCESS_ZERO_BASED  Use  byte  offset from beginning of MR to access
50       this MR, instead of a pointer address
51
52       IBV_ACCESS_ON_DEMAND Create an on-demand paging MR
53
54       IBV_ACCESS_HUGETLB Huge pages are guaranteed to be used  for  this  MR,
55       applicable with IBV_ACCESS_ON_DEMAND in explicit mode only
56
57       IBV_ACCESS_RELAXED_ORDERING  Allow system to reorder accesses to the MR
58       to improve performance
59
60       If IBV_ACCESS_REMOTE_WRITE or  IBV_ACCESS_REMOTE_ATOMIC  is  set,  then
61       IBV_ACCESS_LOCAL_WRITE must be set too.
62
63       Local read access is always enabled for the MR.
64
65       To  create an implicit ODP MR, IBV_ACCESS_ON_DEMAND should be set, addr
66       should be 0 and length should be SIZE_MAX.
67
68       If IBV_ACCESS_HUGETLB is set, then application awares that for this  MR
69       all  pages are huge and must promise it will never do anything to break
70       huge pages.
71
72       ibv_reg_mr_iova() ibv_reg_mr_iova is the same as the normal reg_mr, ex‐
73       cept  that  the  user is allowed to specify the virtual base address of
74       the MR when accessed through a lkey or rkey. The offset in  the  memory
75       region is computed as 'addr + (iova - hca_va)'. Specifying 0 for hca_va
76       has the same effect as IBV_ACCESS_ZERO_BASED.
77
78       ibv_reg_dmabuf_mr() registers a dma-buf based memory region (MR)  asso‐
79       ciated  with  the protection domain pd.  The MR starts at offset of the
80       dma-buf and its size is length.  The dma-buf is identified by the  file
81       descriptor fd.  The argument iova specifies the virtual base address of
82       the MR when accessed through a lkey or rkey.  It  must  have  the  same
83       page  offset as offset.  The argument access describes the desired mem‐
84       ory protection attributes; it is similar to the ibv_reg_mr case  except
85       that  only  the  following flags are supported: IBV_ACCESS_LOCAL_WRITE,
86       IBV_ACCESS_REMOTE_WRITE,     IBV_ACCESS_REMOTE_READ,     IBV_ACCESS_RE‐
87       MOTE_ATOMIC, IBV_ACCESS_RELAXED_ORDERING.
88
89       ibv_dereg_mr() deregisters the MR mr.
90

RETURN VALUE

92       ibv_reg_mr()   /  ibv_reg_mr_iova()  /  ibv_reg_dmabuf_mr()  returns  a
93       pointer to the registered MR, or NULL if the request fails.  The  local
94       key (L_Key) field lkey is used as the lkey field of struct ibv_sge when
95       posting buffers with ibv_post_* verbs, and the the remote  key  (R_Key)
96       field rkey is used by remote processes to perform Atomic and RDMA oper‐
97       ations.  The remote process places this  rkey  as  the  rkey  field  of
98       struct ibv_send_wr passed to the ibv_post_send function.
99
100       ibv_dereg_mr()  returns  0 on success, or the value of errno on failure
101       (which indicates the failure reason).
102

NOTES

104       ibv_dereg_mr() fails if any memory window is still bound to this MR.
105

SEE ALSO

107       ibv_alloc_pd(3),          ibv_post_send(3),           ibv_post_recv(3),
108       ibv_post_srq_recv(3)
109

AUTHORS

111       Dotan Barak <dotanba@gmail.com>
112
113
114
115libibverbs                        2006-10-31                     IBV_REG_MR(3)