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 ::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);