NAME

       mlx5dv_devx_obj_create - Creates a devx object

       mlx5dv_devx_obj_destroy - Destroys a devx object

       mlx5dv_devx_obj_modify - Modifies a devx object

       mlx5dv_devx_obj_query - Queries a devx object

       mlx5dv_devx_obj_query_async - Queries a devx object in an asynchronous mode

       mlx5dv_devx_general_cmd - Issues a general command over the devx interface

SYNOPSIS

              #include <infiniband/mlx5dv.h>

              struct mlx5dv_devx_obj *
              mlx5dv_devx_obj_create(struct ibv_context *context, const void *in, size_t inlen,
                             void *out, size_t outlen);
              int mlx5dv_devx_obj_query(struct mlx5dv_devx_obj *obj, const void *in, size_t inlen,
                            void *out, size_t outlen);
              int mlx5dv_devx_obj_query_async(struct mlx5dv_devx_obj *obj, const void *in,
                              size_t inlen, size_t outlen,
                              uint64_t wr_id,
                              struct mlx5dv_devx_cmd_comp *cmd_comp);
              int mlx5dv_devx_obj_modify(struct mlx5dv_devx_obj *obj, const void *in, size_t inlen,
                             void *out, size_t outlen);
              int mlx5dv_devx_obj_destroy(struct mlx5dv_devx_obj *obj);
              int mlx5dv_devx_general_cmd(struct ibv_context *context, const void *in, size_t inlen,
                              void *out, size_t outlen);

DESCRIPTION

       Create  /  destroy  /  modify / query a devx object, issue a general command over the devx
       interface.

       The DEVX API enables direct access from the user space area to the mlx5 device  driver  by
       using  the  KABI  mechanism.   The  main  purpose  is  to  make  the  user space driver as
       independent as possible from the kernel so that future device functionality  and  commands
       can be activated with minimal to none kernel changes.

       A  DEVX object represents some underlay firmware object, the input command to create it is
       some raw data given by the user application which should match the  device  specification.
       Upon successful creation the output buffer includes the raw data from the device according
       to its specification, this data can be used as part of related firmware commands  to  this
       object.

       Once  the  DEVX  object  is  created  it can be queried/modified/destroyed by the matching
       mlx5dv_devx_obj_xxx() API.  Both the input and the output for those APIs need to match the
       device specification as well.

       The  mlx5dv_devx_general_cmd()  API  enables  issuing  some  general  command which is not
       related to an object such as query device capabilities.

       The mlx5dv_devx_obj_query_async() API is similar to the query object API, however, it runs
       asynchronously without blocking.  The input includes an mlx5dv_devx_cmd_comp object and an
       identifier named `wr_id' for this command.  The response should be read upon success  with
       the  mlx5dv_devx_get_async_cmd_comp()  API.   The `wr_id' that was supplied as an input is
       returned as part of the response to let application knows for which command  the  response
       is related to.

       An  application can gradually migrate to use DEVX according to its needs, it is not all or
       nothing.  For example it can create an ibv_cq via ibv_create_cq() verb and  then  use  the
       returned  cqn  to  create a DEVX QP object by the mlx5dv_devx_obj_create() API which needs
       that cqn.

       The above example can enable an application to create  a  QP  with  some  driver  specific
       attributes that are not exposed in the ibv_create_qp() API, in that case no user or kernel
       change may be needed at all as the command input reaches directly to the firmware.

       The expected users for the DEVX APIs are application that use the mlx5  DV  APIs  and  are
       familiar with the device specification in both control and data path.

       To  successfully create a DEVX object and work on, a DEVX context must be created, this is
       done by the mlx5dv_open_device() API with the MLX5DV_CONTEXT_FLAGS_DEVX flag.

ARGUMENTS

       context
              RDMA device context to create the action on.

       in     A buffer which contains the command’s input data provided in a device specification
              format.

       inlen  The size of in buffer in bytes.

       out    A  buffer  which  contains  the  command’s  output  data  according  to  the device
              specification format.

       outlen The size of out buffer in bytes.

       obj    For query, modify, destroy: the devx object to work on.

       wr_id  The command identifier when working in asynchronous mode.

       cmd_comp
              The command completion object to read the response from in asynchronous mode.

RETURN VALUE

       Upon success mlx5dv_devx_create_obj will return a new struct mlx5dv_devx_obj on error NULL
       will be returned and errno will be set.

       Upon success query, modify, destroy, general commands, 0 is returned or the value of errno
       on a failure.

       If the error value is  EREMOTEIO,  outbox.status  and  outbox.syndrome  will  contain  the
       command failure details.

SEE ALSO

       mlx5dv_open_device, mlx5dv_devx_create_cmd_comp, mlx5dv_devx_get_async_cmd_comp

       #AUTHOR

       Yishai Hadas <yishaih@mellanox.com>

                                    mlx5dv_devx_obj_create / destroy / modify /query / general(3)