LCOV - code coverage report
Current view: top level - spdk/xnvme/include - libxnvme_cmd.h (source / functions) Hit Total Coverage
Test: Combined Lines: 2 2 100.0 %
Date: 2024-07-15 18:04:22 Functions: 1 1 100.0 %
Legend: Lines: hit not hit | Branches: + taken - not taken # not executed Branches: 2 4 50.0 %

           Branch data     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                 :    3296996 : xnvme_cmd_ctx_cpl_status(struct xnvme_cmd_ctx *ctx)
      89                 :            : {
      90   [ +  -  -  + ]:    3296996 :         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 ::xnvme_cmd_ctx
     110                 :            :  *
     111                 :            :  * @param ctx Pointer to command context (::xnvme_cmd_ctx)
     112                 :            :  * @param dvec array of data iovecs
     113                 :            :  * @param dvec_cnt number of elements in dvec
     114                 :            :  * @param dvec_nbytes size of the meta-payload in bytes
     115                 :            :  * @param mvec array of metadata iovecs
     116                 :            :  * @param mvec_cnt number of elements in mvec
     117                 :            :  * @param mvec_nbytes size of the meta-payload in bytes
     118                 :            :  *
     119                 :            :  * @return On success, 0 is returned. On error, negative `errno` is returned.
     120                 :            :  */
     121                 :            : int
     122                 :            : xnvme_cmd_passv(struct xnvme_cmd_ctx *ctx, struct iovec *dvec, size_t dvec_cnt, size_t dvec_nbytes,
     123                 :            :                 struct iovec *mvec, size_t mvec_cnt, size_t mvec_nbytes);
     124                 :            : 
     125                 :            : /**
     126                 :            :  * Pass a NVMe Admin Command through to the device with minimal intervention
     127                 :            :  *
     128                 :            :  * @param ctx Pointer to command context (::xnvme_cmd_ctx)
     129                 :            :  * @param dbuf pointer to data-payload
     130                 :            :  * @param dbuf_nbytes size of data-payload in bytes
     131                 :            :  * @param mbuf pointer to meta-payload
     132                 :            :  * @param mbuf_nbytes size of the meta-payload in bytes
     133                 :            :  *
     134                 :            :  * @return On success, 0 is returned. On error, negative `errno` is returned.
     135                 :            :  */
     136                 :            : int
     137                 :            : xnvme_cmd_pass_admin(struct xnvme_cmd_ctx *ctx, void *dbuf, size_t dbuf_nbytes, void *mbuf,
     138                 :            :                      size_t mbuf_nbytes);

Generated by: LCOV version 1.14