libxnvme_znd.h#

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 getter function when accessing the report entries:

xnvme_znd_report_get_descr(report, index, **descr, **ext)

However, when zdes_bytes is 0, then descr is accessible as a regular array When zdes > 0.

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

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 zra, enum xnvme_spec_znd_cmd_mgmt_recv_action_sf zrasf, 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 zsa, enum xnvme_spec_znd_mgmt_send_action_so zsa_so, 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

  • zsa – Zone Send Action, the xnvme_spec_znd_cmd_mgmt_send_action to perform with zone at zslba or all LBAs when select_all is true

  • zsa_so – the xnvme_spec_znd_mgmt_send_action_so 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 – printer options, see xnvme_pr

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_get_descr#

int xnvme_znd_report_get_descr(const struct xnvme_znd_report *report, uint32_t index, struct xnvme_spec_znd_descr **descr, void **ext)#

Access Zone Descriptors, by entry index, in the given znd_report.

NOTE: the MACRO is kept for backwards compatibility with the upstream fio io-engine.

Parameters:

  • index – Index, 0-based, of the entry in the report

  • report – Pointer to the the xnvme_znd_report to get descriptor from

  • descr – Pointer the descriptor will be assigned to

  • ext – Pointer the extended descriptor will be assigned to

Returns:

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

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.

xnvme_znd_zrwa_flush#

int xnvme_znd_zrwa_flush(struct xnvme_cmd_ctx *ctx, uint32_t nsid, uint64_t lba)#

Submit, and optionally wait for completion of, a Zone RWA Commit.

Parameters:

  • ctx – Pointer to command context (xnvme_cmd_ctx)

  • nsid – Namespace Identifier

  • lba – Commit from ZRWA to Zone up-to and including the given ‘lba’

Returns:

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

On this page