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 : 3131965 : xnvme_cmd_ctx_cpl_status(struct xnvme_cmd_ctx *ctx) 89 : : { 90 [ + - - + ]: 3131965 : 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);