Request Trackers

struct nvme_rq

Request tracker

Definition:

struct nvme_rq {
    void *opaque;
};

Members

opaque

Opaque data pointer

void nvme_rq_reset(struct nvme_rq *rq)

Reset a request tracker for reuse

Parameters

struct nvme_rq *rq

struct nvme_rq

Description

Reset internal state of a request tracker.

void nvme_rq_release(struct nvme_rq *rq)

Release a request tracker

Parameters

struct nvme_rq *rq

struct nvme_rq

Description

Release the request tracker and push it on the request tracker free stack.

void nvme_rq_release_atomic(struct nvme_rq *rq)

Release a request tracker atomically

Parameters

struct nvme_rq *rq

struct nvme_rq

Description

Lock-free (compare-and-swap) version of nvme_rq_release().

struct nvme_rq *nvme_rq_acquire(struct nvme_sq *sq)

Acquire a request tracker

Parameters

struct nvme_sq *sq

Submission queue (struct nvme_sq)

Description

Acquire a request tracker from the free stack.

Note

The nvme_cmd.cid union member is initialized by this function, do not clear it subsequent to this call.

Return

A struct nvme_rq or NULL if none are available.

struct nvme_rq *nvme_rq_acquire_atomic(struct nvme_sq *sq)

Acquire a request tracker atomically

Parameters

struct nvme_sq *sq

Submission queue (struct nvme_sq)

Description

Lock-free (compare-and-swap) version of nvme_rq_acquire().

Return

A struct nvme_rq or NULL if none are available.

struct nvme_rq *__nvme_rq_from_cqe(struct nvme_sq *sq, struct nvme_cqe *cqe)

Get the request tracker associated with completion queue entry

Parameters

struct nvme_sq *sq

Submission queue (struct nvme_sq)

struct nvme_cqe *cqe

Completion queue entry (struct nvme_cqe)

Description

Get the request tracker associated with the completion queue entry cqe.

Note

Only safe when used with CQE’s resulting from commands already associated with a request tracker (see nvme_rq_acquire()).

Return

The associated request tracker (see struct nvme_rq).

struct nvme_rq *nvme_rq_from_cqe(struct nvme_ctrl *ctrl, struct nvme_cqe *cqe)

Get the request tracker associated with completion queue entry

Parameters

struct nvme_ctrl *ctrl

See struct nvme_ctrl

struct nvme_cqe *cqe

Completion queue entry (struct nvme_cqe)

Description

Get the request tracker associated with the completion queue entry cqe.

Note

Only safe when used with CQE’s resulting from commands already associated with a request tracker (see nvme_rq_acquire()).

Return

The associated request tracker (see struct nvme_rq).

void nvme_rq_prep_cmd(struct nvme_rq *rq, union nvme_cmd *cmd)

Associate the request tracker with the given command

Parameters

struct nvme_rq *rq

Request tracker (struct nvme_rq)

union nvme_cmd *cmd

NVMe command prototype (union nvme_cmd)

Description

Prepare cmd and associate it with rq (by setting the command identifier).

void nvme_rq_exec(struct nvme_rq *rq, union nvme_cmd *cmd)

Execute the NVMe command on the submission queue associated with the given request tracker

Parameters

struct nvme_rq *rq

Request tracker (struct nvme_rq)

union nvme_cmd *cmd

NVMe command prototype (union nvme_cmd)

Description

Prepare cmd, post it to a submission queue and ring the doorbell.

int nvme_rq_map_prp(struct nvme_ctrl *ctrl, struct nvme_rq *rq, union nvme_cmd *cmd, uint64_t iova, size_t len)

Set up the Physical Region Pages in the data pointer of the command from a buffer that is contiguous in iova mapped memory.

Parameters

struct nvme_ctrl *ctrl

struct nvme_ctrl

struct nvme_rq *rq

Request tracker (struct nvme_rq)

union nvme_cmd *cmd

NVMe command prototype (union nvme_cmd)

uint64_t iova

I/O Virtual Address

size_t len

Length of buffer

Description

Map a buffer of size len into the command payload.

Return

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

int nvme_rq_mapv_prp(struct nvme_ctrl *ctrl, struct nvme_rq *rq, union nvme_cmd *cmd, struct iovec *iov, int niov)

Set up the Physical Region Pages in the data pointer of the command from an iovec.

Parameters

struct nvme_ctrl *ctrl

struct nvme_ctrl

struct nvme_rq *rq

Request tracker (struct nvme_rq)

union nvme_cmd *cmd

NVMe command prototype (union nvme_cmd)

struct iovec *iov

array of iovecs

int niov

number of iovec in iovec

Description

Map the memory contained in iov into the request PRPs. The first entry is allowed to be unaligned, but the entry MUST end on a page boundary. All subsequent entries MUST be page aligned.

Return

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

int nvme_rq_mapv_sgl(struct nvme_ctrl *ctrl, struct nvme_rq *rq, union nvme_cmd *cmd, struct iovec *iov, int niov)

Set up a Scatter/Gather List in the data pointer of the command from an iovec.

Parameters

struct nvme_ctrl *ctrl

struct nvme_ctrl

struct nvme_rq *rq

Request tracker (struct nvme_rq)

union nvme_cmd *cmd

NVMe command prototype (union nvme_cmd)

struct iovec *iov

array of iovecs

int niov

number of iovec in iovec

Description

Map the memory contained in iov into the request SGL.

Return

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

int nvme_rq_mapv(struct nvme_ctrl *ctrl, struct nvme_rq *rq, union nvme_cmd *cmd, struct iovec *iov, int niov)

Set up data pointer in the command from an iovec.

Parameters

struct nvme_ctrl *ctrl

struct nvme_ctrl

struct nvme_rq *rq

Request tracker (struct nvme_rq)

union nvme_cmd *cmd

NVMe command prototype (union nvme_cmd)

struct iovec *iov

array of iovecs

int niov

number of iovec in iovec

Description

Map the memory contained in iov into the request SGL (if supported) or PRPs.

Return

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

int nvme_rq_spin(struct nvme_rq *rq, struct nvme_cqe *cqe_copy)

Spin for completion of the command associated with the request tracker

Parameters

struct nvme_rq *rq

Request tracker (struct nvme_rq)

struct nvme_cqe *cqe_copy

Output parameter to copy completion queue entry into

Description

Spin on the completion queue associated with rq until a completion queue entry is available and copy it into cqe_copy (if not NULL). If the completed command identifer is different from the one associated with rq, set errno to EAGAIN and return -1.

Return

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

int nvme_rq_wait(struct nvme_rq *rq, struct nvme_cqe *cqe_copy, struct timespec *ts)

Wait for completion of the command associated with the request tracker

Parameters

struct nvme_rq *rq

Request tracker (struct nvme_rq)

struct nvme_cqe *cqe_copy

Output parameter to copy completion queue entry into

struct timespec *ts

Maximum time to wait for completion

Description

Like nvme_rq_spin(), but do not spin for more than ts.

Return

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