mirror of
https://github.com/freebsd/freebsd-src
synced 2024-07-09 04:36:31 +00:00
2da066ef6d
libnvmf provides APIs for transmitting and receiving Command and Response capsules along with data associated with NVMe commands. Capsules are represented by 'struct nvmf_capsule' objects. Capsules are transmitted and received on queue pairs represented by 'struct nvmf_qpair' objects. Queue pairs belong to an association represented by a 'struct nvmf_association' object. libnvmf provides additional helper APIs to assist with constructing command capsules for a host, response capsules for a controller, connecting queue pairs to a remote controller and optionally offloading connected queues to an in-kernel host, accepting queue pair connections from remote hosts and optionally offloading connected queues to an in-kernel controller, constructing controller data structures for local controllers, etc. libnvmf also includes an internal transport abstraction as well as an implementation of a userspace TCP transport. libnvmf is primarily intended for ease of use and low-traffic use cases such as establishing connections that are handed off to the kernel. As such, it uses a simple API built on blocking I/O. For a host, a consumer first populates an 'struct nvmf_association_params' with a set of parameters shared by all queue pairs for a single association such as whether or not to use SQ flow control and header and data digests and creates a 'struct nvmf_association' object. The consumer is responsible for establishing a TCP socket for each queue pair. This socket is included in the 'struct nvmf_qpair_params' passed to 'nvmf_connect' to complete transport-specific negotiation, send a Fabrics Connect command, and wait for the Connect reply. Upon success, a new 'struct nvmf_qpair' object is returned. This queue pair can then be used to send and receive capsules. A command capsule is allocated, populated with an SQE and optional data buffer, and transmitted via nvmf_host_transmit_command. The consumer can then wait for a reply via nvmf_host_wait_for_response. The library also provides some wrapper functions such as nvmf_read_property and nvmf_write_property which send a command and wait for a response synchronously. For a controller, a consumer uses a single association for a set of incoming connections. A consumer can choose to use multiple associations (e.g. a separate association for connections to a discovery controller listening on a different port than I/O controllers). The consumer is responsible for accepting TCP sockets directly, but once a socket has been accepted it is passed to nvmf_accept to perform transport-specific negotiation and wait for the Connect command. Similar to nvmf_connect, nvmf_accept returns a newly construct nvmf_qpair. However, in contrast to nvmf_connect, nvmf_accept does not complete the Fabrics negotiation. The consumer must explicitly send a response capsule before waiting for additional command capsules to arrive. In particular, in the kernel offload case, the Connect command and data are provided to the kernel controller and the Connect response capsule is sent by the kernel once it is ready to handle the new queue pair. For userspace controller command handling, the consumer uses nvmf_controller_receive_capsule to wait for a command capsule. 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. nvmf_send_controller_data is used to send data to a remote host in response to a command. It also sends a response capsule indicating success, or an error if an internal error occurs. nvmf_send_response is used to send a response without associated data. There are also several convenience wrappers such as nvmf_send_success and nvmf_send_generic_error. Reviewed by: imp Sponsored by: Chelsio Communications Differential Revision: https://reviews.freebsd.org/D44710
117 lines
3.0 KiB
C
117 lines
3.0 KiB
C
/*-
|
|
* SPDX-License-Identifier: BSD-2-Clause
|
|
*
|
|
* Copyright (c) 2022-2024 Chelsio Communications, Inc.
|
|
* Written by: John Baldwin <jhb@FreeBSD.org>
|
|
*/
|
|
|
|
#ifndef __LIBNVMF_INTERNAL_H__
|
|
#define __LIBNVMF_INTERNAL_H__
|
|
|
|
#include <sys/queue.h>
|
|
|
|
struct nvmf_transport_ops {
|
|
/* Association management. */
|
|
struct nvmf_association *(*allocate_association)(bool controller,
|
|
const struct nvmf_association_params *params);
|
|
void (*update_association)(struct nvmf_association *na,
|
|
const struct nvme_controller_data *cdata);
|
|
void (*free_association)(struct nvmf_association *na);
|
|
|
|
/* Queue pair management. */
|
|
struct nvmf_qpair *(*allocate_qpair)(struct nvmf_association *na,
|
|
const struct nvmf_qpair_params *params);
|
|
void (*free_qpair)(struct nvmf_qpair *qp);
|
|
|
|
/* Create params for kernel handoff. */
|
|
int (*kernel_handoff_params)(struct nvmf_qpair *qp,
|
|
struct nvmf_handoff_qpair_params *qparams);
|
|
|
|
/* Capsule operations. */
|
|
struct nvmf_capsule *(*allocate_capsule)(struct nvmf_qpair *qp);
|
|
void (*free_capsule)(struct nvmf_capsule *nc);
|
|
int (*transmit_capsule)(struct nvmf_capsule *nc);
|
|
int (*receive_capsule)(struct nvmf_qpair *qp,
|
|
struct nvmf_capsule **ncp);
|
|
uint8_t (*validate_command_capsule)(const struct nvmf_capsule *nc);
|
|
|
|
/* Transferring controller data. */
|
|
size_t (*capsule_data_len)(const struct nvmf_capsule *nc);
|
|
int (*receive_controller_data)(const struct nvmf_capsule *nc,
|
|
uint32_t data_offset, void *buf, size_t len);
|
|
int (*send_controller_data)(const struct nvmf_capsule *nc,
|
|
const void *buf, size_t len);
|
|
};
|
|
|
|
struct nvmf_association {
|
|
struct nvmf_transport_ops *na_ops;
|
|
enum nvmf_trtype na_trtype;
|
|
bool na_controller;
|
|
|
|
struct nvmf_association_params na_params;
|
|
|
|
/* Each qpair holds a reference on an association. */
|
|
u_int na_refs;
|
|
|
|
char *na_last_error;
|
|
};
|
|
|
|
struct nvmf_qpair {
|
|
struct nvmf_association *nq_association;
|
|
bool nq_admin;
|
|
|
|
uint16_t nq_cid; /* host only */
|
|
|
|
/*
|
|
* Queue sizes. This assumes the same size for both the
|
|
* completion and submission queues within a pair.
|
|
*/
|
|
u_int nq_qsize;
|
|
|
|
/* Flow control management for submission queues. */
|
|
bool nq_flow_control;
|
|
uint16_t nq_sqhd;
|
|
uint16_t nq_sqtail; /* host only */
|
|
|
|
/* Value in response to/from CONNECT. */
|
|
uint16_t nq_cntlid;
|
|
|
|
uint32_t nq_kato; /* valid on admin queue only */
|
|
|
|
TAILQ_HEAD(, nvmf_capsule) nq_rx_capsules;
|
|
};
|
|
|
|
struct nvmf_capsule {
|
|
struct nvmf_qpair *nc_qpair;
|
|
|
|
/* Either a SQE or CQE. */
|
|
union {
|
|
struct nvme_command nc_sqe;
|
|
struct nvme_completion nc_cqe;
|
|
};
|
|
int nc_qe_len;
|
|
|
|
/*
|
|
* Is SQHD in received capsule valid? False for locally-
|
|
* synthesized responses.
|
|
*/
|
|
bool nc_sqhd_valid;
|
|
|
|
/* Data buffer. */
|
|
bool nc_send_data;
|
|
void *nc_data;
|
|
size_t nc_data_len;
|
|
|
|
TAILQ_ENTRY(nvmf_capsule) nc_link;
|
|
};
|
|
|
|
extern struct nvmf_transport_ops tcp_ops;
|
|
|
|
void na_clear_error(struct nvmf_association *na);
|
|
void na_error(struct nvmf_association *na, const char *fmt, ...);
|
|
|
|
int nvmf_kernel_handoff_params(struct nvmf_qpair *qp,
|
|
struct nvmf_handoff_qpair_params *qparams);
|
|
|
|
#endif /* !__LIBNVMF_INTERNAL_H__ */
|