[RFC,rdma-core,v2] verbs: add object export & import man page
diff mbox series

Message ID 20190626142630.8737-1-shamir.rabinovitch@oracle.com
State Not Applicable
Headers show
Series
  • [RFC,rdma-core,v2] verbs: add object export & import man page
Related show

Commit Message

Shamir Rabinovitch June 26, 2019, 2:26 p.m. UTC
Add the man page for object export & pd/mr import.

Signed-off-by: Shamir Rabinovitch <shamir.rabinovitch@oracle.com>
---

Changelog:

v1 -> v2: Review comments (Yuval)
v0 -> v1: Change to markdown format (Jason)

----
 libibverbs/man/ibv_export_to_fd.3.md | 109 +++++++++++++++++++++++++++
 1 file changed, 109 insertions(+)
 create mode 100644 libibverbs/man/ibv_export_to_fd.3.md

Patch
diff mbox series

diff --git a/libibverbs/man/ibv_export_to_fd.3.md b/libibverbs/man/ibv_export_to_fd.3.md
new file mode 100644
index 00000000..440210e8
--- /dev/null
+++ b/libibverbs/man/ibv_export_to_fd.3.md
@@ -0,0 +1,109 @@ 
+---
+date: 2018-06-26
+footer: libibverbs
+header: "Libibverbs Programmer's Manual"
+layout: page
+license: 'Licensed under the OpenIB.org BSD license (FreeBSD Variant) - See COPYING.md'
+section: 3
+title: ibv_export_to_fd
+tagline: Verbs
+---
+
+# NAME
+
+**ibv_export_to_fd**, **ibv_import_pd**, **ibv_import_mr** - export & import ib hw objects.
+
+# SYNOPSIS
+
+```c
+#include <infiniband/verbs.h>
+
+int ibv_export_to_fd(uint32_t fd,
+                     uint32_t *new_handle,
+                     struct ibv_context *context,
+                     enum uverbs_default_objects type,
+                     uint32_t handle);
+
+struct ibv_pd *ibv_import_pd(struct ibv_context *context,
+                             uint32_t fd,
+                             uint32_t handle);
+
+struct ibv_mr *ibv_import_mr(struct ibv_context *context,
+                             uint32_t fd,
+                             uint32_t handle);
+
+uint32_t ibv_context_to_fd(struct ibv_context *context);
+
+uint32_t ibv_pd_to_handle(struct ibv_pd *pd);
+
+uint32_t ibv_mr_to_handle(struct ibv_mr *mr);
+
+```
+
+# DESCRIPTION
+
+**ibv_export_to_fd**() exports ib hw object (pd, mr,...) from one context to another context represented by the file descriptor fd. The destination context (file descriptor) can
+then be shared with other processes by passing it 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).
+
+## 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).
+
+**ibv_import_pd**(), **ibv_import_mr**() import pd/mr previously exported via export context.
+
+**ibv_context_to_fd**() returns the file descriptor of a given context.
+
+**ibv_pd_to_handle**(), **ibv_mr_to_handle**() returns the ib hw object handle of a given object.
+
+# ARGUMENTS
+
+**ibv_export_to_fd**()
+
+*fd* is the destination context's file descriptor.
+
+*new_handle* is the handle of the new object.
+
+*context* is the context to export the object from.
+
+*type* is the type of the object being exported (e.g. UVERBS_OBJECT_PD).
+
+*handle* is the handle of the object being exported.
+
+**ibv_import_pd**(), **ibv_import_mr**()
+
+*context* the context to import the ib hw object to.
+
+*fd* is the source context's file descriptor.
+
+*handle* is the handle of the exported object in the export context as returned from *ibv_export_to_fd*().
+
+**ibv_context_to_fd**()
+
+*context* is the context obtained from **ibv_open_device**() verb.
+
+**ibv_pd_to_handle**(), **ibv_mr_to_handle**()
+
+*pd*, *mr* obtained from **ibv_alloc_pd**(), **ibv_reg_mr**() verbs.
+
+# RETURN VALUE
+
+**ibv_export_to_fd**() returns 0 on success, or the value of errno on failure (which indicates the failure reason).
+
+**ibv_import_pd**(), **ibv_import_mr**() returns a pointer to the imported ib hw object, or NULL if the request fails.
+
+**ibv_context_to_fd**() returns the file descriptor of the given context.
+
+**ibv_pd_to_handle**(), **ibv_mr_to_handle**() returns the ib hw object handle from the given object.
+
+# SEE ALSO
+
+**ibv_dealloc_pd**(3), **ibv_dereg_mr**(3)
+
+# AUTHORS
+
+Shamir Rabinovitch <shamir.rabinovitch@oracle.com>