# ibv_advise_mr

## NAME



           ibv_advise_mr - Gives advice or directions to the kernel about an
           address range belongs to a memory region (MR).
    


## SYNOPSIS



                  #include <infiniband/verbs.h>
    
                  int ibv_advise_mr(struct ibv_pd *pd,
                            enum ibv_advise_mr_advice advice,
                            uint32_t flags,
                            struct ibv_sge *sg_list,
                            uint32_t num_sge)
    


## DESCRIPTION



           **ibv_advise_mr()** Give advice or directions to the kernel about an
           address range belonging to a memory region (MR).  Applications
           that are aware of future access patterns can use this verb in
           order to leverage this knowledge to improve system or application
           performance.
    
           **Conventional advice values**
    
           _IBV_ADVISE_MR_ADVICE_PREFETCH_
                  Pre-fetch a range of an on-demand paging MR.  Make pages
                  present with read-only permission before the actual IO is
                  conducted.  This would provide a way to reduce latency by
                  overlapping paging-in and either compute time or IO to
                  other ranges.
    
           _IBV_ADVISE_MR_ADVICE_PREFETCH_WRITE_
                  Like IBV_ADVISE_MR_ADVICE_PREFETCH but with read-access and
                  write-access permission to the fetched memory.
    
           _IBV_ADVISE_MR_ADVICE_PREFETCH_NO_FAULT_
                  Pre-fetch a range of an on-demand paging MR without
                  faulting.  This allows presented pages in the CPU to become
                  presented to the device.
    


## ARGUMENTS



           _pd_     The protection domain (PD) associated with the MR.
    
           _advice_ The requested advise value (as listed above).
    
           _flags_  Describes the properties of the advise operation
                  **Conventional advice values** _IBV_ADVISE_MR_FLAG_FLUSH_ :
                  Request to be a synchronized operation.  Return to the
                  caller after the operation is completed.
    
           _sg_list_
                  Pointer to the s/g array When using IBV_ADVISE_OP_PREFETCH
                  advise value, all the lkeys of all the scatter gather
                  elements (SGEs) must be associated with ODP MRs (MRs that
                  were registered with IBV_ACCESS_ON_DEMAND).
    
           _num_sge_
                  Number of elements in the s/g array
    


## RETURN VALUE



           **ibv_advise_mr()** returns 0 when the call was successful, or the
           value of errno on failure (which indicates the failure reason).
    
           _EOPNOTSUPP_
                  libibverbs or provider driver doesn’t support the
                  ibv_advise_mr() verb (ENOSYS may sometimes be returned by
                  old versions of libibverbs).
    
           _ENOTSUP_
                  The advise operation isn’t supported.
    
           _EFAULT_ In one of the following: o When the range requested is out
                  of the MR bounds, or when parts of it are not part of the
                  process address space.  o One of the lkeys provided in the
                  scatter gather list is invalid or with wrong write access.
    
           _EINVAL_ In one of the following: o The PD is invalid.  o The flags
                  are invalid.  o The requested address doesn’t belong to a
                  MR, but a MW or something.
    
           _EPERM_  In one of the following: o Referencing a valid lkey outside
                  the caller’s security scope.  o The advice is
                  IBV_ADVISE_MR_ADVICE_PREFETCH_WRITE but the specified MR in
                  the scatter gather list is not registered as writable
                  access.
    
           _ENOENT_ The providing lkeys aren’t consistent with the MR’s.
    
           _ENOMEM_ Not enough memory.  # NOTES
    
           An application may pre-fetch any address range within an ODP MR
           when using the **IBV_ADVISE_MR_ADVICE_PREFETCH** or
           **IBV_ADVISE_MR_ADVICE_PREFETCH_WRITE** advice.  Semantically, this
           operation is best-effort.  That means the kernel does not
           guarantee that underlying pages are updated in the HCA or the
           pre-fetched pages would remain resident.
    
           When using **IBV_ADVISE_MR_ADVICE_PREFETCH** or
           **IBV_ADVISE_MR_ADVICE_PREFETCH_WRITE** advice, the operation will be
           done in the following stages: o Page in the user pages to memory
           (pages aren’t pinned).  o Get the dma mapping of these user pages.
           o Post the underlying page translations to the HCA.
    
           If **IBV_ADVISE_MR_FLAG_FLUSH** is specified then the underlying pages
           are guaranteed to be updated in the HCA before returning SUCCESS.
           Otherwise the driver can choose to postpone the posting of the new
           translations to the HCA.  When performing a local RDMA access
           operation it is recommended to use IBV_ADVISE_MR_FLAG_FLUSH flag
           with one of the pre-fetch advices to increase probability that the
           pages translations are valid in the HCA and avoid future page
           faults.
    


* * *