mirror of
https://github.com/freebsd/freebsd-src
synced 2024-10-07 00:50:50 +00:00
aa1207ea4f
nvmf_transport.ko provides routines for managing NVMeoF queue pairs and capsules. It provides a glue layer between transports (such as TCP or RDMA) and an NVMeoF host (initiator) and controller (target). Unlike the synchronous API exposed to the host and controller by libnvmf, the kernel's transport layer uses an asynchronous API built on callbacks. Upper layers provide callbacks on queue pairs that are invoked for transport errors (error_cb) or anytime a capsule is received (receive_cb). Data transfers for a command are usually associated with a callback that is invoked once a transfer has finished either due to an error or successful completion. For an upper layer that is a host, command capsules are allocated and populated with an NVMe SQE by calling nvmf_allocate_command. A data buffer (described by a struct memdesc) can be associated with a command capsule before it is transmitted via nvmf_capsule_append_data. This function accepts a direction (send vs receive) as well as the data transfer callback. The host then transmits the command via nvmf_transmit_capsule. The host must ensure that the data buffer described by the 'struct memdesc' remains valid until the data transfer callback is called. The queue pair's receive_cb callback should match received response capsules up with previously transmitted commands. For the controller, incoming commands are received via the queue pair's receive_cb callback. nvmf_receive_controller_data is used to retrieve any data from a command (e.g. the data for a WRITE command). It can be called multiple times to split the data transfer into smaller sizes. This function accepts an I/O completion callback that is invoked once the data transfer has completed. nvmf_send_controller_data is used to send data to a remote host in response to a command. In this case a callback function is not used but the status is returned synchronously. Finally, the controller can allocate a response capsule via nvmf_allocate_response populated with a supplied CQE and send the response via nvmf_transmit_capsule. Reviewed by: imp Sponsored by: Chelsio Communications Differential Revision: https://reviews.freebsd.org/D44711
141 lines
5.1 KiB
C
141 lines
5.1 KiB
C
/*-
|
|
* SPDX-License-Identifier: BSD-2-Clause
|
|
*
|
|
* Copyright (c) 2022-2024 Chelsio Communications, Inc.
|
|
* Written by: John Baldwin <jhb@FreeBSD.org>
|
|
*/
|
|
|
|
#ifndef __NVMF_TRANSPORT_H__
|
|
#define __NVMF_TRANSPORT_H__
|
|
|
|
/*
|
|
* Interface used by the Fabrics host (initiator) and controller
|
|
* (target) to send and receive capsules and associated data.
|
|
*/
|
|
|
|
#include <sys/sysctl.h>
|
|
#include <dev/nvmf/nvmf_proto.h>
|
|
|
|
struct mbuf;
|
|
struct memdesc;
|
|
struct nvmf_capsule;
|
|
struct nvmf_connection;
|
|
struct nvmf_qpair;
|
|
struct nvmf_handoff_qpair_params;
|
|
|
|
SYSCTL_DECL(_kern_nvmf);
|
|
|
|
/*
|
|
* Callback to invoke when an error occurs on a qpair. The last
|
|
* parameter is an error value. If the error value is zero, the qpair
|
|
* has been closed at the transport level rather than a transport
|
|
* error occuring.
|
|
*/
|
|
typedef void nvmf_qpair_error_t(void *, int);
|
|
|
|
/* Callback to invoke when a capsule is received. */
|
|
typedef void nvmf_capsule_receive_t(void *, struct nvmf_capsule *);
|
|
|
|
/*
|
|
* Callback to invoke when an I/O request has completed. The second
|
|
* parameter is the amount of data transferred. The last parameter is
|
|
* an error value which is non-zero if the request did not complete
|
|
* successfully. A request with an error may complete partially.
|
|
*/
|
|
typedef void nvmf_io_complete_t(void *, size_t, int);
|
|
|
|
/*
|
|
* A queue pair represents either an Admin or I/O
|
|
* submission/completion queue pair. The params contains negotiated
|
|
* values passed in from userland.
|
|
*
|
|
* Unlike libnvmf in userland, the kernel transport interface does not
|
|
* have any notion of an association. Instead, qpairs are
|
|
* independent.
|
|
*/
|
|
struct nvmf_qpair *nvmf_allocate_qpair(enum nvmf_trtype trtype,
|
|
bool controller, const struct nvmf_handoff_qpair_params *params,
|
|
nvmf_qpair_error_t *error_cb, void *error_cb_arg,
|
|
nvmf_capsule_receive_t *receive_cb, void *receive_cb_arg);
|
|
void nvmf_free_qpair(struct nvmf_qpair *qp);
|
|
|
|
/*
|
|
* Capsules are either commands (host -> controller) or responses
|
|
* (controller -> host). A data buffer may be associated with a
|
|
* command capsule. Transmitted data is not copied by this API but
|
|
* instead must be preserved until the completion callback is invoked
|
|
* to indicate capsule transmission has completed.
|
|
*/
|
|
struct nvmf_capsule *nvmf_allocate_command(struct nvmf_qpair *qp,
|
|
const void *sqe, int how);
|
|
struct nvmf_capsule *nvmf_allocate_response(struct nvmf_qpair *qp,
|
|
const void *cqe, int how);
|
|
void nvmf_free_capsule(struct nvmf_capsule *nc);
|
|
int nvmf_capsule_append_data(struct nvmf_capsule *nc,
|
|
struct memdesc *mem, size_t len, bool send,
|
|
nvmf_io_complete_t *complete_cb, void *cb_arg);
|
|
int nvmf_transmit_capsule(struct nvmf_capsule *nc);
|
|
void nvmf_abort_capsule_data(struct nvmf_capsule *nc, int error);
|
|
void *nvmf_capsule_sqe(struct nvmf_capsule *nc);
|
|
void *nvmf_capsule_cqe(struct nvmf_capsule *nc);
|
|
|
|
/* Controller-specific APIs. */
|
|
|
|
/*
|
|
* A controller calls this function to check for any
|
|
* transport-specific errors (invalid fields) in a received command
|
|
* capsule. The callback returns a generic command status value:
|
|
* NVME_SC_SUCCESS if no error is found.
|
|
*/
|
|
uint8_t nvmf_validate_command_capsule(struct nvmf_capsule *nc);
|
|
|
|
/*
|
|
* A controller calls this function to query the amount of data
|
|
* associated with a command capsule.
|
|
*/
|
|
size_t nvmf_capsule_data_len(const struct nvmf_capsule *cc);
|
|
|
|
/*
|
|
* A controller calls this function to receive data associated with a
|
|
* command capsule (e.g. the data for a WRITE command). This can
|
|
* either return in-capsule data or fetch data from the host
|
|
* (e.g. using a R2T PDU over TCP). The received command capsule
|
|
* should be passed in 'nc'. The received data is stored in 'mem'.
|
|
* If this function returns success, then the callback will be invoked
|
|
* once the operation has completed. Note that the callback might be
|
|
* invoked before this function returns.
|
|
*/
|
|
int nvmf_receive_controller_data(struct nvmf_capsule *nc,
|
|
uint32_t data_offset, struct memdesc *mem, size_t len,
|
|
nvmf_io_complete_t *complete_cb, void *cb_arg);
|
|
|
|
/*
|
|
* A controller calls this function to send data in response to a
|
|
* command prior to sending a response capsule. If an error occurs,
|
|
* the function returns a generic status completion code to be sent in
|
|
* the following CQE. Note that the transfer might send a subset of
|
|
* the data requested by nc. If the transfer succeeds, this function
|
|
* can return one of the following values:
|
|
*
|
|
* - NVME_SC_SUCCESS: The transfer has completed successfully and the
|
|
* caller should send a success CQE in a response capsule.
|
|
*
|
|
* - NVMF_SUCCESS_SENT: The transfer has completed successfully and
|
|
* the transport layer has sent an implicit success CQE to the
|
|
* remote host (e.g. the SUCCESS flag for TCP). The caller should
|
|
* not send a response capsule.
|
|
*
|
|
* - NVMF_MORE: The transfer has completed successfully, but the
|
|
* transfer did not complete the data buffer.
|
|
*
|
|
* The mbuf chain in 'm' is consumed by this function even if an error
|
|
* is returned.
|
|
*/
|
|
u_int nvmf_send_controller_data(struct nvmf_capsule *nc,
|
|
uint32_t data_offset, struct mbuf *m, size_t len);
|
|
|
|
#define NVMF_SUCCESS_SENT 0x100
|
|
#define NVMF_MORE 0x101
|
|
|
|
#endif /* !__NVMF_TRANSPORT_H__ */
|