Controller Configuration

struct nvme_ctrl_opts: NVMe controller options

Definition:

struct nvme_ctrl_opts {
    int nsqr, ncqr;
#define NVME_QUIRK_BROKEN_DBBUF (1 << 0);
    unsigned int quirks;
};

Members

nsqr: number of submission queues to request
ncqr: number of completion queues to request
quirks: quirks to apply

Note

nsqr and ncqr are zeroes based values.

struct nvme_ctrl: NVMe Controller

Definition:

struct nvme_ctrl {
    struct vfio_pci_device pci;
    void *regs;
    struct nvme_sq *sq;
    struct nvme_cq *cq;
    struct {
        struct nvme_sq *sq;
        struct nvme_cq *cq;
    } adminq;
    void *doorbells;
    struct {
        void *doorbells;
        void *eventidxs;
    } dbbuf;
    struct nvme_ctrl_opts opts;
    struct {
        int nsqa, ncqa;
        int mqes;
        int mps;
    } config;
    unsigned long flags;
};

Members

pci

vfio pci device state

regs

Controller Configuration (MBAR.CC) registers

sq

submission queues

cq

completion queues

adminq

Admin queue pair

doorbells

mapped doorbell registers

dbbuf

doorbell buffers

opts

controller options

config

cached run-time controller configuration

flags

controller feature flags

See enum nvme_ctrl_feature_flags.

int nvme_pci_init(struct nvme_ctrl *ctrl, const char *bdf): Initialize PCI instance of nvme controller

Parameters

struct nvme_ctrl *ctrl: Controller whose pci device is to initialize
const char *bdf: PCI device identifier (“bus:device:function”)

Description

Initialize PCI device based on vfio-pci without NVMe controller initialization.

Return

0 on success, -1 on error and sets errno.

int nvme_ctrl_init(struct nvme_ctrl *ctrl, const char *bdf, const struct nvme_ctrl_opts *opts): Initialize NVMe controller instance along with PCI instance

Parameters

struct nvme_ctrl *ctrl: Controller whose pci device is to initialize
const char *bdf: PCI device identifier (“bus:device:function”)
const struct nvme_ctrl_opts *opts: Controller configuration options

Description

Initialize NVMe controller instance configuration values and sq/cq instance array. It won’t create any queue resources, no commands at all.

Return

0 on success, -1 on error and sets errno.

int nvme_init(struct nvme_ctrl *ctrl, const char *bdf, const struct nvme_ctrl_opts *opts): Initialize controller

Parameters

struct nvme_ctrl *ctrl: Controller to initialize
const char *bdf: PCI device identifier (“bus:device:function”)
const struct nvme_ctrl_opts *opts: Controller configuration options

Description

Initialize the controller identified by bdf. The controller is ready for use after a successful call to this.

See struct nvme_ctrl_opts for configurable options.

Return

0 on success, -1 on error and sets errno.

void nvme_close(struct nvme_ctrl *ctrl): Close a controller

Parameters

struct nvme_ctrl *ctrl: Controller to close

Description

Uninitialize the controller, deleting any i/o queues and releasing VFIO resources.

int nvme_reset(struct nvme_ctrl *ctrl): Reset controller

Parameters

struct nvme_ctrl *ctrl: Controller to reset

Description

Reset the controller referenced by ctrl.

Return

See nvme_wait_rdy().

int nvme_configure_adminq(struct nvme_ctrl *ctrl, unsigned long sq_flags): Configure admin sq/cq pair

Parameters

struct nvme_ctrl *ctrl: Controller to setup adminq
unsigned long sq_flags: SQ flags to configure (XXX: yet to implement)

Description

Configure admin sq/cq address and size to controller registers

Return

0 on success, -1 on error and set errno.

int nvme_enable(struct nvme_ctrl *ctrl): Enable controller

Parameters

struct nvme_ctrl *ctrl: Controller to enable

Description

Enable the controller referenced by ctrl.

Return

See nvme_wait_rdy().

int nvme_create_iocq(struct nvme_ctrl *ctrl, int qid, int qsize, int vector): Create an I/O Completion Queue

Parameters

struct nvme_ctrl *ctrl: Controller reference
int qid: Queue identifier
int qsize: Queue size
int vector: interrupt vector

Description

Create an I/O Completion Queue on ctrl with identifier qid and size qsize. Set vector to -1 to disable interrupts. If you associate an interrupt vector, you need to use vfio_set_irq() to associate the vector with an eventfd.

Note that one slot in the queue is reserved for the full queue condition. So, if a queue command depth of N is required, qsize should be N + 1.

Return

On success, returns 0. On error, returns -1 and sets errno.

int nvme_delete_iocq(struct nvme_ctrl *ctrl, int qid): Delete an I/O Completion Queue

Parameters

struct nvme_ctrl *ctrl: See struct nvme_ctrl
int qid: Queue identifier

Description

Delete the I/O Completion queue associated with qid.

Return

On success, returns 0. On error, returns -1 and sets errno.

int nvme_create_iosq(struct nvme_ctrl *ctrl, int qid, int qsize, struct nvme_cq *cq, unsigned long flags): Create an I/O Submission Queue

Parameters

struct nvme_ctrl *ctrl: Controller reference
int qid: Queue identifier
int qsize: Queue size
struct nvme_cq *cq: Associated I/O Completion Queue
unsigned long flags: See enum nvme_create_iosq_flags

Description

Create an I/O Submission Queue on ctrl with identifier qid, queue size qsize and associated with I/O Completion Queue cq. flags may be used to modify the behavior (see enum nvme_create_iosq_flags).

Note that one slot in the queue is reserved for the full queue condition. So, if a queue command depth of N is required, qsize should be N + 1.

Return

On success, returns 0. On error, returns -1 and sets errno.

int nvme_delete_iosq(struct nvme_ctrl *ctrl, int qid): Delete an I/O Submission Queue

Parameters

struct nvme_ctrl *ctrl: See struct nvme_ctrl
int qid: Queue identifier

Description

Delete the I/O Submission queue associated with qid.

Return

On success, returns 0. On error, returns -1 and sets errno.

int nvme_create_ioqpair(struct nvme_ctrl *ctrl, int qid, int qsize, int vector, unsigned long flags): Create an I/O Completion/Submission Queue Pair

Parameters

struct nvme_ctrl *ctrl: Controller reference
int qid: Queue identifier
int qsize: Queue size
int vector: Completion queue interrupt vector
unsigned long flags: See enum nvme_create_iosq_flags

Description

Create both an I/O Submission Queue and an I/O Completion Queue with the same queue identifier, queue size. flags may be used to modify the behavior of the submission queu (see enum nvme_create_iosq_flags).

Note that one slot in the queue is reserved for the full queue condition. So, if a queue command depth of N is required, qsize should be N + 1.

Return

On success, returns 0. On error, returns -1 and sets errno.

int nvme_delete_ioqpair(struct nvme_ctrl *ctrl, int qid): Delete an I/O Completion/Submission Queue Pair

Parameters

struct nvme_ctrl *ctrl: See struct nvme_ctrl
int qid: Queue identifier

Description

Delete both the I/O Submission and Completion queues associated with qid.

Return

On success, returns 0. On error, returns -1 and sets errno.

void nvme_discard_cq(struct nvme_ctrl *ctrl, struct nvme_cq *cq): Free resources related to the corresponding CQ

Parameters

struct nvme_ctrl *ctrl: See struct nvme_ctrl
struct nvme_cq *cq: Associated I/O Completion Queue

void nvme_discard_sq(struct nvme_ctrl *ctrl, struct nvme_sq *sq): Free resources related to the corresponding SQ

Parameters

struct nvme_ctrl *ctrl: See struct nvme_ctrl
struct nvme_sq *sq: Associated I/O Submission Queue