xnvme_znd

Enums

Structs

xnvme_znd_report

struct xnvme_znd_report

Encapsulation of Zone Descriptors and Zone Descriptor Extensions.

This is not the structure from the Specification, rather, this encapsulates it and provides MACRO-accessors and helper-functions to retrieve zone-descriptors and when supported, extensions.

For simplicity then only use the macros below when accessing the report entries:

ZND_REPORT_DESCR(rprt, nth) - Access the ‘nth’ descriptor (zero-based) ZND_REPORT_DEXT(rprt, nth) - Access the ‘nth’ descr. extension (zero-based)

However, when zdes_bytes is 0, then descr is accessible as a regular array When zdes > 0, then the ZND_REPORT_DESCR should be used to access Zone Descriptors and ZND_REPORT_DEXT should be used to access Zone Descriptor extension

Public Members

uint64_t nzones

Nr. of zones in device.

uint32_t zd_nbytes

Zone Descriptor in ‘B’.

uint32_t zdext_nbytes

Zone Descriptor Extension in ‘B’.

uint64_t zslba

First Zone in the report.

uint64_t zelba

Last Zone in the report.

uint32_t nentries

Nr. of entries in report.

uint8_t extended

Whether this report has extensions.

uint8_t _pad[3]
uint64_t zrent_nbytes

Zone Report Entry Size in ‘B’.

uint64_t report_nbytes

Size of this struct in bytes.

uint64_t entries_nbytes

Size of the entries in bytes.

Array of structs, column format: descr[,descr_ext]

uint8_t storage[]

Functions

xnvme_znd_append

int xnvme_znd_append(struct xnvme_cmd_ctx *ctx, uint32_t nsid, uint64_t zslba, uint16_t nlb, const void *dbuf, const void *mbuf)

Submit, and optionally wait for completion of, a Zone Append.

Parameters
  • ctx – Pointer to command context (xnvme_cmd_ctx)

  • nsid – Namespace Identifier

  • zslba – First LBA of the Zone to append to

  • nlb – number of LBAs, this is zero-based value

  • dbuf – pointer to data payload

  • mbuf – pointer to meta payload

Returns

On success, 0 is returned. On error, negative errno is returned.

xnvme_znd_descr_from_dev

int xnvme_znd_descr_from_dev(struct xnvme_dev *dev, uint64_t slba, struct xnvme_spec_znd_descr *zdescr)

Fills ‘zdescr’ with the Zone on the given ‘dev’ that starts at ‘slba’.

Parameters
Returns

On success, 0 is returned and ‘zdescr’ filled with matching Zone Descriptor. On error, negative errno is returned to indicate the error, and the content of given ‘zdescr’ is undefined.

xnvme_znd_descr_from_dev_in_state

int xnvme_znd_descr_from_dev_in_state(struct xnvme_dev *dev, enum xnvme_spec_znd_state state, struct xnvme_spec_znd_descr *zdescr)

Fills ‘zdescr’ with the first Zone on the given ‘dev’ in the given ‘state’.

Parameters
  • dev – The device to receive descriptors from

  • state – The state the Zone should be in

  • zdescr – Pointer to the descriptor the function should fill

Returns

On succes, 0 is returned and ‘zdescr’ filled with matching Zone Descriptor. On error, negative errno is returned to indicate the error, and the content of given ‘zdescr’ is undefined.

xnvme_znd_dev_get_ctrlr

const struct xnvme_spec_znd_idfy_ctrlr *xnvme_znd_dev_get_ctrlr(struct xnvme_dev *dev)

Todo:

Document this

Provide a generic xnvme_dev_get_ctrlr_csi instead of this

Parameters
  • dev

Returns

xnvme_znd_dev_get_lbafe

const struct xnvme_spec_znd_idfy_lbafe *xnvme_znd_dev_get_lbafe(struct xnvme_dev *dev)

Todo:

Document this

Parameters
  • dev

Returns

xnvme_znd_dev_get_ns

const struct xnvme_spec_znd_idfy_ns *xnvme_znd_dev_get_ns(struct xnvme_dev *dev)

The User space library for Zoned Namespaces based on xNVMe, the Cross-platform libraries and tools for NVMe devices.

Copyright (C) Simon A. F. Lund simon.lund@samsung.com SPDX-License-Identifier: Apache-2.0

Todo:

Document this

Provide a generic xnvme_dev_get_ns_csi instead of this

Parameters
  • dev

Returns

xnvme_znd_log_changes_from_dev

struct xnvme_spec_znd_log_changes *xnvme_znd_log_changes_from_dev(struct xnvme_dev *dev)

Returns a list of changes since the last report was retrieved.

Note

Invoking this function clears the changed log

Note

Caller is responsible for de-allocating the returned structure using xnvme_buf_free

Parameters
Returns

On success, pointer to namespace structure. On error, NULL is returned and errno is set to indicate the error

xnvme_znd_mgmt_recv

int xnvme_znd_mgmt_recv(struct xnvme_cmd_ctx *ctx, uint32_t nsid, uint64_t slba, enum xnvme_spec_znd_cmd_mgmt_recv_action action, enum xnvme_spec_znd_cmd_mgmt_recv_action_sf sf, uint8_t partial, void *dbuf, uint32_t dbuf_nbytes)

Submit, and optionally wait for completion of, a Zone Management Receive.

Note

When opts | CMD_MODE_SYNC then ret is filled with completion entry upon return

Parameters
Returns

On success, 0 is returned. On error, negative errno is returned.

xnvme_znd_mgmt_send

int xnvme_znd_mgmt_send(struct xnvme_cmd_ctx *ctx, uint32_t nsid, uint64_t zslba, bool select_all, enum xnvme_spec_znd_cmd_mgmt_send_action action, enum xnvme_spec_znd_mgmt_send_action_sf action_sf, void *dbuf)

Submit, and optionally wait for completion of, a Zone Management Send.

Parameters
  • ctx – Pointer to command context (xnvme_cmd_ctx)

  • nsid – Namespace Identifier

  • zslba – Start LBA of the Zone to manage

  • select_all – Ignore zslba, command affects all LBAs

  • action – Management the xnvme_spec_znd_cmd_mgmt_send_action to perform with zone at zslba or all LBAs when select_all is true

  • action_sf – the xnvme_spec_znd_mgmt_send_action_sf option

  • dbuf – For action=ZND_SEND_DESCRIPTOR provide buffer

Returns

On success, 0 is returned. On error, negative errno is returned.

xnvme_znd_report_find_arbitrary

int xnvme_znd_report_find_arbitrary(const struct xnvme_znd_report *report, enum xnvme_spec_znd_state state, uint64_t *zlba, int opts)

Scan the ‘report’ for a zone in the given ‘state’ and store it in ‘zlba’.

Parameters
  • report – The report to scan

  • state – The zone-state to scan for

  • zlba – Pointer to store zlba to

  • opts – Optional seed random-number generator, when 0 then time(NULL) is used

Returns

On success, 0 is returned. On error, negative errno is returned.

xnvme_znd_report_fpr

int xnvme_znd_report_fpr(FILE *stream, const struct xnvme_znd_report *report, int flags)

Prints the given xnvme_znd_report to the given stream.

Parameters
  • stream – output stream used for printing

  • report – pointer to the the xnvme_znd_report to print

  • flags

Returns

On success, the number of characters printed is returned.

xnvme_znd_report_from_dev

struct xnvme_znd_report *xnvme_znd_report_from_dev(struct xnvme_dev *dev, uint64_t slba, size_t limit, uint8_t extended)

Retrieves a Zone Report from the namespace associated with the given dev, reporting starting at the given slba, and limited to limit entries.

Note

Caller is responsible for de-allocating the returned structure using xnvme_buf_virt_free()

Parameters
  • dev – Device handle obtained with xnvme_dev_open()

  • slba – LBA of the first zone in the report

  • limit – when 0 then provide a report for all zones start from slba. Otherwise, provide a report for [slba, slba+limit]

  • extended – When 0, the “regular” report is provided. When 1, then the Extended Report is provided, if supported by device.

Returns

On success, pointer to zoned report. On error, NULL is returned and errno is set to indicate the error

xnvme_znd_report_pr

int xnvme_znd_report_pr(const struct xnvme_znd_report *report, int flags)

Prints the given xnvme_znd_report to stdout.

Parameters
  • report

  • flags

Returns

On success, the number of characters printed is returned.

xnvme_znd_stat

int xnvme_znd_stat(struct xnvme_dev *dev, enum xnvme_spec_znd_cmd_mgmt_recv_action_sf sfield, uint64_t *nzones)

Ask the given device for how many zones in the given state via receive-action.

Parameters
Returns

On Success, 0 is returned and ‘nzones’ filled with stat. On error, negative errno is returned to indicate the error.