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 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 extensionPublic 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[]#
-
uint64_t nzones#
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:
dev – Device handle obtained with xnvme_dev_open()
slba – The Zone Start LBA
zdescr – Pointer to the xnvme_spec_znd_descr to fill
- 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:
dev – Device handle obtained with xnvme_dev_open()
- 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
thenret
is filled with completion entry upon return- Parameters:
ctx – Pointer to command context (xnvme_cmd_ctx)
nsid – Namespace Identifier
slba – Start LBA of the Zone to receive for
zra – Zone Receive Action, the xnvme_spec_znd_cmd_mgmt_recv_action
zrasf – the xnvme_spec_znd_cmd_mgmt_recv_action_sf
partial – partial request
dbuf – pointer to data payload
dbuf_nbytes – pointer to meta payload
- 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
- 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 givenslba
, and limited tolimit
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:
dev – The device to stat
sfield – Receive stats of the given xnvme_spec_znd_cmd_mgmt_recv_action_sf
nzones – Pointer to store result in
- 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.