# mlx5dv_devx_obj_create

## 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.
    


* * *