diff mbox series

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

Message ID 20190626083614.23688-1-shamir.rabinovitch@oracle.com (mailing list archive)
State RFC
Headers show
Series [RFC,rdma-core] verbs: add ibv_export_to_fd man page | expand

Commit Message

Shamir Rabinovitch June 26, 2019, 8:36 a.m. UTC 
Add the ibv_export_to_fd man page.

Signed-off-by: Shamir Rabinovitch <shamir.rabinovitch@oracle.com>
---
 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

Comments

Yuval Shaia June 26, 2019, 12:46 p.m. UTC | #1 
On Wed, Jun 26, 2019 at 11:36:14AM +0300, Shamir Rabinovitch wrote:
> Add the ibv_export_to_fd man page.

This is RFC but still suggesting to give some words here.

Also, subject is incorrect since man page is for all functions involved in
the shared-obj mechanism, not only the export_to_fd.

> 
> Signed-off-by: Shamir Rabinovitch <shamir.rabinovitch@oracle.com>
> ---
>  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
> 
> 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..8e3f0fb2
> --- /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);

Do you know if extra stuff besides this new file needs to be done so i can
do ex man ibv_context_to_fd and get this man page?

> +
> +```
> +
> +# DESCRIPTION
> +
> +**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

s/export/exports
s/from context/from one context

> +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

s/then  be/then be
s/via unix socket SCM_RIGHTS/by passing it via unix socket SCM_RIGHTS

> +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**() returs the file descriptor of the given context.

s/returs/returns

> +
> +**ibv_pd_to_handle**(), **ibv_mr_to_handle**() returns the ib hw object handle from the given object.

s/from the/of a

> +
> +# 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* the handle the the exported object in the export context as returned from *ibv_export_to_fd*().

s/the handle the the exported/is the handle of the exported

> +
> +**ibv_context_to_fd**()
> +
> +*context* context obtained from **ibv_open_device**() verb.

Missing 'is'? (just to be consist with your other variables description)

> +
> +**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. 

Redundant '-' (to be consist.... -:))

> +
> +**ibv_context_to_fd**() returs the file descriptor of the given context.

s/returs/returns

> +
> +**ibv_pd_to_handle**(), **ibv_mr_to_handle**() returns the ib hw object handle from the given object

Missing '.' at EOL (to be cons....)

> +
> +# SEE ALSO
> +
> +**ibv_dealloc_pd**(3), **ibv_dereg_mr**(3)
> +
> +# AUTHORS
> +
> +Shamir Rabinovitch <shamir.rabinovitch@oracle.com>
> -- 
> 2.21.0
>
Jason Gunthorpe July 2, 2019, 10:48 p.m. UTC | #2 
On Wed, Jun 26, 2019 at 03:46:39PM +0300, Yuval Shaia wrote:
> On Wed, Jun 26, 2019 at 11:36:14AM +0300, Shamir Rabinovitch wrote:
> > Add the ibv_export_to_fd man page.
> 
> This is RFC but still suggesting to give some words here.
> 
> Also, subject is incorrect since man page is for all functions involved in
> the shared-obj mechanism, not only the export_to_fd.
> 
> > 
> > Signed-off-by: Shamir Rabinovitch <shamir.rabinovitch@oracle.com>
> >  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
> > 
> > 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..8e3f0fb2
> > +++ 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);

This should probably be some internal function and the exports should
be type safe just like the imports.

> > +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);
> 
> Do you know if extra stuff besides this new file needs to be done so i can
> do ex man ibv_context_to_fd and get this man page?

Yes, they need to be setup in cmake with aliases.

I think this man page is kind of terse for such a complicated
thing. 

Ie it doesn't talk about what happens when close() or ibv_destroy_X()
is called.

Jason
Yuval Shaia July 4, 2019, 1:41 p.m. UTC | #3 
On Tue, Jul 02, 2019 at 07:48:07PM -0300, Jason Gunthorpe wrote:
> On Wed, Jun 26, 2019 at 03:46:39PM +0300, Yuval Shaia wrote:
> > On Wed, Jun 26, 2019 at 11:36:14AM +0300, Shamir Rabinovitch wrote:
> > > Add the ibv_export_to_fd man page.
> > 
> > This is RFC but still suggesting to give some words here.
> > 
> > Also, subject is incorrect since man page is for all functions involved in
> > the shared-obj mechanism, not only the export_to_fd.
> > 
> > > 
> > > Signed-off-by: Shamir Rabinovitch <shamir.rabinovitch@oracle.com>
> > >  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
> > > 
> > > 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..8e3f0fb2
> > > +++ 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);
> 
> This should probably be some internal function and the exports should
> be type safe just like the imports.

So you suggesting something like this (instead of passing handle as arg):

int ibv_export_pd(uint32_t fd,
		  uint32_t *new_handle,
		  struct ibv_context *context,
		  struct ib_pd* pd);

int ibv_export_mr(uint32_t fd,
		  uint32_t *new_handle,
		  struct ibv_context *context,
		  struct ib_mr* mr);

So the handle is taken internally from the pd or mr  arg.

Are you still ok with new_handle? asking as this is what is used in the
ibv_import_xxx functions.

> 
> > > +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);
> > 
> > Do you know if extra stuff besides this new file needs to be done so i can
> > do ex man ibv_context_to_fd and get this man page?
> 
> Yes, they need to be setup in cmake with aliases.

Will take care of it, thanks.

> 
> I think this man page is kind of terse for such a complicated
> thing. 
> 
> Ie it doesn't talk about what happens when close() or ibv_destroy_X()
> is called.

We've mentioned that the returned object is like a regular object returned
from (ex) ibv_create_pd and should be destroyed with the corresponding
destroy function.
We can add a note saying that the HW object will be destroyed only when all
reference to it will be destroyed.
Is that enough?

> 
> Jason
diff mbox series

Patch

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..8e3f0fb2
--- /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**() 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).
+
+## 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**() returs 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.
+
+# 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* the handle the the exported object in the export context as returned from *ibv_export_to_fd*().
+
+**ibv_context_to_fd**()
+
+*context* 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**() returs 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>