1/*-
2 * SPDX-License-Identifier: BSD-2-Clause
3 *
4 * Copyright (c) 2022-2024 Chelsio Communications, Inc.
5 * Written by: John Baldwin <jhb@FreeBSD.org>
6 */
7
8#ifndef __NVMF_TRANSPORT_H__
9#define	__NVMF_TRANSPORT_H__
10
11/*
12 * Interface used by the Fabrics host (initiator) and controller
13 * (target) to send and receive capsules and associated data.
14 */
15
16#include <sys/sysctl.h>
17#include <dev/nvmf/nvmf_proto.h>
18
19struct mbuf;
20struct memdesc;
21struct nvmf_capsule;
22struct nvmf_connection;
23struct nvmf_qpair;
24struct nvmf_handoff_qpair_params;
25
26SYSCTL_DECL(_kern_nvmf);
27
28/*
29 * Callback to invoke when an error occurs on a qpair.  The last
30 * parameter is an error value.  If the error value is zero, the qpair
31 * has been closed at the transport level rather than a transport
32 * error occuring.
33 */
34typedef void nvmf_qpair_error_t(void *, int);
35
36/* Callback to invoke when a capsule is received. */
37typedef void nvmf_capsule_receive_t(void *, struct nvmf_capsule *);
38
39/*
40 * Callback to invoke when an I/O request has completed.  The second
41 * parameter is the amount of data transferred.  The last parameter is
42 * an error value which is non-zero if the request did not complete
43 * successfully.  A request with an error may complete partially.
44 */
45typedef void nvmf_io_complete_t(void *, size_t, int);
46
47/*
48 * A queue pair represents either an Admin or I/O
49 * submission/completion queue pair.  The params contains negotiated
50 * values passed in from userland.
51 *
52 * Unlike libnvmf in userland, the kernel transport interface does not
53 * have any notion of an association.  Instead, qpairs are
54 * independent.
55 */
56struct nvmf_qpair *nvmf_allocate_qpair(enum nvmf_trtype trtype,
57    bool controller, const struct nvmf_handoff_qpair_params *params,
58    nvmf_qpair_error_t *error_cb, void *error_cb_arg,
59    nvmf_capsule_receive_t *receive_cb, void *receive_cb_arg);
60void	nvmf_free_qpair(struct nvmf_qpair *qp);
61
62/*
63 * Capsules are either commands (host -> controller) or responses
64 * (controller -> host).  A data buffer may be associated with a
65 * command capsule.  Transmitted data is not copied by this API but
66 * instead must be preserved until the completion callback is invoked
67 * to indicate capsule transmission has completed.
68 */
69struct nvmf_capsule *nvmf_allocate_command(struct nvmf_qpair *qp,
70    const void *sqe, int how);
71struct nvmf_capsule *nvmf_allocate_response(struct nvmf_qpair *qp,
72    const void *cqe, int how);
73void	nvmf_free_capsule(struct nvmf_capsule *nc);
74int	nvmf_capsule_append_data(struct nvmf_capsule *nc,
75    struct memdesc *mem, size_t len, bool send,
76    nvmf_io_complete_t *complete_cb, void *cb_arg);
77int	nvmf_transmit_capsule(struct nvmf_capsule *nc);
78void	nvmf_abort_capsule_data(struct nvmf_capsule *nc, int error);
79void *nvmf_capsule_sqe(struct nvmf_capsule *nc);
80void *nvmf_capsule_cqe(struct nvmf_capsule *nc);
81
82/* Controller-specific APIs. */
83
84/*
85 * A controller calls this function to check for any
86 * transport-specific errors (invalid fields) in a received command
87 * capsule.  The callback returns a generic command status value:
88 * NVME_SC_SUCCESS if no error is found.
89 */
90uint8_t	nvmf_validate_command_capsule(struct nvmf_capsule *nc);
91
92/*
93 * A controller calls this function to query the amount of data
94 * associated with a command capsule.
95 */
96size_t	nvmf_capsule_data_len(const struct nvmf_capsule *cc);
97
98/*
99 * A controller calls this function to receive data associated with a
100 * command capsule (e.g. the data for a WRITE command).  This can
101 * either return in-capsule data or fetch data from the host
102 * (e.g. using a R2T PDU over TCP).  The received command capsule
103 * should be passed in 'nc'.  The received data is stored in 'mem'.
104 * If this function returns success, then the callback will be invoked
105 * once the operation has completed.  Note that the callback might be
106 * invoked before this function returns.
107 */
108int	nvmf_receive_controller_data(struct nvmf_capsule *nc,
109    uint32_t data_offset, struct memdesc *mem, size_t len,
110    nvmf_io_complete_t *complete_cb, void *cb_arg);
111
112/*
113 * A controller calls this function to send data in response to a
114 * command prior to sending a response capsule.  If an error occurs,
115 * the function returns a generic status completion code to be sent in
116 * the following CQE.  Note that the transfer might send a subset of
117 * the data requested by nc.  If the transfer succeeds, this function
118 * can return one of the following values:
119 *
120 * - NVME_SC_SUCCESS: The transfer has completed successfully and the
121 *   caller should send a success CQE in a response capsule.
122 *
123 * - NVMF_SUCCESS_SENT: The transfer has completed successfully and
124 *   the transport layer has sent an implicit success CQE to the
125 *   remote host (e.g. the SUCCESS flag for TCP).  The caller should
126 *   not send a response capsule.
127 *
128 * - NVMF_MORE: The transfer has completed successfully, but the
129 *   transfer did not complete the data buffer.
130 *
131 * The mbuf chain in 'm' is consumed by this function even if an error
132 * is returned.
133 */
134u_int	nvmf_send_controller_data(struct nvmf_capsule *nc,
135    uint32_t data_offset, struct mbuf *m, size_t len);
136
137#define	NVMF_SUCCESS_SENT	0x100
138#define	NVMF_MORE		0x101
139
140#endif /* !__NVMF_TRANSPORT_H__ */
141