nvme_zns.h File Reference

NVMe driver public API extension for Zoned Namespace Command Set. More...

Functions

const struct spdk_nvme_zns_ns_dataspdk_nvme_zns_ns_get_data (struct spdk_nvme_ns *ns)
 Get the Zoned Namespace Command Set Specific Identify Namespace data as defined by the NVMe Zoned Namespace Command Set Specification. More...
 
uint64_t spdk_nvme_zns_ns_get_zone_size_sectors (struct spdk_nvme_ns *ns)
 Get the zone size, in number of sectors, of the given namespace. More...
 
uint64_t spdk_nvme_zns_ns_get_zone_size (struct spdk_nvme_ns *ns)
 Get the zone size, in bytes, of the given namespace. More...
 
uint64_t spdk_nvme_zns_ns_get_num_zones (struct spdk_nvme_ns *ns)
 Get the number of zones for the given namespace. More...
 
uint32_t spdk_nvme_zns_ns_get_max_open_zones (struct spdk_nvme_ns *ns)
 Get the maximum number of open zones for the given namespace. More...
 
uint32_t spdk_nvme_zns_ns_get_max_active_zones (struct spdk_nvme_ns *ns)
 Get the maximum number of active zones for the given namespace. More...
 
const struct spdk_nvme_zns_ctrlr_dataspdk_nvme_zns_ctrlr_get_data (struct spdk_nvme_ctrlr *ctrlr)
 Get the Zoned Namespace Command Set Specific Identify Controller data as defined by the NVMe Zoned Namespace Command Set Specification. More...
 
uint32_t spdk_nvme_zns_ctrlr_get_max_zone_append_size (const struct spdk_nvme_ctrlr *ctrlr)
 Get the maximum zone append data transfer size of a given NVMe controller. More...
 
int spdk_nvme_zns_zone_append (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, void *buffer, uint64_t zslba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags)
 Submit a zone append I/O to the specified NVMe namespace. More...
 
int spdk_nvme_zns_zone_append_with_md (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, void *buffer, void *metadata, uint64_t zslba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags, uint16_t apptag_mask, uint16_t apptag)
 Submit a zone append I/O to the specified NVMe namespace. More...
 
int spdk_nvme_zns_zone_appendv (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, uint64_t zslba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags, spdk_nvme_req_reset_sgl_cb reset_sgl_fn, spdk_nvme_req_next_sge_cb next_sge_fn)
 Submit a zone append I/O to the specified NVMe namespace. More...
 
int spdk_nvme_zns_zone_appendv_with_md (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, uint64_t zslba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags, spdk_nvme_req_reset_sgl_cb reset_sgl_fn, spdk_nvme_req_next_sge_cb next_sge_fn, void *metadata, uint16_t apptag_mask, uint16_t apptag)
 Submit a zone append I/O to the specified NVMe namespace. More...
 
int spdk_nvme_zns_close_zone (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, uint64_t slba, bool select_all, spdk_nvme_cmd_cb cb_fn, void *cb_arg)
 Submit a Close Zone operation to the specified NVMe namespace. More...
 
int spdk_nvme_zns_finish_zone (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, uint64_t slba, bool select_all, spdk_nvme_cmd_cb cb_fn, void *cb_arg)
 Submit a Finish Zone operation to the specified NVMe namespace. More...
 
int spdk_nvme_zns_open_zone (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, uint64_t slba, bool select_all, spdk_nvme_cmd_cb cb_fn, void *cb_arg)
 Submit a Open Zone operation to the specified NVMe namespace. More...
 
int spdk_nvme_zns_reset_zone (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, uint64_t slba, bool select_all, spdk_nvme_cmd_cb cb_fn, void *cb_arg)
 Submit a Reset Zone operation to the specified NVMe namespace. More...
 
int spdk_nvme_zns_offline_zone (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, uint64_t slba, bool select_all, spdk_nvme_cmd_cb cb_fn, void *cb_arg)
 Submit a Offline Zone operation to the specified NVMe namespace. More...
 
int spdk_nvme_zns_set_zone_desc_ext (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, uint64_t slba, void *buffer, uint32_t payload_size, spdk_nvme_cmd_cb cb_fn, void *cb_arg)
 Submit a Set Zone Descriptor Extension operation to the specified NVMe namespace. More...
 
int spdk_nvme_zns_report_zones (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, void *payload, uint32_t payload_size, uint64_t slba, enum spdk_nvme_zns_zra_report_opts report_opts, bool partial_report, spdk_nvme_cmd_cb cb_fn, void *cb_arg)
 Get a zone report from the specified NVMe namespace. More...
 
int spdk_nvme_zns_ext_report_zones (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, void *payload, uint32_t payload_size, uint64_t slba, enum spdk_nvme_zns_zra_report_opts report_opts, bool partial_report, spdk_nvme_cmd_cb cb_fn, void *cb_arg)
 Get a extended zone report from the specified NVMe namespace. More...
 

Detailed Description

NVMe driver public API extension for Zoned Namespace Command Set.

Function Documentation

◆ spdk_nvme_zns_close_zone()

int spdk_nvme_zns_close_zone ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
uint64_t  slba,
bool  select_all,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg 
)

Submit a Close Zone operation to the specified NVMe namespace.

Parameters
nsNamespace.
qpairI/O queue pair to submit the request.
slbastarting LBA of the zone to operate on.
select_allIf this is set, slba will be ignored, and operation will be performed on all zones that are in ZSIO or ZSEO state.
cb_fnCallback function invoked when the I/O command completes.
cb_argArgument passed to callback function.
Returns
0 on success. Negated errno on failure.

◆ spdk_nvme_zns_ctrlr_get_data()

const struct spdk_nvme_zns_ctrlr_data* spdk_nvme_zns_ctrlr_get_data ( struct spdk_nvme_ctrlr *  ctrlr)

Get the Zoned Namespace Command Set Specific Identify Controller data as defined by the NVMe Zoned Namespace Command Set Specification.

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

Parameters
ctrlrOpaque handle to NVMe controller.
Returns
pointer to the controller data, or NULL if the controller does not support the Zoned Command Set.

◆ spdk_nvme_zns_ctrlr_get_max_zone_append_size()

uint32_t spdk_nvme_zns_ctrlr_get_max_zone_append_size ( const struct spdk_nvme_ctrlr *  ctrlr)

Get the maximum zone append data transfer size of a given NVMe controller.

Parameters
ctrlrOpaque handle to NVMe controller.
Returns
Maximum zone append data transfer size of the NVMe controller in bytes.

◆ spdk_nvme_zns_ext_report_zones()

int spdk_nvme_zns_ext_report_zones ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
void *  payload,
uint32_t  payload_size,
uint64_t  slba,
enum spdk_nvme_zns_zra_report_opts  report_opts,
bool  partial_report,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg 
)

Get a extended zone report from the specified NVMe namespace.

Parameters
nsNamespace.
qpairI/O queue pair to submit the request.
payloadThe pointer to the payload buffer.
payload_sizeThe size of payload buffer.
slbastarting LBA of the zone to operate on.
report_optsFilter on which zone states to include in the extended zone report.
partial_reportIf true, nr_zones field in the extended zone report indicates the number of zone descriptors that were successfully written to the extended zone report. If false, nr_zones field in the extended zone report indicates the number of zone descriptors that match the report_opts criteria.
cb_fnCallback function invoked when the I/O command completes.
cb_argArgument passed to callback function.
Returns
0 on success. Negated errno on failure.

◆ spdk_nvme_zns_finish_zone()

int spdk_nvme_zns_finish_zone ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
uint64_t  slba,
bool  select_all,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg 
)

Submit a Finish Zone operation to the specified NVMe namespace.

Parameters
nsNamespace.
qpairI/O queue pair to submit the request.
slbastarting LBA of the zone to operate on.
select_allIf this is set, slba will be ignored, and operation will be performed on all zones that are in ZSIO, ZSEO, or ZSC state.
cb_fnCallback function invoked when the I/O command completes.
cb_argArgument passed to callback function.
Returns
0 on success. Negated errno on failure.

◆ spdk_nvme_zns_ns_get_data()

const struct spdk_nvme_zns_ns_data* spdk_nvme_zns_ns_get_data ( struct spdk_nvme_ns *  ns)

Get the Zoned Namespace Command Set Specific Identify Namespace data as defined by the NVMe Zoned Namespace Command Set Specification.

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

Parameters
nsNamespace.
Returns
a pointer to the namespace data, or NULL if the namespace is not a Zoned Namespace.

◆ spdk_nvme_zns_ns_get_max_active_zones()

uint32_t spdk_nvme_zns_ns_get_max_active_zones ( struct spdk_nvme_ns *  ns)

Get the maximum number of active zones for the given namespace.

An active zone is a zone in any of the zone states: EXPLICIT OPEN, IMPLICIT OPEN or CLOSED.

If this value is 0, there is no limit.

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

Parameters
nsNamespace to query.
Returns
the maximum number of active zones.

◆ spdk_nvme_zns_ns_get_max_open_zones()

uint32_t spdk_nvme_zns_ns_get_max_open_zones ( struct spdk_nvme_ns *  ns)

Get the maximum number of open zones for the given namespace.

An open zone is a zone in any of the zone states: EXPLICIT OPEN or IMPLICIT OPEN.

If this value is 0, there is no limit.

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

Parameters
nsNamespace to query.
Returns
the maximum number of open zones.

◆ spdk_nvme_zns_ns_get_num_zones()

uint64_t spdk_nvme_zns_ns_get_num_zones ( struct spdk_nvme_ns *  ns)

Get the number of zones for the given namespace.

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

Parameters
nsNamespace to query.
Returns
the number of zones.

◆ spdk_nvme_zns_ns_get_zone_size()

uint64_t spdk_nvme_zns_ns_get_zone_size ( struct spdk_nvme_ns *  ns)

Get the zone size, in bytes, of the given namespace.

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

Parameters
nsNamespace to query.
Returns
the zone size of the given namespace in bytes.

◆ spdk_nvme_zns_ns_get_zone_size_sectors()

uint64_t spdk_nvme_zns_ns_get_zone_size_sectors ( struct spdk_nvme_ns *  ns)

Get the zone size, in number of sectors, of the given namespace.

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

Parameters
nsNamespace to query.
Returns
the zone size of the given namespace in number of sectors.

◆ spdk_nvme_zns_offline_zone()

int spdk_nvme_zns_offline_zone ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
uint64_t  slba,
bool  select_all,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg 
)

Submit a Offline Zone operation to the specified NVMe namespace.

Parameters
nsNamespace.
qpairI/O queue pair to submit the request.
slbastarting LBA of the zone to operate on.
select_allIf this is set, slba will be ignored, and operation will be performed on all zones that are in ZSRO state.
cb_fnCallback function invoked when the I/O command completes.
cb_argArgument passed to callback function.
Returns
0 on success. Negated errno on failure.

◆ spdk_nvme_zns_open_zone()

int spdk_nvme_zns_open_zone ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
uint64_t  slba,
bool  select_all,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg 
)

Submit a Open Zone operation to the specified NVMe namespace.

Parameters
nsNamespace.
qpairI/O queue pair to submit the request.
slbastarting LBA of the zone to operate on.
select_allIf this is set, slba will be ignored, and operation will be performed on all zones that are in ZSC state.
cb_fnCallback function invoked when the I/O command completes.
cb_argArgument passed to callback function.
Returns
0 on success. Negated errno on failure.

◆ spdk_nvme_zns_report_zones()

int spdk_nvme_zns_report_zones ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
void *  payload,
uint32_t  payload_size,
uint64_t  slba,
enum spdk_nvme_zns_zra_report_opts  report_opts,
bool  partial_report,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg 
)

Get a zone report from the specified NVMe namespace.

Parameters
nsNamespace.
qpairI/O queue pair to submit the request.
payloadThe pointer to the payload buffer.
payload_sizeThe size of payload buffer.
slbastarting LBA of the zone to operate on.
report_optsFilter on which zone states to include in the zone report.
partial_reportIf true, nr_zones field in the zone report indicates the number of zone descriptors that were successfully written to the zone report. If false, nr_zones field in the zone report indicates the number of zone descriptors that match the report_opts criteria.
cb_fnCallback function invoked when the I/O command completes.
cb_argArgument passed to callback function.
Returns
0 on success. Negated errno on failure.

◆ spdk_nvme_zns_reset_zone()

int spdk_nvme_zns_reset_zone ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
uint64_t  slba,
bool  select_all,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg 
)

Submit a Reset Zone operation to the specified NVMe namespace.

Parameters
nsNamespace.
qpairI/O queue pair to submit the request.
slbastarting LBA of the zone to operate on.
select_allIf this is set, slba will be ignored, and operation will be performed on all zones that are in ZSIO, ZSEO, ZSC, or ZSF state.
cb_fnCallback function invoked when the I/O command completes.
cb_argArgument passed to callback function.
Returns
0 on success. Negated errno on failure.

◆ spdk_nvme_zns_set_zone_desc_ext()

int spdk_nvme_zns_set_zone_desc_ext ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
uint64_t  slba,
void *  buffer,
uint32_t  payload_size,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg 
)

Submit a Set Zone Descriptor Extension operation to the specified NVMe namespace.

Parameters
nsNamespace.
qpairI/O queue pair to submit the request.
slbastarting LBA of the zone to operate on.
bufferVirtual address pointer to the data payload buffer.
payload_sizePayload buffer size.
cb_fnCallback function invoked when the I/O command completes.
cb_argArgument passed to callback function.
Returns
0 on success. Negated errno on failure.

◆ spdk_nvme_zns_zone_append()

int spdk_nvme_zns_zone_append ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
void *  buffer,
uint64_t  zslba,
uint32_t  lba_count,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg,
uint32_t  io_flags 
)

Submit a zone append I/O to the specified NVMe namespace.

The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). The user must ensure that only one thread submits I/O on a given qpair at any given time.

Parameters
nsNVMe namespace to submit the zone append I/O.
qpairI/O queue pair to submit the request.
bufferVirtual address pointer to the data payload buffer.
zslbaZone Start LBA of the zone that we are appending to.
lba_countLength (in sectors) for the zone append operation.
cb_fnCallback function to invoke when the I/O is completed.
cb_argArgument to pass to the callback function.
io_flagsSet flags, defined by the SPDK_NVME_IO_FLAGS_* entries in spdk/nvme_spec.h, for this I/O.
Returns
0 if successfully submitted, negated errnos on the following error conditions: -EINVAL: The request is malformed. -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level.

◆ spdk_nvme_zns_zone_append_with_md()

int spdk_nvme_zns_zone_append_with_md ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
void *  buffer,
void *  metadata,
uint64_t  zslba,
uint32_t  lba_count,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg,
uint32_t  io_flags,
uint16_t  apptag_mask,
uint16_t  apptag 
)

Submit a zone append I/O to the specified NVMe namespace.

The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). The user must ensure that only one thread submits I/O on a given qpair at any given time.

Parameters
nsNVMe namespace to submit the zone append I/O.
qpairI/O queue pair to submit the request.
bufferVirtual address pointer to the data payload buffer.
metadataVirtual address pointer to the metadata payload, the length of metadata is specified by spdk_nvme_ns_get_md_size().
zslbaZone Start LBA of the zone that we are appending to.
lba_countLength (in sectors) for the zone append operation.
cb_fnCallback function to invoke when the I/O is completed.
cb_argArgument to pass to the callback function.
io_flagsSet flags, defined by the SPDK_NVME_IO_FLAGS_* entries in spdk/nvme_spec.h, for this I/O.
apptag_maskApplication tag mask.
apptagApplication tag to use end-to-end protection information.
Returns
0 if successfully submitted, negated errnos on the following error conditions: -EINVAL: The request is malformed. -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level.

◆ spdk_nvme_zns_zone_appendv()

int spdk_nvme_zns_zone_appendv ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
uint64_t  zslba,
uint32_t  lba_count,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg,
uint32_t  io_flags,
spdk_nvme_req_reset_sgl_cb  reset_sgl_fn,
spdk_nvme_req_next_sge_cb  next_sge_fn 
)

Submit a zone append I/O to the specified NVMe namespace.

The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). The user must ensure that only one thread submits I/O on a given qpair at any given time.

Parameters
nsNVMe namespace to submit the zone append I/O.
qpairI/O queue pair to submit the request.
zslbaZone Start LBA of the zone that we are appending to.
lba_countLength (in sectors) for the zone append operation.
cb_fnCallback function to invoke when the I/O is completed.
cb_argArgument to pass to the callback function.
io_flagsSet flags, defined in nvme_spec.h, for this I/O.
reset_sgl_fnCallback function to reset scattered payload.
next_sge_fnCallback function to iterate each scattered payload memory segment.
Returns
0 if successfully submitted, negated errnos on the following error conditions: -EINVAL: The request is malformed. -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level.

◆ spdk_nvme_zns_zone_appendv_with_md()

int spdk_nvme_zns_zone_appendv_with_md ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
uint64_t  zslba,
uint32_t  lba_count,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg,
uint32_t  io_flags,
spdk_nvme_req_reset_sgl_cb  reset_sgl_fn,
spdk_nvme_req_next_sge_cb  next_sge_fn,
void *  metadata,
uint16_t  apptag_mask,
uint16_t  apptag 
)

Submit a zone append I/O to the specified NVMe namespace.

The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). The user must ensure that only one thread submits I/O on a given qpair at any given time.

Parameters
nsNVMe namespace to submit the zone append I/O.
qpairI/O queue pair to submit the request.
zslbaZone Start LBA of the zone that we are appending to.
lba_countLength (in sectors) for the zone append operation.
cb_fnCallback function to invoke when the I/O is completed.
cb_argArgument to pass to the callback function.
io_flagsSet flags, defined in nvme_spec.h, for this I/O.
reset_sgl_fnCallback function to reset scattered payload.
next_sge_fnCallback function to iterate each scattered payload memory segment.
metadataVirtual address pointer to the metadata payload, the length of metadata is specified by spdk_nvme_ns_get_md_size().
apptag_maskApplication tag mask.
apptagApplication tag to use end-to-end protection information.
Returns
0 if successfully submitted, negated errnos on the following error conditions: -EINVAL: The request is malformed. -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level.