Line data    Source code

       1             : /**
       2             :  * SPDX-FileCopyrightText: Samsung Electronics Co., Ltd
       3             :  *
       4             :  * SPDX-License-Identifier: BSD-3-Clause
       5             :  *
       6             :  * @headerfile libxnvme_adm.h
       7             :  */
       8             : 
       9             : /**
      10             :  * Attributes for asynchronous command-contexts
      11             :  *
      12             :  * @struct xnvme_cmd_ctx_async
      13             :  */
      14             : struct xnvme_cmd_ctx_async {
      15             :         struct xnvme_queue *queue; ///< Queue used for command processing
      16             :         xnvme_queue_cb cb;         ///< User defined callback function
      17             :         void *cb_arg;              ///< User defined callback function arguments
      18             : };
      19             : 
      20             : /**
      21             :  * The xNVMe Command Context
      22             :  *
      23             :  * @struct xnvme_cmd_ctx
      24             :  */
      25             : struct xnvme_cmd_ctx {
      26             :         struct xnvme_spec_cmd cmd;        ///< Command to be processed
      27             :         struct xnvme_spec_cpl cpl;        ///< Completion result from processing
      28             :         struct xnvme_dev *dev;            ///< Device associated with the command
      29             :         struct xnvme_cmd_ctx_async async; ///< Fields for command option: XNVME_CMD_ASYNC
      30             :         ///< Field containing command-options, the field is initialized by helper-functions
      31             :         uint32_t opts;
      32             : 
      33             :         uint8_t be_rsvd[12]; ///< Fields reserved for use by library internals
      34             : };
      35             : XNVME_STATIC_ASSERT(sizeof(struct xnvme_cmd_ctx) == 128, "Incorrect size")
      36             : 
      37             : /**
      38             :  * Assign a callback-function and argument to be used with the given command-context
      39             :  *
      40             :  * @param ctx Pointer to the ::xnvme_cmd_ctx to setup callback for
      41             :  * @param cb The callback function to use
      42             :  * @param cb_arg The callback argument to use
      43             :  */
      44             : static inline void
      45             : xnvme_cmd_ctx_set_cb(struct xnvme_cmd_ctx *ctx, xnvme_queue_cb cb, void *cb_arg)
      46             : {
      47             :         ctx->async.cb     = cb;
      48             :         ctx->async.cb_arg = cb_arg;
      49             : }
      50             : 
      51             : /**
      52             :  * Retrieve a command-context for issuing commands to the given device
      53             :  *
      54             :  * @param dev Device handle (::xnvme_dev) obtained with xnvme_dev_open()
      55             :  *
      56             :  * @return A ::xnvme_cmd_ctx initialized synchronous command on the given device
      57             :  */
      58             : struct xnvme_cmd_ctx
      59             : xnvme_cmd_ctx_from_dev(struct xnvme_dev *dev);
      60             : 
      61             : /**
      62             :  * Retrieve a command-text for issuing commands via the given queue
      63             :  *
      64             :  * @param queue Pointer to the ::xnvme_queue to retrieve a command-context for
      65             :  *
      66             :  * @return On success, a pointer to a ::xnvme_cmd_ctx is returned. On error, NULL is returned and
      67             :  * `errno` set to indicate the error.
      68             :  */
      69             : struct xnvme_cmd_ctx *
      70             : xnvme_cmd_ctx_from_queue(struct xnvme_queue *queue);
      71             : 
      72             : /**
      73             :  * Clears/resets the given ::xnvme_cmd_ctx
      74             :  *
      75             :  * @param ctx Pointer to the ::xnvme_cmd_ctx to clear
      76             :  */
      77             : void
      78             : xnvme_cmd_ctx_clear(struct xnvme_cmd_ctx *ctx);
      79             : 
      80             : /**
      81             :  * Encapsulate completion-error checking here for now.
      82             :  *
      83             :  * @param ctx Pointer to the ::xnvme_cmd_ctx to check status on
      84             :  *
      85             :  * @return On success, 0 is return. On error, a non-zero value is returned.
      86             :  */
      87             : static inline int
      88           0 : xnvme_cmd_ctx_cpl_status(struct xnvme_cmd_ctx *ctx)
      89             : {
      90           0 :         return ctx->cpl.status.sc || ctx->cpl.status.sct;
      91             : }
      92             : 
      93             : /**
      94             :  * Pass an NVMe IO Command through to the device via the given ::xnvme_cmd_ctx
      95             :  *
      96             :  * @param ctx Pointer to command context (::xnvme_cmd_ctx)
      97             :  * @param dbuf pointer to data-payload
      98             :  * @param dbuf_nbytes size of data-payload in bytes
      99             :  * @param mbuf pointer to meta-payload
     100             :  * @param mbuf_nbytes size of the meta-payload in bytes
     101             :  *
     102             :  * @return On success, 0 is returned. On error, negative `errno` is returned.
     103             :  */
     104             : int
     105             : xnvme_cmd_pass(struct xnvme_cmd_ctx *ctx, void *dbuf, size_t dbuf_nbytes, void *mbuf,
     106             :                size_t mbuf_nbytes);
     107             : 
     108             : /**
     109             :  * Pass a vectored NVMe IO Command through to the device via the given
     110             : ::xnvme_cmd_ctx
     111             :  *
     112             :  * NOTE: This function will be deprecated in the future - use xnvme_cmd_pass_iov() instead
     113             :  *
     114             :  * @param ctx Pointer to command context (::xnvme_cmd_ctx)
     115             :  * @param dvec array of data iovecs
     116             :  * @param dvec_cnt number of elements in dvec
     117             :  * @param dvec_nbytes size of the meta-payload in bytes
     118             :  * @param mvec array of metadata iovecs
     119             :  * @param mvec_cnt number of elements in mvec
     120             :  * @param mvec_nbytes size of the meta-payload in bytes
     121             :  *
     122             :  * @return On success, 0 is returned. On error, negative `errno` is returned.
     123             :  */
     124             : int
     125             : xnvme_cmd_passv(struct xnvme_cmd_ctx *ctx, struct iovec *dvec, size_t dvec_cnt, size_t dvec_nbytes,
     126             :                 struct iovec *mvec, size_t mvec_cnt, size_t mvec_nbytes);
     127             : 
     128             : /**
     129             :  * Pass a vectored NVMe IO Command through to the device via the given
     130             :  * ::xnvme_cmd_ctx
     131             :  *
     132             :  * @param ctx Pointer to command context (::xnvme_cmd_ctx)
     133             :  * @param dvec array of data iovecs
     134             :  * @param dvec_cnt number of elements in dvec
     135             :  * @param dvec_nbytes size of the meta-payload in bytes
     136             :  * @param mbuf pointer to meta-payload
     137             :  * @param mbuf_nbytes size of the meta-payload in bytes
     138             :  *
     139             :  * @return On success, 0 is returned. On error, negative `errno` is returned.
     140             :  */
     141             : int
     142             : xnvme_cmd_pass_iov(struct xnvme_cmd_ctx *ctx, struct iovec *dvec, size_t dvec_cnt,
     143             :                    size_t dvec_nbytes, void *mbuf, size_t mbuf_nbytes);
     144             : 
     145             : /**
     146             :  * Pass a NVMe Admin Command through to the device with minimal intervention
     147             :  *
     148             :  * @param ctx Pointer to command context (::xnvme_cmd_ctx)
     149             :  * @param dbuf pointer to data-payload
     150             :  * @param dbuf_nbytes size of data-payload in bytes
     151             :  * @param mbuf pointer to meta-payload
     152             :  * @param mbuf_nbytes size of the meta-payload in bytes
     153             :  *
     154             :  * @return On success, 0 is returned. On error, negative `errno` is returned.
     155             :  */
     156             : int
     157             : xnvme_cmd_pass_admin(struct xnvme_cmd_ctx *ctx, void *dbuf, size_t dbuf_nbytes, void *mbuf,
     158             :                      size_t mbuf_nbytes);