Page MenuHomeFreeBSD

libnvmf: Add internal library to support NVMe over Fabrics

Authored by jhb on Apr 9 2024, 11:03 PM.
Referenced Files
Tue, Jun 18, 6:29 PM
F86315687: D44710.id137178.diff
Tue, Jun 18, 4:15 PM
F86305436: D44710.diff
Tue, Jun 18, 12:04 PM
Unknown Object (File)
Sat, Jun 1, 7:43 PM
Unknown Object (File)
Mon, May 27, 2:11 AM
Unknown Object (File)
May 19 2024, 5:59 AM
Unknown Object (File)
May 3 2024, 5:54 AM
Unknown Object (File)
Apr 26 2024, 4:57 AM



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

Sponsored by: Chelsio Communications

Diff Detail

rG FreeBSD src repository
Lint Not Applicable
Tests Not Applicable

Event Timeline

jhb requested review of this revision.Apr 9 2024, 11:03 PM

This seems fine, but is definitely too large for me to review in detail.


seems odd to have a union of 1

This revision is now accepted and ready to land.Apr 13 2024, 6:09 PM

I realize it's rather large, and I don't really expect super detailed review as it takes quite a bit of context to page NVMeoF in.


In the future if a RDMA transport is added, this will instead look like:

struct nvmf_qpair_admin_params {
      bool admin;
      union {
           struct {
               int fd;
           } tcp;
           struct {
           } rdma;

It is true that if RDMA lands that will be some ABI changes, so probably the shlib_major will get bumped if that happens, and the ioctl structures might also get a new size and need some shims to support the old size, but I've tried to design the various APIs and layers to make it mostly seamless to add RDMA as a transport.

Move nvmf_transport_type to libnvmf

This revision now requires review to proceed.Apr 16 2024, 8:45 PM



Switch to SPDX-only license blocks for C files

This revision was not accepted when it landed; it landed in state Needs Review.May 3 2024, 12:16 AM
This revision was automatically updated to reflect the committed changes.