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 xnvme_znd_report::_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 xnvme_znd_report::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.

Return

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

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

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’.

Return

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.

Parameters

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’.

Return

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.

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

xnvme_znd_dev_get_ctrlr

const struct xnvme_spec_znd_idfy_ctrlr* xnvme_znd_dev_get_ctrlr(struct xnvme_dev * dev)

Return

Parameters
  • dev:

xnvme_znd_dev_get_lbafe

const struct xnvme_spec_znd_idfy_lbafe* xnvme_znd_dev_get_lbafe(struct xnvme_dev * dev)

Return

Parameters
  • dev:

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

Return

Parameters
  • dev:

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

Return

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

Parameters

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

Return

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

Parameters

xnvme_znd_mgmt_send

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

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

Return

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

Parameters
  • ctx: Pointer to command context (xnvme_cmd_ctx)

  • nsid: Namespace Identifier

  • zslba: Start LBA of the Zone to manage

  • action: Management action to perform with zone at zslba

  • sf: the xnvme_spec_znd_cmd_mgmt_recv_action_sf option

  • dbuf: For action=ZND_SEND_DESCRIPTOR provide buffer

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’.

Return

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

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

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.

Return

On success, the number of characters printed is returned.

Parameters
  • stream: output stream used for printing

  • report: pointer to the the xnvme_znd_report to print

  • flags:

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()

Return

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

Parameters
  • dev: Device handle obtained with xnvme_dev_open() / xnvme_dev_openf()

  • 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.

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.

Return

On success, the number of characters printed is returned.

Parameters
  • report:

  • flags:

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.

Return

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

Parameters