libxnvme_driver.h#
Enums#
xnvme_driver_flag#
-
enum xnvme_driver_flag#
Flags for xnvme_driver_attach() and xnvme_driver_detach().
Values:
-
enumerator XNVME_DRIVER_FORCE#
Attach a function whose namespaces carry a signature.
-
enumerator XNVME_DRIVER_DRY_RUN#
Run the checks, change nothing.
-
enumerator XNVME_DRIVER_FORCE#
Structs#
xnvme_driver_result#
-
struct xnvme_driver_result#
The outcome of an attach or detach of one function.
Public Members
-
int err#
0 when done, or a negative errno; see xnvme_driver_attach()
-
char why[508]#
Why it was refused or failed, empty when done.
-
int err#
Functions#
xnvme_driver_attach#
-
int xnvme_driver_attach(const char *const *bdfs, int nbdfs, const char *driver, int flags, struct xnvme_driver_result *results)#
Move each of the functions in ‘bdfs’ off the kernel NVMe driver and onto ‘driver’.
The functions are attached as one set: one sharing an IOMMU group with another in the set is not refused for it. Each function gets an entry in ‘results’, with ‘err’ set to 0 when it was attached, or for a dry run would be, and otherwise to:
-ENODEV, not an NVMe controller function; -EALREADY, already on ‘driver’; -EISCONN, on another userspace driver; -EBUSY, held; -EACCES, open files could not be checked; -EEXIST, a namespace carries a filesystem, partition table or volume signature, which XNVME_DRIVER_FORCE overrides; -EXDEV, its IOMMU group has a member that cannot go along; -ENOENT, ‘driver’ is not available; -ECANCELED, left where it was as a member of its IOMMU group failed to bind; or the errno of the binding.
- Parameters:
bdfs – PCI addresses of the functions
nbdfs – Number of entries in ‘bdfs’ and ‘results’
driver – The userspace driver, or NULL for xnvme_driver_default()
flags – Bitwise OR of xnvme_driver_flag
results – Array of ‘nbdfs’ entries to fill
- Returns:
On success, the number of functions refused or failed, not counting -EALREADY. On error, negative
errnois returned, -ENOSYS where the platform does not implement it.
xnvme_driver_default#
-
const char *xnvme_driver_default(void)#
The userspace driver xnvme_driver_attach() binds when given none.
- Returns:
The driver name, or NULL where the platform has none
xnvme_driver_detach#
-
int xnvme_driver_detach(const char *const *bdfs, int nbdfs, const char *driver, int flags, struct xnvme_driver_result *results)#
Return each of the functions in ‘bdfs’ from a userspace driver to ‘driver’.
Each function gets an entry in ‘results’, with ‘err’ set to 0 when it was detached, or for a dry run would be, and otherwise to -ENODEV, not an NVMe controller function; -EALREADY, not on a userspace driver; -EBUSY, held; -EACCES, open files could not be checked; or the errno of the binding.
- Parameters:
bdfs – PCI addresses of the functions
nbdfs – Number of entries in ‘bdfs’ and ‘results’
driver – The kernel driver to return them to, or NULL for the platform’s NVMe driver
flags – Bitwise OR of xnvme_driver_flag
results – Array of ‘nbdfs’ entries to fill
- Returns:
On success, the number of functions refused or failed, not counting -EALREADY. On error, negative
errnois returned, -ENOSYS where the platform does not implement it.
xnvme_driver_for_be#
-
const char *xnvme_driver_for_be(const char *be)#
The driver an NVMe controller function must be on for the backend ‘be’ to use it.
A backend that drives the function itself, such as spdk, libvfn or upcie, needs a userspace driver: vfio-pci for libvfn, else xnvme_driver_default(). Every other backend reaches the device through the kernel, and needs the platform’s NVMe driver. ‘be’ is a backend config’s name, as xnvme_be_attr lists it, or the platform’s own name for its kernel backends.
- Parameters:
be – Name of a backend config, or of the platform
- Returns:
The driver name. NULL with errno set to ENOENT when ‘be’ names no backend of the platform, to EINVAL when the backend uses no PCIe function, such as ramdisk or a file, and to ENOSYS where the platform does not move functions between drivers.
Header#
/**
* SPDX-FileCopyrightText: Samsung Electronics Co., Ltd
*
* SPDX-License-Identifier: BSD-3-Clause
*
* @file libxnvme_driver.h
*
* Moving an NVMe controller function between the kernel NVMe driver and a userspace one. The
* functions and their drivers are found with xnvme_scan(); a dry run of an attach or a detach
* says what holds each. How a function is moved is the platform's: Linux binds vfio-pci or
* uio_pci_generic through sysfs, FreeBSD nic_uio. On other platforms every function returns
* -ENOSYS.
*/
/**
* Flags for xnvme_driver_attach() and xnvme_driver_detach()
*
* @enum xnvme_driver_flag
*/
enum xnvme_driver_flag {
XNVME_DRIVER_FORCE = 0x1, ///< Attach a function whose namespaces carry a signature
XNVME_DRIVER_DRY_RUN = 0x2, ///< Run the checks, change nothing
};
/**
* The outcome of an attach or detach of one function
*
* @struct xnvme_driver_result
*/
struct xnvme_driver_result {
int err; ///< 0 when done, or a negative errno; see xnvme_driver_attach()
char why[508]; ///< Why it was refused or failed, empty when done
};
XNVME_STATIC_ASSERT(sizeof(struct xnvme_driver_result) == 512, "Incorrect size")
/**
* The userspace driver xnvme_driver_attach() binds when given none
*
* @return The driver name, or NULL where the platform has none
*/
const char *
xnvme_driver_default(void);
/**
* The driver an NVMe controller function must be on for the backend 'be' to use it
*
* A backend that drives the function itself, such as spdk, libvfn or upcie, needs a userspace
* driver: vfio-pci for libvfn, else xnvme_driver_default(). Every other backend reaches the
* device through the kernel, and needs the platform's NVMe driver. 'be' is a backend config's
* name, as xnvme_be_attr lists it, or the platform's own name for its kernel backends.
*
* @param be Name of a backend config, or of the platform
*
* @return The driver name. NULL with errno set to ENOENT when 'be' names no backend of the
* platform, to EINVAL when the backend uses no PCIe function, such as ramdisk or a file, and to
* ENOSYS where the platform does not move functions between drivers.
*/
const char *
xnvme_driver_for_be(const char *be);
/**
* Move each of the functions in 'bdfs' off the kernel NVMe driver and onto 'driver'
*
* The functions are attached as one set: one sharing an IOMMU group with another in the set is
* not refused for it. Each function gets an entry in 'results', with 'err' set to 0 when it was
* attached, or for a dry run would be, and otherwise to:
*
* -ENODEV, not an NVMe controller function; -EALREADY, already on 'driver'; -EISCONN, on another
* userspace driver; -EBUSY, held; -EACCES, open files could not be checked; -EEXIST, a namespace
* carries a filesystem, partition table or volume signature, which XNVME_DRIVER_FORCE overrides;
* -EXDEV, its IOMMU group has a member that cannot go along; -ENOENT, 'driver' is not available;
* -ECANCELED, left where it was as a member of its IOMMU group failed to bind; or the errno of
* the binding.
*
* @param bdfs PCI addresses of the functions
* @param nbdfs Number of entries in 'bdfs' and 'results'
* @param driver The userspace driver, or NULL for xnvme_driver_default()
* @param flags Bitwise OR of #xnvme_driver_flag
* @param results Array of 'nbdfs' entries to fill
*
* @return On success, the number of functions refused or failed, not counting -EALREADY. On error,
* negative `errno` is returned, -ENOSYS where the platform does not implement it.
*/
int
xnvme_driver_attach(const char *const *bdfs, int nbdfs, const char *driver, int flags,
struct xnvme_driver_result *results);
/**
* Return each of the functions in 'bdfs' from a userspace driver to 'driver'
*
* Each function gets an entry in 'results', with 'err' set to 0 when it was detached, or for a
* dry run would be, and otherwise to -ENODEV, not an NVMe controller function; -EALREADY, not on
* a userspace driver; -EBUSY, held; -EACCES, open files could not be checked; or the errno of the
* binding.
*
* @param bdfs PCI addresses of the functions
* @param nbdfs Number of entries in 'bdfs' and 'results'
* @param driver The kernel driver to return them to, or NULL for the platform's NVMe driver
* @param flags Bitwise OR of #xnvme_driver_flag
* @param results Array of 'nbdfs' entries to fill
*
* @return On success, the number of functions refused or failed, not counting -EALREADY. On error,
* negative `errno` is returned, -ENOSYS where the platform does not implement it.
*/
int
xnvme_driver_detach(const char *const *bdfs, int nbdfs, const char *driver, int flags,
struct xnvme_driver_result *results);