.\" Automatically generated by Pandoc 1.19.2.4
.\"
.TH "IBV_ADVISE_MR" "3" "2018\-10\-19" "libibverbs" "Libibverbs Programmer\[aq]s Manual"
.hy
.SH NAME
.PP
ibv_advise_mr \- Gives advice or directions to the kernel about an
address range belongs to a memory region (MR).
.SH SYNOPSIS
.IP
.nf
\f[C]
#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)
\f[]
.fi
.SH DESCRIPTION
.PP
\f[B]ibv_advise_mr()\f[] 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.
.PP
\f[B]Conventional advice values\f[]
.TP
.B \f[I]IBV_ADVISE_MR_ADVICE_PREFETCH\f[]
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.
.RS
.RE
.TP
.B \f[I]IBV_ADVISE_MR_ADVICE_PREFETCH_WRITE\f[]
Like IBV_ADVISE_MR_ADVICE_PREFETCH but with read\-access and
write\-access permission to the fetched memory.
.RS
.RE
.SH ARGUMENTS
.TP
.B \f[I]pd\f[]
The protection domain (PD) associated with the MR.
.RS
.RE
.TP
.B \f[I]advice\f[]
The requested advise value (as listed above).
.RS
.RE
.TP
.B \f[I]flags\f[]
Describes the properties of the advise operation \f[B]Conventional
advice values\f[] \f[I]IBV_ADVISE_MR_FLAG_FLUSH\f[] : Request to be a
synchronized operation.
Return to the caller after the operation is completed.
.RS
.RE
.TP
.B \f[I]sg_list\f[]
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).
.RS
.RE
.TP
.B \f[I]num_sge\f[]
Number of elements in the s/g array
.RS
.RE
.SH RETURN VALUE
.PP
\f[B]ibv_advise_mr()\f[] returns 0 when the call was successful, or the
value of errno on failure (which indicates the failure reason).
.TP
.B \f[I]EOPNOTSUPP\f[]
libibverbs or provider driver doesn\[aq]t support the ibv_advise_mr()
verb (ENOSYS may sometimes be returned by old versions of libibverbs).
.RS
.RE
.TP
.B \f[I]ENOTSUP\f[]
The advise operation isn\[aq]t supported.
.RS
.RE
.TP
.B \f[I]EFAULT\f[]
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.
.RS
.RE
.TP
.B \f[I]EINVAL\f[]
In one of the following: o The PD is invalid.
o The flags are invalid.
.RS
.RE
.SH NOTES
.PP
An application may pre\-fetch any address range within an ODP MR when
using the \f[B]IBV_ADVISE_MR_ADVICE_PREFETCH\f[] or
\f[B]IBV_ADVISE_MR_ADVICE_PREFETCH_WRITE\f[] 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.
.PP
When using \f[B]IBV_ADVISE_MR_ADVICE_PREFETCH\f[] or
\f[B]IBV_ADVISE_MR_ADVICE_PREFETCH_WRITE\f[] advice, the operation will
be done in the following stages: o Page in the user pages to memory
(pages aren\[aq]t pinned).
o Get the dma mapping of these user pages.
o Post the underlying page translations to the HCA.
.PP
If \f[B]IBV_ADVISE_MR_FLAG_FLUSH\f[] 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.
.SH SEE ALSO
.PP
\f[B]ibv_reg_mr\f[](3), \f[B]ibv_rereg_mr\f[](3),
\f[B]ibv_dereg_mr\f[](3)
.SH AUTHOR
.PP
Aviad Yehezkel <aviadye@mellanox.com>