[RFC,rdma-core] verbs: add ibv_export_to_fd man page

Commit Message

Shamir Rabinovitch June 25, 2019, 9:21 a.m. UTC

Signed-off-by: Shamir Rabinovitch <[e-mail]>
---
 libibverbs/man/ibv_export_to_fd.3 | 99 +++++++++++++++++++++++++++++++
 1 file changed, 99 insertions(+)
 create mode 100644 libibverbs/man/ibv_export_to_fd.3

Comments

Jason Gunthorpe June 25, 2019, 11:53 a.m. UTC | #1

On Tue, Jun 25, 2019 at 12:21:13PM +0300, Shamir Rabinovitch wrote:
> Signed-off-by: Shamir Rabinovitch <[e-mail]>
>  libibverbs/man/ibv_export_to_fd.3 | 99 +++++++++++++++++++++++++++++++
>  1 file changed, 99 insertions(+)
>  create mode 100644 libibverbs/man/ibv_export_to_fd.3

all new man pages must be in markdown.

Jason

Patch

diff --git a/libibverbs/man/ibv_export_to_fd.3 b/libibverbs/man/ibv_export_to_fd.3
new file mode 100644
index 00000000..e3e06bb0
--- /dev/null
+++ b/libibverbs/man/ibv_export_to_fd.3
@@ -0,0 +1,99 @@ 
+.\" -*- nroff -*-
+.\" Licensed under the OpenIB.org BSD license (FreeBSD Variant) - See COPYING.md
+.\"
+.TH IBV_EXPORT_TO_FD 3 2019-06-20 libibverbs "Libibverbs Programmer's Manual"
+.SH "NAME"
+ibv_export_to_fd, ibv_import_x \- exports ib hw object (e.g. pd) from current context to the
+.B export context.
+ibv_import_x import the ib hw object from the
+.B export context
+to the current context (e.g. ibv_import_pd).
+.SH "SYNOPSIS"
+.nf
+.B #include <infiniband/verbs.h>
+.sp
+.BI "int ibv_export_to_fd(uint32_t " "fd" ,
+.BI "                     uint32_t " "*new_handle" ,
+.BI "                     struct ibv_context " "*context" ,
+.BI "                     enum uverbs_default_objects " "type" ,
+.BI "                     uint32_t " "handle");
+.sp
+.BI "struct ibv_pd *ibv_import_pd(struct ibv_context " "*context" ,
+.BI "                             uint32_t " "fd" ,
+.BI "                             uint32_t " "handle");
+.sp
+.BI "struct ibv_mr *ibv_import_mr(struct ibv_context " "*context" ,
+.BI "                             uint32_t " "fd" ,
+.BI "                             uint32_t " "handle");
+.sp
+.BI "uint32_t ibv_context_to_fd(struct ibv_context " "*context");
+.sp
+.BI "uint32_t ibv_pd_to_handle(struct ibv_pd " "*pd");
+.sp
+.BI "uint32_t ibv_mr_to_handle(struct ibv_mr " "*mr");
+.fi
+.SH "DESCRIPTION"
+.B ibv_export_to_fd()
+export ib hw object (pd, mr,...) from context to another context represented by the file descriptor fd. The destination context (file descriptor) can then be shared with other processes via unix socket SCM_RIGHTS. Once shared, the destination process can import the exported objects from the shared file descriptor to it's current context by using the equivalent ibv_import_x (e.g. ibv_import_pd) verb which return ib hw object. The destruction of the imported object is done by using the ib hw object destroy verb (e.g. ibv_dealloc_pd).
+.PP
+.B fd
+is the destination context's file descriptor.
+.PP
+.B new_handle
+is the handle of the new object.
+.PP
+.B context
+is the context to export the object from
+.PP
+.B type
+is the type of the object being exported (e.g. UVERBS_OBJECT_PD)
+.PP
+.B handle
+is the handle of the object being exported.
+.PP
+.nf
+To export object (e.g. pd), the below steps should be taken:
+
+1. Allocate new shared context (ibv_open_device)
+2. Get the new context file descriptor (ibv_context_to_fd)
+3. Get the ib hw object handle (e.g. ibv_pd_to_handle)
+4. Export the ib hw object to the file descriptor (ibv_export_to_fd)
+.fi
+.P
+.B ibv_import_pd(), ibv_import_mr()
+import pd/mr previously exported via
+.B export context
+.P
+.B context
+the context to import the ib hw object to
+.P
+.B fd
+is the source context's file descriptor.
+.P
+.B handle
+the handle the the exported object in the
+.B export context
+as returned from
+.B ibv_export_to_fd()
+.P
+.B ibv_context_to_fd()
+returs the file descriptor of the given context
+.P
+.B ibv_pd_to_handle(), ibv_mr_to_handle()
+returns the ib hw object handle from the given object
+.SH "RETURN VALUE"
+.B ibv_export_to_fd()
+\- returns 0 on success, or the value of errno on failure (which indicates the failure reason).
+.P
+.B ibv_import_pd(), ibv_import_mr()
+\- returns a pointer to the imported ib hw object, or NULL if the request fails.
+.SH "NOTES"
+The destination context for this verb can be
+.B ANY
+context including the source context.
+.SH "SEE ALSO"
+.BR ibv_dealloc_pd (3),
+.BR ibv_dereg_mr (3),
+.SH "AUTHORS"
+.TP
+Shamir Rabinovitch <[e-mail]>