--- name: "ibv_reg_mr" section: "3" platform: "linux" package: "rdma-core" version: "65.0-1" release: "Arch Linux 2026-11-01" platforms: ["linux", "freebsd"] url: "https://new.carta.tech/ibv_reg_mr" --- # ibv\_reg\_mr(3) register or deregister a memory region (MR) ## NAME ibv\_reg\_mr, ibv\_reg\_mr\_iova, ibv\_reg\_dmabuf\_mr, ibv\_reg\_mr\_ex, ibv\_dereg\_mr - register or deregister a memory region (MR) ## SYNOPSIS ``` #include struct ibv_mr *ibv_reg_mr(struct ibv_pd *pd, void *addr, size_t length, int access); struct ibv_mr *ibv_reg_mr_iova(struct ibv_pd *pd, void *addr, size_t length, uint64_t hca_va, int access); struct ibv_mr *ibv_reg_dmabuf_mr(struct ibv_pd *pd, uint64_t offset, size_t length, uint64_t iova, int fd, int access); struct ibv_mr *ibv_reg_mr_ex(struct ibv_pd *pd, struct ibv_mr_init_attr *mr_init_attr"); int ibv_dereg_mr(struct ibv_mr *mr); ``` ## DESCRIPTION **ibv\_reg\_mr()** registers a memory region (MR) associated with the protection domain *pd.* The MR's starting address is *addr* and its size is *length.* The argument *access* describes the desired memory protection attributes; it is either 0 or the bitwise OR of one or more of the following flags: - **IBV\_ACCESS\_LOCAL\_WRITE** Enable Local Write Access - **IBV\_ACCESS\_REMOTE\_WRITE** Enable Remote Write Access - **IBV\_ACCESS\_REMOTE\_READ** Enable Remote Read Access - **IBV\_ACCESS\_REMOTE\_ATOMIC** Enable Remote Atomic Operation Access (if supported) - **IBV\_ACCESS\_FLUSH\_GLOBAL** Enable Remote Flush Operation with global visibility placement type (if supported) - **IBV\_ACCESS\_FLUSH\_PERSISTENT** Enable Remote Flush Operation with persistence placement type (if supported) - **IBV\_ACCESS\_MW\_BIND** Enable Memory Window Binding - **IBV\_ACCESS\_ZERO\_BASED** Use byte offset from beginning of MR to access this MR, instead of a pointer address - **IBV\_ACCESS\_ON\_DEMAND** Create an on-demand paging MR - **IBV\_ACCESS\_HUGETLB** Huge pages are guaranteed to be used for this MR, applicable with IBV\_ACCESS\_ON\_DEMAND in explicit mode only - **IBV\_ACCESS\_RELAXED\_ORDERING** This setting allows the NIC to relax the order that data is transferred between the network and the target memory region. Relaxed ordering allows network initiated writes (such as incoming message send or RDMA write operations) to reach memory in an arbitrary order. This can improve the performance of some applications. However, relaxed ordering has the following impact: RDMA write-after-write message order is no longer guaranteed. (Send messages will still match posted receive buffers in order.) Back-to-back network writes that target the same memory region leave the region in an unknown state. Relaxed ordering does not change completion semantics, such as data visibility. That is, a completion still ensures that all data is visible, including data from prior transfers. Relaxed ordered operations will also not bypass atomic operations. If **IBV\_ACCESS\_REMOTE\_WRITE** or **IBV\_ACCESS\_REMOTE\_ATOMIC** is set, then **IBV\_ACCESS\_LOCAL\_WRITE** must be set too. Local read access is always enabled for the MR. To create an implicit ODP MR, IBV\_ACCESS\_ON\_DEMAND should be set, addr should be 0 and length should be SIZE\_MAX. If **IBV\_ACCESS\_HUGETLB** is set, then application awares that for this MR all pages are huge and must promise it will never do anything to break huge pages. **ibv\_reg\_mr\_iova()** ibv\_reg\_mr\_iova is the same as the normal reg\_mr, except that the user is allowed to specify the virtual base address of the MR when accessed through a lkey or rkey. The offset in the memory region is computed as 'addr + (iova - hca\_va)'. Specifying 0 for hca\_va has the same effect as IBV\_ACCESS\_ZERO\_BASED. **ibv\_reg\_dmabuf\_mr()** registers a dma-buf based memory region (MR) associated with the protection domain *pd.* The MR starts at *offset* of the dma-buf and its size is *length.* The dma-buf is identified by the file descriptor *fd.* The argument *iova* specifies the virtual base address of the MR when accessed through a lkey or rkey. It must have the same page offset as *offset.* The argument *access* describes the desired memory protection attributes; it is similar to the ibv\_reg\_mr case except that only the following flags are supported: **IBV\_ACCESS\_LOCAL\_WRITE, IBV\_ACCESS\_REMOTE\_WRITE, IBV\_ACCESS\_REMOTE\_READ, IBV\_ACCESS\_REMOTE\_ATOMIC, IBV\_ACCESS\_RELAXED\_ORDERING.** **ibv\_reg\_mr\_ex()** ibv\_reg\_mr\_ex is a an API that enables all the variants of the other ibv\_reg\_mr\_xxx() that desecibed in that man page. It has the *mr\_init\_attr-\>comp\_mask* field to let application mark which fields are applicable. In addition, it includes the *mr\_init\_attr-\>dmah* which can be used to include an ibv\_dmah object that will be used for that MR. It also includes the *mr\_init\_attr-\>buf* field, selected by **IBV\_REG\_MR\_MASK\_BUF,** which can be used to register a buffer handle returned by [**ibv\_alloc\_buf**(3)](/ibv_alloc_buf/3.md). When **IBV\_REG\_MR\_MASK\_BUF** is set, *mr\_init\_attr-\>buf* must point to the buffer handle and *mr\_init\_attr-\>addr* and *mr\_init\_attr-\>length* describe the buffer range to register. The protection domain must be the same protection domain used to allocate the buffer, and the range must be within the allocated buffer. The other fields on the input pointer have the same meaning as of the fields that described in that man page for the other verbs. **ibv\_dereg\_mr()** deregisters the MR *mr.* ## RETURN VALUE **ibv\_reg\_mr() / ibv\_reg\_mr\_iova() / ibv\_reg\_dmabuf\_mr() / ibv\_reg\_mr\_ex()** returns a pointer to the registered MR, or NULL if the request fails. On failure **errno** is set to indicate the reason (for example **EINVAL** for an invalid combination of arguments). The local key (**L\_Key**) field **lkey** is used as the lkey field of struct ibv\_sge when posting buffers with ibv\_post\_\* verbs, and the the remote key (**R\_Key**) field **rkey** is used by remote processes to perform Atomic and RDMA operations. The remote process places this **rkey** as the rkey field of struct ibv\_send\_wr passed to the ibv\_post\_send function. **ibv\_dereg\_mr()** returns 0 on success, or the value of errno on failure (which indicates the failure reason). ## NOTES **ibv\_dereg\_mr()** fails if any memory window is still bound to this MR. **ibv\_reg\_mr\_ex()** One among mr\_init\_attr-\>fd and mr\_init\_attr-\>addr is required, both can't come together. When **IBV\_REG\_MR\_MASK\_BUF** is set, *mr\_init\_attr-\>buf* identifies the buffer handle returned by [**ibv\_alloc\_buf**(3)](/ibv_alloc_buf/3.md), and *mr\_init\_attr-\>addr* is required and **IBV\_REG\_MR\_MASK\_ADDR** must be set; the address selects the registered range within *mr\_init\_attr-\>buf;* For a dma-buf backed buffer, the caller must not set *mr\_init\_attr-\>fd,* *mr\_init\_attr-\>fd\_offset,* or *mr\_init\_attr-\>iova* because libibverbs derives them from the buffer handle. ## SEE ALSO [**ibv\_alloc\_pd**(3)](/ibv_alloc_pd/3.md), [**ibv\_alloc\_buf**(3)](/ibv_alloc_buf/3.md), [**ibv\_post\_send**(3)](/ibv_post_send/3.md), [**ibv\_post\_recv**(3)](/ibv_post_recv/3.md), [**ibv\_post\_srq\_recv**(3)](/ibv_post_srq_recv/3.md) ## AUTHORS - Dotan Barak \