--- name: "fi_mr" section: "3" platform: "linux" package: "libfabric" version: "2.7.0-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/fi_mr" --- # fi\_mr(3) Memory region operations ## NAME fi\_mr - Memory region operations - fi\_mr\_reg / fi\_mr\_regv / fi\_mr\_regattr Register local memory buffers for direct fabric access - fi\_close Deregister registered memory buffers. - fi\_mr\_desc Return a local descriptor associated with a registered memory region - fi\_mr\_key Return the remote key needed to access a registered memory region - fi\_mr\_raw\_attr Return raw memory region attributes. - fi\_mr\_map\_raw Converts a raw memory region key into a key that is usable for data transfer operations. - fi\_mr\_unmap\_key Releases a previously mapped raw memory region key. - fi\_mr\_bind Associate a registered memory region with a completion counter or an endpoint. - fi\_mr\_refresh Updates the memory pages associated with a memory region. - fi\_mr\_enable Enables a memory region for use. - fi\_hmem\_ze\_device Returns an hmem device identifier for a level zero driver and device. - fi\_mr\_get\_xpu\_desc Retrieve a memory region descriptor with extended options. ## SYNOPSIS - ``` #include int fi_mr_reg(struct fid_domain *domain, const void *buf, size_t len, uint64_t access, uint64_t offset, uint64_t requested_key, uint64_t flags, struct fid_mr **mr, void *context); int fi_mr_regv(struct fid_domain *domain, const struct iovec * iov, size_t count, uint64_t access, uint64_t offset, uint64_t requested_key, uint64_t flags, struct fid_mr **mr, void *context); int fi_mr_regattr(struct fid_domain *domain, const struct fi_mr_attr *attr, uint64_t flags, struct fid_mr **mr); int fi_close(struct fid *mr); void * fi_mr_desc(struct fid_mr *mr); uint64_t fi_mr_key(struct fid_mr *mr); int fi_mr_raw_attr(struct fid_mr *mr, uint64_t *base_addr, uint8_t *raw_key, size_t *key_size, uint64_t flags); int fi_mr_map_raw(struct fid_domain *domain, uint64_t base_addr, uint8_t *raw_key, size_t key_size, uint64_t *key, uint64_t flags); int fi_mr_unmap_key(struct fid_domain *domain, uint64_t key); int fi_mr_bind(struct fid_mr *mr, struct fid *bfid, uint64_t flags); int fi_mr_refresh(struct fid_mr *mr, const struct iovec *iov, size_t count, uint64_t flags); int fi_mr_enable(struct fid_mr *mr); int fi_hmem_ze_device(int driver_index, int device_index); int fi_mr_get_xpu_desc(struct fid_mr *mr, void *buf, size_t *len, uint64_t flags, struct fid_xpu_ctx *ctx); ``` ## ARGUMENTS - *domain* Resource domain - *mr* Memory region - *bfid* Fabric identifier of an associated resource. - *context* User specified context associated with the memory region. - *buf* Memory buffer to register with the fabric hardware. - *len* Length of memory buffer to register. Must be \> 0. - *iov* Vectored memory buffer. - *count* Count of vectored buffer entries. - *access* Memory access permissions associated with registration - *offset* Optional specified offset for accessing specified registered buffers. This parameter is reserved for future use and must be 0. - *requested\_key* Requested remote key associated with registered buffers. Parameter is ignored if FI\_MR\_PROV\_KEY flag is set in the domain mr\_mode bits. Parameter may be ignored if remote access permissions are not asked for. - *attr* Memory region attributes - *flags* Additional flags to apply to the operation. ## DESCRIPTION Registered memory regions associate memory buffers with permissions granted for access by fabric resources. A memory buffer must be registered with a resource domain before it can be used as the target of a remote RMA or atomic data transfer. Additionally, a fabric provider may require that data buffers be registered before being used in local transfers. Memory registration restrictions are controlled using a separate set of mode bits, specified through the domain attributes (mr\_mode field). Each mr\_mode bit requires that an application take specific steps in order to use memory buffers with libfabric interfaces. As a special case, a new memory region can be created from an existing memory region. Such a new memory region is called a sub-MR, and the existing memory region is called the base MR. Sub-MRs may be used to shared hardware resources, such as virtual to physical address translations and page pinning. This can improve performance when creating and destroying sub-regions that need different access rights. The base MR itself can also be a sub-MR, allowing for a hierarchy of memory regions. The following apply to memory registration. - *Default Memory Registration* If no mr\_mode bits are set, the default behaviors describe below are followed. Historically, these defaults were collectively referred to as scalable memory registration. The default requirements are outlined below, followed by definitions of how each mr\_mode bit alters the definition. Compatibility: For library versions 1.4 and earlier, this was indicated by setting mr\_mode to FI\_MR\_SCALABLE and the fi\_info mode bit FI\_LOCAL\_MR to 0. FI\_MR\_SCALABLE and FI\_LOCAL\_MR were deprecated in libfabric version 1.5, though they are supported for backwards compatibility purposes. For security, memory registration is required for data buffers that are accessed directly by a peer process. For example, registration is required for RMA target buffers (read or written to), and those accessed by atomic or collective operations. By default, registration occurs on virtual address ranges. Because registration refers to address ranges, rather than allocated data buffers, the address ranges do not need to map to data buffers allocated by the application at the time the registration call is made. That is, an application can register any range of addresses in their virtual address space, whether or not those addresses are backed by physical pages or have been allocated. Note that physical pages must back addresses prior to the addresses being accessed as part of a data transfer operation, or the data transfers will fail. Additionally, depending on the operation, this could result in the local process receiving a segmentation fault for accessing invalid memory. Once registered, the resulting memory regions are accessible by peers starting at a base address of 0. That is, the target address that is specified is a byte offset into the registered region. The application also selects the access key associated with the MR. The key size is restricted to a maximum of 8 bytes. With scalable registration, locally accessed data buffers are not registered. This includes source buffers for all transmit operations – sends, tagged sends, RMA, and atomics – as well as buffers posted for receive and tagged receive operations. Although the default memory registration behavior is convenient for application developers, it is difficult to implement in hardware. Attempts to hide the hardware requirements from the application often results in significant and unacceptable impacts to performance. The following mr\_mode bits are provided as input into fi\_getinfo. If a provider requires the behavior defined for an mr\_mode bit, it will leave the bit set on output to fi\_getinfo. Otherwise, the provider can clear the bit to indicate that the behavior is not needed. By setting an mr\_mode bit, the application has agreed to adjust its behavior as indicated. Importantly, applications that choose to support an mr\_mode must be prepared to handle the case where the mr\_mode is not required. A provider will clear an mr\_mode bit if it is not needed. - *FI\_MR\_LOCAL* When the FI\_MR\_LOCAL mode bit is set, applications must register all data buffers that will be accessed by the local hardware and provide a valid desc parameter into applicable data transfer operations. When FI\_MR\_LOCAL is unset, applications are not required to register data buffers before using them for local operations (e.g. send and receive data buffers). Prior to libfabric 1.22, the desc parameter was ignored. In libfabric 1.22 and later, the desc parameter must be either valid or NULL. This behavior allows applications to optionally pass in a valid desc parameter. If the desc parameter is NULL, any required local memory registration will be handled by the provider. A provider may hide local registration requirements from applications by making use of an internal registration cache or similar mechanisms. Such mechanisms, however, may negatively impact performance for some applications, notably those which manage their own network buffers. In order to support as broad range of applications as possible, without unduly affecting their performance, applications that wish to manage their own local memory registrations may do so by using the memory registration calls and passing in a valid desc parameter. Note: the FI\_MR\_LOCAL mr\_mode bit replaces the FI\_LOCAL\_MR fi\_info mode bit. When FI\_MR\_LOCAL is set, FI\_LOCAL\_MR is ignored. - *FI\_MR\_RAW* Raw memory regions are used to support providers with keys larger than 64-bits or require setup at the peer. When the FI\_MR\_RAW bit is set, applications must use fi\_mr\_raw\_attr() locally and fi\_mr\_map\_raw() at the peer before targeting a memory region as part of any data transfer request. - *FI\_MR\_VIRT\_ADDR* The FI\_MR\_VIRT\_ADDR bit indicates that the provider references memory regions by virtual address, rather than a 0-based offset. Peers that target memory regions registered with FI\_MR\_VIRT\_ADDR specify the destination memory buffer using the target’s virtual address, with any offset into the region specified as virtual address + offset. Support of this bit typically implies that peers must exchange addressing data prior to initiating any RMA or atomic operation. For memory regions that are registered using FI\_MR\_DMABUF, the starting \`virtual address' of the DMA-buf region is obtained by adding the offset field to the base\_addr field of struct fi\_mr\_dmabuf that was specified through the registration call. - *FI\_MR\_ALLOCATED* When set, all registered memory regions must be backed by physical memory pages at the time the registration call is made. In addition, applications must not perform operations which may result in the underlying virtual address to physical page mapping to change (e.g. calling free() against an allocated MR). Failing to adhere to this may result in the virtual address pointing to one set of physical pages while the MR points to another set of physical pages. When unset, registered memory regions need not be backed by physical memory pages at the time the registration call is made. In addition, the underlying virtual address to physical page mapping is allowed to change, and the provider will ensure the corresponding MR is updated accordingly. This behavior enables application use-cases where memory may be frequently freed and reallocated or system memory migrating to/from device memory. When unset, the application is responsible for ensuring that a registered memory region references valid physical pages while a data transfer is active against it, or the data transfer may fail. Application changes to the virtual address range must be coordinated with network traffic to or from that range. If unset and FI\_HMEM is supported, the ability for the virtual address to physical address mapping to change extends to HMEM interfaces as well. If a provider cannot support a virtual address to physical address changing for a given HMEM interface, the provider should support a reasonable fallback or the operation should fail. - *FI\_MR\_PROV\_KEY* This memory region mode indicates that the provider does not support application requested MR keys. MR keys are returned by the provider. Applications that support FI\_MR\_PROV\_KEY can obtain the provider key using fi\_mr\_key(), unless FI\_MR\_RAW is also set. The returned key should then be exchanged with peers prior to initiating an RMA or atomic operation. - *FI\_MR\_MMU\_NOTIFY* FI\_MR\_MMU\_NOTIFY is typically set by providers that support memory registration against memory regions that are not necessarily backed by allocated physical pages at the time the memory registration occurs. (That is, FI\_MR\_ALLOCATED is typically 0). However, such providers require that applications notify the provider prior to the MR being accessed as part of a data transfer operation. This notification informs the provider that all necessary physical pages now back the region. The notification is necessary for providers that cannot hook directly into the operating system page tables or memory management unit. See fi\_mr\_refresh() for notification details. - *FI\_MR\_RMA\_EVENT* This mode bit indicates that the provider must configure memory regions that are associated with RMA events prior to their use. This includes all memory regions that are associated with completion counters. When set, applications must indicate if a memory region will be associated with a completion counter as part of the region’s creation. This is done by passing in the FI\_RMA\_EVENT flag to the memory registration call. Such memory regions will be created in a disabled state and must be associated with all completion counters prior to being enabled. To enable a memory region, the application must call fi\_mr\_enable(). After calling fi\_mr\_enable(), no further resource bindings may be made to the memory region. - *FI\_MR\_ENDPOINT* This mode bit indicates that the provider associates memory regions with endpoints rather than domains. Memory regions that are registered with the provider are created in a disabled state and must be bound to an endpoint prior to being enabled. To bind the MR with an endpoint, the application must use fi\_mr\_bind(). To enable the memory region, the application must call fi\_mr\_enable(). - *FI\_MR\_HMEM* This mode bit is associated with the FI\_HMEM capability. If FI\_MR\_HMEM is set, the application must register buffers that were allocated using a device call and provide a valid desc parameter into applicable data transfer operations even if they are only used for local operations (e.g. send and receive data buffers). Device memory must be registered using the fi\_mr\_regattr call, with the iface and device fields filled out. If FI\_MR\_HMEM is unset, the application need not register device buffers for local operations. In addition, fi\_mr\_regattr is not required to be used for device memory registration. It is the responsibility of the provider to discover the appropriate device memory registration attributes, if applicable. Similar to if FI\_MR\_LOCAL is unset, if FI\_MR\_HMEM is unset, applications may optionally pass in a valid desc parameter. If the desc parameter is NULL, any required local memory registration will be handled by the provider. If FI\_MR\_HMEM is set, but FI\_MR\_LOCAL is unset, only device buffers must be registered when used locally. In this case, the desc parameter passed into data transfer operations must either be valid or NULL. Similarly, if FI\_MR\_LOCAL is set, but FI\_MR\_HMEM is not, the desc parameter must either be valid or NULL. - *FI\_MR\_COLLECTIVE* This bit is associated with the FI\_COLLECTIVE capability. If FI\_MR\_COLLECTIVE is set, the provider requires that memory regions used in collection operations must explicitly be registered for use with collective calls. This requires registering regions passed to collective calls using the FI\_COLLECTIVE flag. If FI\_MR\_COLLECTIVE is unset, memory registration for collection operations is optional. Applications may optionally pass in a valid desc parameter. If the desc parameter is NULL, any required local memory registration will be handled by the provider. - *FI\_MR\_XPU\_DESC* This bit is associated with the FI\_XPU capability. It indicates whether an XPU-usable memory descriptor is required for data transfers initiated by an XPU (see [fi\_xpu(3)](/fi_xpu/3.md)). When FI\_MR\_XPU\_DESC is set, an application that registers a buffer used by an XPU data transfer must obtain an XPU descriptor with fi\_mr\_get\_xpu\_desc() and pass it into the device-side data transfer calls. This is the XPU analog of FI\_MR\_LOCAL for host-side calls. When FI\_MR\_XPU\_DESC is unset, XPU data transfer calls do not require a descriptor and the application need not call fi\_mr\_get\_xpu\_desc(). - *Basic Memory Registration* (deprecated) Basic memory registration was deprecated in libfabric version 1.5, but is supported for backwards compatibility. Basic memory registration is indicated by setting mr\_mode equal to FI\_MR\_BASIC. FI\_MR\_BASIC must be set alone and not paired with mr\_mode bits. Unlike other mr\_mode bits, if FI\_MR\_BASIC is set on input to fi\_getinfo(), it will not be cleared by the provider. That is, setting mr\_mode equal to FI\_MR\_BASIC forces basic registration if the provider supports it. The behavior of basic registration is equivalent to requiring the following mr\_mode bits: FI\_MR\_VIRT\_ADDR, FI\_MR\_ALLOCATED, and FI\_MR\_PROV\_KEY. Additionally, providers that support basic registration usually require the (deprecated) fi\_info mode bit FI\_LOCAL\_MR, which was incorporated into the FI\_MR\_LOCAL mr\_mode bit. The registrations functions – fi\_mr\_reg, fi\_mr\_regv, and fi\_mr\_regattr – are used to register one or more memory regions with fabric resources. The main difference between registration functions are the number and type of parameters that they accept as input. Otherwise, they perform the same general function. **Deprecated** : By default, memory registration completes synchronously. I.e. the registration call will not return until the registration has completed. Memory registration can complete asynchronous by binding the resource domain to an event queue using the FI\_REG\_MR flag. See fi\_domain\_bind. When memory registration is asynchronous, in order to avoid a race condition between the registration call returning and the corresponding reading of the event from the EQ, the mr output parameter will be written before any event associated with the operation may be read by the application. An asynchronous event will not be generated unless the registration call returns success (0). ### fi\_mr\_reg The fi\_mr\_reg call registers the user-specified memory buffer with the resource domain. The buffer is enabled for access by the fabric hardware based on the provided access permissions. See the access field description for memory region attributes below. Registered memory is associated with a local memory descriptor and, optionally, a remote memory key. A memory descriptor is a provider specific identifier associated with registered memory. Memory descriptors often map to hardware specific indices or keys associated with the memory region. Remote memory keys provide limited protection against unwanted access by a remote node. Remote accesses to a memory region must provide the key associated with the registration. Because MR keys must be provided by a remote process, an application can use the requested\_key parameter to indicate that a specific key value be returned. Support for user requested keys is provider specific and is determined by the FI\_MR\_PROV\_KEY flag value in the mr\_mode domain attribute. Remote RMA and atomic operations indicate the location within a registered memory region by specifying an address. The location is referenced by adding the offset to either the base virtual address of the buffer or to 0, depending on the mr\_mode. The offset parameter is reserved for future use and must be 0. For asynchronous memory registration requests, the result will be reported to the user through an event queue associated with the resource domain. If successful, the allocated memory region structure will be returned to the user through the mr parameter. The mr address must remain valid until the registration operation completes. The context specified with the registration request is returned with the completion event. For domains opened with FI\_AV\_AUTH\_KEY, fi\_mr\_reg is not supported and fi\_mr\_regattr must be used. ### fi\_mr\_regv The fi\_mr\_regv call adds support for a scatter-gather list to fi\_mr\_reg. Multiple memory buffers are registered as a single memory region. Otherwise, the operation is the same. For domains opened with FI\_AV\_AUTH\_KEY, fi\_mr\_regv is not supported and fi\_mr\_regattr must be used. ### fi\_mr\_regattr The fi\_mr\_regattr call is a more generic, extensible registration call that allows the user to specify the registration request using a struct fi\_mr\_attr (defined below). ### fi\_close Fi\_close is used to release all resources associated with a registering a memory region. Once deregistered, further access to the registered memory is not guaranteed. Active or queued operations that reference a memory region being closed may attempt to access an invalid memory region and fail. After an MR is closed, any new operations targeting the closed MR will also fail. Applications are responsible for ensuring that a MR is no longer needed prior to closing it. Note that accesses to a closed MR from a remote peer will result in an error at the peer. The state of the local endpoint will be unaffected. For MRs that are associated with an endpoint (FI\_MR\_ENDPOINT flag is set), the MR must be closed before the endpoint. If resources are still associated with the MR when attempting to close, the call will return -FI\_EBUSY. If a memory registration cache is used, the behavior of fi\_close may be affected. More information on the memory registration cache is in the MEMORY REGISTRATION CACHE section. ### fi\_mr\_desc Obtains the local memory descriptor associated with a MR. The memory registration must have completed successfully before invoking this call. ### fi\_mr\_get\_xpu\_desc The fi\_mr\_get\_xpu\_desc call retrieves a provider-specific raw descriptor (e.g., the hardware lkey) for the MR into a caller-supplied buffer. The caller allocates buf and sets *len to the buffer size on input;* *on output* len is set to the number of bytes written. If the buffer is too small, -FI\_ETOOSMALL is returned and \*len is set to the required size. When called with FI\_XPU flag and a valid fid\_xpu\_ctx, the returned descriptor is usable by the XPU when posting work requests. The needed size can also be obtained through the mr\_desc\_size field of fi\_xpu\_ctx\_attr from fi\_xpu\_ctx\_query. For non-XPU use cases, applications are encouraged to use fi\_mr\_desc instead, which returns the descriptor pointer directly. The MR is not bound to an XPU context — it is a shared domain-level resource. The same MR can be queried with different XPU contexts. See [fi\_xpu(3)](/fi_xpu/3.md) for details. ### fi\_mr\_key Returns the remote protection key associated with a MR. The memory registration must have completed successfully before invoking this. The returned key may be used in data transfer operations at a peer. If the FI\_MR\_RAW mode bit has been set for the domain, then the memory key must be obtained using the fi\_mr\_raw\_attr function instead. A return value of FI\_KEY\_NOTAVAIL will be returned if the registration has not completed or a raw memory key is required. ### fi\_mr\_raw\_attr Returns the raw, remote protection key and base address associated with a MR. The memory registration must have completed successfully before invoking this routine. Use of this call is required if the FI\_MR\_RAW mode bit has been set by the provider; however, it is safe to use this call with any memory region. On input, the key\_size parameter should indicate the size of the raw\_key buffer. If the actual key is larger than what can fit into the buffer, it will return -FI\_ETOOSMALL. On output, key\_size is set to the size of the buffer needed to store the key, which may be larger than the input value. The needed key\_size can also be obtained through the mr\_key\_size domain attribute (fi\_domain\_attr) field. A raw key must be mapped by a peer before it can be used in data transfer operations. See fi\_mr\_map\_raw below. ### fi\_mr\_map\_raw Raw protection keys must be mapped to a usable key value before they can be used for data transfer operations. The mapping is done by the peer that initiates the RMA or atomic operation. The mapping function takes as input the raw key and its size, and returns the mapped key. Use of the fi\_mr\_map\_raw function is required if the peer has the FI\_MR\_RAW mode bit set, but this routine may be called on any valid key. All mapped keys must be freed by calling fi\_mr\_unmap\_key when access to the peer memory region is no longer necessary. ### fi\_mr\_unmap\_key This call releases any resources that may have been allocated as part of mapping a raw memory key. All mapped keys must be freed before the corresponding domain is closed. ### fi\_mr\_bind The fi\_mr\_bind function associates a memory region with a counter or endpoint. Counter bindings are needed by providers that support the generation of completions based on fabric operations. Endpoint bindings are needed if the provider associates memory regions with endpoints (see FI\_MR\_ENDPOINT). When binding with a counter, the type of events tracked against the memory region is based on the bitwise OR of the following flags. - *FI\_REMOTE\_WRITE* Generates an event whenever a remote RMA write or atomic operation modifies the memory region. Use of this flag requires that the endpoint through which the MR is accessed be created with the FI\_RMA\_EVENT capability. When binding the memory region to an endpoint, flags should be 0. ### fi\_mr\_refresh The use of this call is to notify the provider of any change to the physical pages backing a registered memory region. This call must be supported by providers requiring FI\_MR\_MMU\_NOTIFY and may optionally be supported by providers not requiring FI\_MR\_ALLOCATED. This call informs the provider that the page table entries associated with the region may have been modified, and the provider should verify and update the registered region accordingly. The iov parameter is optional and may be used to specify which portions of the registered region requires updating. Providers are only guaranteed to update the specified address ranges. Failing to update a range will result in an error being returned. When FI\_MR\_MMU\_NOTIFY is set, the refresh operation has the effect of disabling and re-enabling access to the registered region. Any operations from peers that attempt to access the region will fail while the refresh is occurring. Additionally, attempts to access the region by the local process through libfabric APIs may result in a page fault or other fatal operation. When FI\_MR\_ALLOCATED is unset, -FI\_ENOSYS will be returned if a provider does not support fi\_mr\_refresh. If supported, the provider will atomically update physical pages of the MR associated with the user specified address ranges. The MR will remain enabled during this time. Note: FI\_MR\_MMU\_NOTIFY set behavior takes precedence over FI\_MR\_ALLOCATED unset behavior. The fi\_mr\_refresh call is only needed if the physical pages might have been updated after the memory region was created. ### fi\_mr\_enable The enable call is used with memory registration associated with the FI\_MR\_RMA\_EVENT mode bit. Memory regions created in the disabled state must be explicitly enabled after being fully configured by the application. Any resource bindings to the MR must be done prior to enabling the MR. ## MEMORY REGION ATTRIBUTES Memory regions are created using the following attributes. The struct fi\_mr\_attr is passed into fi\_mr\_regattr, but individual fields also apply to other memory registration calls, with the fields passed directly into calls as function parameters. - ``` struct fi_mr_attr { union { const struct iovec *mr_iov; const struct fi_mr_dmabuf *dmabuf; }; size_t iov_count; uint64_t access; uint64_t offset; uint64_t requested_key; void *context; size_t auth_key_size; uint8_t *auth_key; enum fi_hmem_iface iface; union { uint64_t reserved; int cuda; int ze int neuron; int synapseai; int rocr; } device; void *hmem_data; size_t page_size; const struct fid_mr *base_mr; size_t sub_mr_cnt; }; struct fi_mr_auth_key { struct fid_av *av; fi_addr_t src_addr; }; ``` ### mr\_iov This is an IO vector of virtual addresses and their length that represent a single memory region. The number of entries in the iovec is specified by iov\_count. ### dmabuf DMA-buf registrations are used to share device memory between a given device and the fabric NIC and does not require that the device memory be mmap’ed into the virtual address space of the calling process. This structure references a DMA-buf backed device memory region. This field is only usable if the application has successfully requested support for FI\_HMEM and the FI\_MR\_DMABUF flag is passed into the memory registration call. DMA-buf regions are file-based references to device memory. Such regions are identified through the struct fi\_mr\_dmabuf. - ``` struct fi_mr_dmabuf { int fd; uint64_t offset; size_t len; void *base_addr; }; ``` The fd is the file descriptor associated with the DMA-buf region. The offset is the offset into the region where the memory registration should begin. And len is the size of the region to register, starting at the offset. The base\_addr is the page-aligned starting virtual address of the memory region allocated by the DMA-buf. If a base virtual address is not available (because, for example, the calling process has not mapped the memory region into its address space), base\_addr can be set to NULL. The selection of dmabuf over the mr\_iov field is controlled by specifying the FI\_MR\_DMABUF flag. ### iov\_count The number of entries in the mr\_iov array. The maximum number of memory buffers that may be associated with a single memory region is specified as the mr\_iov\_limit domain attribute. See [fi\_domain(3)](/fi_domain/3.md). ### access Indicates the type of *operations* that the local or a peer endpoint may perform on registered memory region. Supported access permissions are the bitwise OR of the following flags: - *FI\_SEND* The memory buffer may be used in outgoing message data transfers. This includes fi\_msg and fi\_tagged send operations, as well as fi\_collective operations. - *FI\_RECV* The memory buffer may be used to receive inbound message transfers. This includes fi\_msg and fi\_tagged receive operations, as well as fi\_collective operations. - *FI\_READ* The memory buffer may be used as the result buffer for RMA read and atomic operations on the initiator side. Note that from the viewpoint of the application, the memory buffer is being written into by the network. - *FI\_WRITE* The memory buffer may be used as the source buffer for RMA write and atomic operations on the initiator side. Note that from the viewpoint of the application, the endpoint is reading from the memory buffer and copying the data onto the network. - *FI\_REMOTE\_READ* The memory buffer may be used as the source buffer of an RMA read operation on the target side. The contents of the memory buffer are not modified by such operations. - *FI\_REMOTE\_WRITE* The memory buffer may be used as the target buffer of an RMA write or atomic operation. The contents of the memory buffer may be modified as a result of such operations. - *FI\_COLLECTIVE* This flag provides an explicit indication that the memory buffer may be used with collective operations. Use of this flag is required if the FI\_MR\_COLLECTIVE mr\_mode bit has been set on the domain. This flag should be paired with FI\_SEND and/or FI\_RECV Note that some providers may not enforce fine grained access permissions. For example, a memory region registered for FI\_WRITE access may also behave as if FI\_SEND were specified as well. Relaxed enforcement of such access is permitted, though not guaranteed, provided security is maintained. ### offset The offset field is reserved for future use and must be 0. ### requested\_key An application specified access key associated with the memory region. The MR key must be provided by a remote process when performing RMA or atomic operations to a memory region. Applications can use the requested\_key field to indicate that a specific key be used by the provider. This allows applications to use well known key values, which can avoid applications needing to exchange and store keys. Support for user requested keys is provider specific and is determined by the the FI\_MR\_PROV\_KEY flag in the mr\_mode domain attribute field. Depending on the provider, the user requested key may be ignored if the memory region is for local access only. A provider may be unable to do so if the hardware supports user requested keys and the same key is used for both local and remote access. ### context Application context associated with asynchronous memory registration operations. This value is returned as part of any asynchronous event associated with the registration. This field is ignored for synchronous registration calls. ### auth\_key\_size The size of key referenced by the auth\_key field in bytes, or 0 if no authorization key is given. This field is ignored unless the fabric is opened with API version 1.5 or greater. If the domain is opened with FI\_AV\_AUTH\_KEY, auth\_key\_size must equal sizeof(struct fi\_mr\_auth\_key). ### auth\_key Indicates the key to associate with this memory registration. Authorization keys are used to limit communication between endpoints. Only peer endpoints that are programmed to use the same authorization key may access the memory region. The domain authorization key will be used if the auth\_key\_size provided is 0. This field is ignored unless the fabric is opened with API version 1.5 or greater. If the domain is opened with FI\_AV\_AUTH\_KEY, auth\_key must point to a user-defined struct fi\_mr\_auth\_key. ### iface Indicates the software interfaces used by the application to allocate and manage the memory region. This field is ignored unless the application has requested the FI\_HMEM capability. - *FI\_HMEM\_SYSTEM* Uses standard operating system calls and libraries, such as malloc, calloc, realloc, mmap, and free. When iface is set to FI\_HMEM\_SYSTEM, the device field (described below) is ignored. - *FI\_HMEM\_CUDA* Uses Nvidia CUDA interfaces such as cuMemAlloc, cuMemAllocHost, cuMemAllocManaged, cuMemFree, cudaMalloc, cudaFree. - *FI\_HMEM\_ROCR* Uses AMD ROCR interfaces such as hsa\_memory\_allocate and hsa\_memory\_free. - *FI\_HMEM\_ZE* Uses oneAPI Level Zero interfaces such as zeDriverAllocSharedMem, zeDriverFreeMem. - *FI\_HMEM\_NEURON* Uses the AWS Neuron SDK to support AWS Trainium devices. - *FI\_HMEM\_SYNAPSEAI* Uses the SynapseAI API to support Habana Gaudi devices. ### device Reserved 64 bits for device identifier if using non-standard HMEM interface. This field is ignore unless the iface field is valid. Otherwise, the device field is determined by the value specified through iface. - *cuda* For FI\_HMEM\_CUDA, this is equivalent to CUdevice (int). - *ze* For FI\_HMEM\_ZE, this is equivalent to the index of the device in the ze\_device\_handle\_t array. If there is only a single level zero driver present, an application may set this directly. However, it is recommended that this value be set using the fi\_hmem\_ze\_device() macro, which will encode the driver index with the device. - *neuron* For FI\_HMEM\_NEURON, the device identifier for AWS Trainium devices. - *synapseai* For FI\_HMEM\_SYNAPSEAI, the device identifier for Habana Gaudi hardware. - *rocr* For FI\_HMEM\_ROCR, the device index for an AMD GPU. ### hmem\_data The hmem\_data field is reserved for future use and must be null. ### page\_size Page size allows applications to optionally provide a hint at what the optimal page size is for the an MR allocation. Typically, providers can select the optimal page size. In cases where VA range has zero pages backing it, which is supported with FI\_MR\_ALLOCATED unset, the provider may not know the optimal page size during registration. Rather than use a less efficient page size, this attribute allows applications to specify the page size to be used. If page size is zero, provider will select the page size. If non-zero, page size must be supported by OS. If a specific page size is specified for a memory region during creation, all pages later associated with the region must be of the given size. Attaching a memory page of a different size to a region may result in failed transfers to or from the region. Providers may choose to ignore page size. This will result in a provider selected page size always being used. ### base\_mr If non-NULL, create a sub-MR from an existing memory region specified by the base\_mr field. The sub-MR must be fully contained within the base MR; however, the sub-MR has its own authorization keys and access rights. The following attributes are inherited from the base MR, and as a result, are ignored when creating the sub-MR: iface, device, hmem\_data, page\_size The sub-MR should hold a reference to the base MR. When fi\_close is called on the base MR, the call would fail if there are any outstanding sub-MRs. The base\_mr field must be NULL if the FI\_MR\_DMABUF flag is set. ### sub\_mr\_cnt The number of sub-MRs expected to be created from the memory region. This value is not a limit. Instead, it is a hint to the provider to allow provider specific optimization for sub-MR creation. For example, the provider may reserve access keys or pre-allocation fid\_mr objects. The provider may ignore this hint. ### fi\_hmem\_ze\_device Returns an hmem device identifier for a level zero \ tuple. The output of this call should be used to set fi\_mr\_attr::device.ze for FI\_HMEM\_ZE interfaces. The driver and device index values represent their 0-based positions in arrays returned from zeDriverGet and zeDeviceGet, respectively. ### av For memory registration being allocated against a domain configured with FI\_AV\_AUTH\_KEY, av is used to define the fid\_av which contains the authorization keys to be associated with the memory region. If the domain is also opened with FI\_MR\_ENDPOINT, the specified AV must be the same AV bound to the endpoint. By default, the memory region will be associated with all authorization keys in the AV. ### addr If the domain was opened with FI\_DIRECTED\_RECV, addr can be used to limit the memory region to a specific fi\_addr\_t, including fi\_addr\_t’s return from fi\_av\_insert\_auth\_key. ## NOTES Direct access to an application’s memory by a remote peer requires that the application register the targeted memory buffer(s). This is typically done by calling one of the fi\_mr\_reg\* routines. For FI\_MR\_PROV\_KEY, the provider will return a key that must be used by the peer when accessing the memory region. The application is responsible for transferring this key to the peer. If FI\_MR\_RAW mode has been set, the key must be retrieved using the fi\_mr\_raw\_attr function. FI\_MR\_RAW allows support for providers that require more than 8-bytes for their protection keys or need additional setup before a key can be used for transfers. After a raw key has been retrieved, it must be exchanged with the remote peer. The peer must use fi\_mr\_map\_raw to convert the raw key into a usable 64-bit key. The mapping must be done even if the raw key is 64-bits or smaller. The raw key support functions are usable with all registered memory regions, even if FI\_MR\_RAW has not been set. It is recommended that portable applications target using those interfaces; however, their use does carry extra message and memory footprint overhead, making it less desirable for highly scalable apps. There may be cases where device peer to peer support should not be used or cannot be used, such as when the PCIe ACS configuration does not permit the transfer. The FI\_HMEM\_DISABLE\_P2P environment variable can be set to notify Libfabric that peer to peer transactions should not be used. The provider may choose to perform a copy instead, or will fail support for FI\_HMEM if the provider is unable to do that. ## FLAGS The follow flag may be specified to any memory registration call. - *FI\_RMA\_EVENT* This flag indicates that the specified memory region will be associated with a completion counter used to count RMA operations that access the MR. - *FI\_RMA\_PMEM* This flag indicates that the underlying memory region is backed by persistent memory and will be used in RMA operations. It must be specified if persistent completion semantics or persistent data transfers are required when accessing the registered region. - *FI\_HMEM\_DEVICE\_ONLY* This flag indicates that the memory is only accessible by a device. Which device is specified by the fi\_mr\_attr fields iface and device. This refers to memory regions that were allocated using a device API AllocDevice call (as opposed to using the host allocation or unified/shared memory allocation). This flag is only usable for domains opened with FI\_HMEM capability support. - *FI\_HMEM\_HOST\_ALLOC* This flag indicates that the memory is owned by the host only. Whether it can be accessed by the device is implementation dependent. The fi\_mr\_attr field iface is still used to identify the device API, but the field device is ignored. This refers to memory regions that were allocated using a device API AllocHost call (as opposed to using malloc-like host allocation, unified/shared memory allocation, or AllocDevice). This flag is only usable for domains opened with FI\_HMEM capability support. - *FI\_MR\_DMABUF* This flag indicates that the memory region to registered is a DMA-buf backed region. When set, the region is specified through the dmabuf field of the fi\_mr\_attr structure. This flag is only usable for domains opened with FI\_HMEM capability support. - *FI\_MR\_SINGLE\_USE* This flag indicates that the memory region is only used for a single operation. After the operation is complete, the key associated with the memory region is automatically invalidated and can no longer be used for remote access. - *FI\_AUTH\_KEY* Only valid with domains configured with FI\_AV\_AUTH\_KEY. When used with fi\_mr\_regattr, this flag denotes that the fi\_mr\_auth\_key::src\_addr field contains an authorization key fi\_addr\_t (i.e. fi\_addr\_t returned from fi\_av\_insert\_auth\_key) instead of an endpoint fi\_addr\_t (i.e. fi\_addr\_t return from fi\_av\_insert / fi\_av\_insertsvc / fi\_av\_remove). ## MEMORY DOMAINS Memory domains identify the physical separation of memory which may or may not be accessible through the same virtual address space. Traditionally, applications only dealt with a single memory domain, that of host memory tightly coupled with the system CPUs. With the introduction of device and non-uniform memory subsystems, applications often need to be aware of which memory domain a particular virtual address maps to. As a general rule, separate physical devices can be considered to have their own memory domains. For example, a NIC may have user accessible memory, and would be considered a separate memory domain from memory on a GPU. Both the NIC and GPU memory domains are separate from host system memory. Individual GPUs or computation accelerators may have distinct memory domains, or may be connected in such a way (e.g. a GPU specific fabric) that all GPUs would belong to the same memory domain. Unfortunately, identifying memory domains is specific to each system and its physical and/or virtual configuration. Understanding memory domains in heterogenous memory environments is important as it can impact data ordering and visibility as viewed by an application. It is also important to understand which memory domain an application is most tightly coupled to. In most cases, applications are tightly coupled to host memory. However, an application running directly on a GPU or NIC may be more tightly coupled to memory associated with those devices. Memory regions are often associated with a single memory domain. The domain is often indicated by the fi\_mr\_attr iface and device fields. Though it is possible for physical pages backing a virtual memory region to migrate between memory domains based on access patterns. For example, the physical pages referenced by a virtual address range could migrate between host memory and GPU memory, depending on which computational unit is actively using it. See the [fi\_endpoint(3)](/fi_endpoint/3.md) and [fi\_cq(3)](/fi_cq/3.md) man pages for addition discussion on message, data, and completion ordering semantics, including the impact of memory domains. ## RETURN VALUES Returns 0 on success. On error, a negative value corresponding to fabric errno is returned. fi\_mr\_get\_xpu\_desc returns -FI\_ETOOSMALL if the provided buffer is too small; \*len is updated to the required size. Returns -FI\_EINVAL if an invalid XPU context is provided. Fabric errno values are defined in rdma/fi\_errno.h. ## ERRORS - *-FI\_ENOKEY* The requested\_key is already in use. - *-FI\_EKEYREJECTED* The requested\_key is not available. They key may be out of the range supported by the provider, or the provider may not support user-requested memory registration keys. - *-FI\_ENOSYS* Returned by fi\_mr\_bind if the provider does not support reporting events based on access to registered memory regions. - *-FI\_EBADFLAGS* Returned if the specified flags are not supported by the provider. ## MEMORY REGISTRATION CACHE Many hardware NICs accessed by libfabric require that data buffers be registered with the hardware while the hardware accesses it. This ensures that the virtual to physical address mappings for those buffers do not change while the transfer is occurring. The performance impact of registering memory regions can be significant. As a result, some providers make use of a registration cache, particularly when working with applications that are unable to manage their own network buffers. A registration cache avoids the overhead of registering and unregistering a data buffer with each transfer. If a registration cache is going to be used for host and device memory, the device must support unified virtual addressing. If the device does not support unified virtual addressing, either an additional registration cache is required to track this device memory, or device memory cannot be cached. As a general rule, if hardware requires the FI\_MR\_LOCAL mode bit described above, but this is not supported by the application, a memory registration cache *may* be in use. The following environment variables may be used to configure registration caches. - *FI\_MR\_CACHE\_MAX\_SIZE* This defines the total number of bytes for all memory regions that may be tracked by the cache. If not set, the cache has no limit on how many bytes may be registered and cached. Setting this will reduce the amount of memory that is not actively being used as part of a data transfer that is registered with a provider. By default, the cache size is unlimited. - *FI\_MR\_CACHE\_MAX\_COUNT* This defines the total number of memory regions that may be registered with the cache. If not set, a default limit is chosen. Setting this will reduce the number of regions that are registered, regardless of their size, which are not actively being used as part of a data transfer. Setting this to zero will disable registration caching. - *FI\_MR\_CACHE\_MONITOR* The cache monitor is responsible for detecting system memory (FI\_HMEM\_SYSTEM) changes made between the virtual addresses used by an application and the underlying physical pages. Valid monitor options are: userfaultfd, memhooks, kdreg2, and disabled. Selecting disabled will turn off the registration cache. Userfaultfd is a Linux kernel feature used to report virtual to physical address mapping changes to user space. Memhooks operates by intercepting relevant memory allocation and deallocation calls which may result in the mappings changing, such as malloc, mmap, free, etc. Note that memhooks operates at the elf linker layer, and does not use glibc memory hooks. Kdreg2 is supplied as a loadable Linux kernel module. - *FI\_MR\_CUDA\_CACHE\_MONITOR\_ENABLED* The CUDA cache monitor is responsible for detecting CUDA device memory (FI\_HMEM\_CUDA) changes made between the device virtual addresses used by an application and the underlying device physical pages. Valid monitor options are: 0 or 1. Note that the CUDA memory monitor requires a CUDA toolkit version with unified virtual addressing enabled. - *FI\_MR\_ROCR\_CACHE\_MONITOR\_ENABLED* The ROCR cache monitor is responsible for detecting ROCR device memory (FI\_HMEM\_ROCR) changes made between the device virtual addresses used by an application and the underlying device physical pages. Valid monitor options are: 0 or 1. Note that the ROCR memory monitor requires a ROCR version with unified virtual addressing enabled. - *FI\_MR\_ZE\_CACHE\_MONITOR\_ENABLED* The ZE cache monitor is responsible for detecting oneAPI Level Zero device memory (FI\_HMEM\_ZE) changes made between the device virtual addresses used by an application and the underlying device physical pages. Valid monitor options are: 0 or 1. More direct access to the internal registration cache is possible through the fi\_open() call, using the “mr\_cache” service name. Once opened, custom memory monitors may be installed. A memory monitor is a component of the cache responsible for detecting changes in virtual to physical address mappings. Some level of control over the cache is possible through the above mentioned environment variables. ## SEE ALSO [fi\_getinfo(3)](/fi_getinfo/3.md), [fi\_endpoint(3)](/fi_endpoint/3.md), [fi\_domain(3)](/fi_domain/3.md), [fi\_rma(3)](/fi_rma/3.md), [fi\_msg(3)](/fi_msg/3.md), [fi\_atomic(3)](/fi_atomic/3.md) ## AUTHORS OpenFabrics.