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

[Yuval Shaia <yuval.shaia@xxxxxxxxxx>]

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@xxxxxxxxxx>
> ---
>  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@xxxxxxxxxx>
> -- 
> 2.21.0
>