xnvme_nvm¶

Header¶

/*
 * The User space library for Non-Volatile Memory NVMe 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
 *
 * @headerfile libxnvme_nvm.h
 */
#ifndef __LIBXNVME_NVM_H
#define __LIBXNVME_NVM_H

#ifdef __cplusplus
extern "C" {
#endif

#include <libxnvme.h>

/**
 * Submit, and optionally wait for completion of, a NVMe Read
 *
 * @param ctx Pointer to command context (::xnvme_cmd_ctx)
 * @param nsid Namespace Identifier
 * @param slba The LBA to start reading from
 * @param nlb The number of LBAs to read. NOTE: nlb is a zero-based value
 * @param dbuf Pointer to data-payload
 * @param mbuf Pointer to meta-payload
 *
 * @return On success, 0 is returned. On error, negative `errno` is returned.
 */
int
xnvme_nvm_read(struct xnvme_cmd_ctx *ctx, uint32_t nsid, uint64_t slba, uint16_t nlb, void *dbuf,
	       void *mbuf);

/**
 * Submit, and optionally wait for completion of, a NVMe Write
 *
 * @param ctx Pointer to command context (::xnvme_cmd_ctx)
 * @param nsid Namespace Identifier
 * @param slba The LBA to start the write at
 * @param nlb Number of LBAs to be written. NOTE: nlb is a zero-based value
 * @param dbuf Pointer to buffer; Payload as indicated by 'ctx->opts'
 * @param mbuf Pointer to buffer; Payload as indicated by 'ctx->opts'
 *
 * @return On success, 0 is returned. On error, negative `errno` is returned.
 */
int
xnvme_nvm_write(struct xnvme_cmd_ctx *ctx, uint32_t nsid, uint64_t slba, uint16_t nlb,
		const void *dbuf, const void *mbuf);

/**
 * Submit a write uncorrected command
 *
 * @param ctx Pointer to command context (::xnvme_cmd_ctx)
 * @param nsid Namespace Identifier
 * @param slba The Starting Destination LBA
 * @param nlb Number Of Logical Blocks
 */
int
xnvme_nvm_write_uncorrectable(struct xnvme_cmd_ctx *ctx, uint32_t nsid, uint64_t slba,
			      uint16_t nlb);

/**
 * Submit a write zeroes command
 *
 * @see xnvme_cmd_opts
 *
 * @param ctx Pointer to command context (::xnvme_cmd_ctx)
 * @param nsid Namespace Identifier
 * @param sdlba The Starting Destination LBA to start copying to
 * @param nlb Number Of Logical Blocks
 *
 * @return On success, 0 is returned. On error, -1 is returned, `errno` set to
 * indicate and param ctx.cpl filled with lower-level status codes
 */
int
xnvme_nvm_write_zeroes(struct xnvme_cmd_ctx *ctx, uint32_t nsid, uint64_t sdlba, uint16_t nlb);

/**
 * Submit, and optionally wait for completion of, a NVMe Write
 *
 * @param ctx Pointer to command context (::xnvme_cmd_ctx)
 * @param opcode Opcode for the NVMe command
 * @param nsid Namespace Identifier
 * @param slba The LBA to start the write at
 * @param nlb Number of LBAs to be written. NOTE: nlb is a zero-based value
 *
 * @return On success, 0 is returned. On error, negative `errno` is returned.
 */
void
xnvme_prep_nvm(struct xnvme_cmd_ctx *ctx, uint8_t opcode, uint32_t nsid, uint64_t slba,
	       uint16_t nlb);

/**
 * Submit, and optionally wait for completion of a NVMe Simple-Copy-Command
 *
 * @see xnvme_cmd_opts
 *
 * @param ctx Pointer to command context (::xnvme_cmd_ctx)
 * @param nsid Namespace Identifier
 * @param sdlba The Starting Destination LBA to start copying to
 * @param ranges Pointer to ranges-buffer, see ::xnvme_spec_nvm_scopy_fmt_zero
 * @param nr Number of ranges in the given ranges-buffer, zero-based value
 * @param copy_fmt For of ranges
 *
 * @return On success, 0 is returned. On error, -1 is returned, `errno` set to
 * indicate and `ctx.cpl` filled with lower-level status codes
 */
int
xnvme_nvm_scopy(struct xnvme_cmd_ctx *ctx, uint32_t nsid, uint64_t sdlba,
		struct xnvme_spec_nvm_scopy_fmt_zero *ranges, uint8_t nr,
		enum xnvme_nvm_scopy_fmt copy_fmt);

#ifdef __cplusplus
}
#endif

#endif /* __LIBXNVME_NVM */

Enums¶

xnvme_nvm_scopy_fmt¶

enum xnvme_nvm_scopy_fmt¶

Structure conversion for support Kernel format.

Values:

enumerator XNVME_NVM_SCOPY_FMT_ZERO¶: user provides entries formatted as XNVME_NVM_SCOPY_FMT_ZERO

enumerator XNVME_NVM_SCOPY_FMT_SRCLEN¶: user provides entries formatted as XNVME_NVM_SCOPY_FMT_SRCLEN

xnvme_nvme_sgl_descriptor_type¶

enum xnvme_nvme_sgl_descriptor_type¶

Values:

enumerator XNVME_SPEC_SGL_DESCR_TYPE_DATA_BLOCK¶: XNVME_SPEC_SGL_DESCR_TYPE_DATA_BLOCK.

enumerator XNVME_SPEC_SGL_DESCR_TYPE_BIT_BUCKET¶: XNVME_SPEC_SGL_DESCR_TYPE_BIT_BUCKET.

enumerator XNVME_SPEC_SGL_DESCR_TYPE_SEGMENT¶: XNVME_SPEC_SGL_DESCR_TYPE_SEGMENT.

enumerator XNVME_SPEC_SGL_DESCR_TYPE_LAST_SEGMENT¶: XNVME_SPEC_SGL_DESCR_TYPE_LAST_SEGMENT.

enumerator XNVME_SPEC_SGL_DESCR_TYPE_KEYED_DATA_BLOCK¶: XNVME_SPEC_SGL_DESCR_TYPE_KEYED_DATA_BLOCK.

enumerator XNVME_SPEC_SGL_DESCR_TYPE_VENDOR_SPECIFIC¶: XNVME_SPEC_SGL_DESCR_TYPE_VENDOR_SPECIFIC.

Structs¶

Functions¶

xnvme_nvm_read¶

int xnvme_nvm_read(struct xnvme_cmd_ctx *ctx, uint32_t nsid, uint64_t slba, uint16_t nlb, void *dbuf, void *mbuf)¶

Submit, and optionally wait for completion of, a NVMe Read.

Return

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

Parameters

ctx: Pointer to command context (xnvme_cmd_ctx)
nsid: Namespace Identifier
slba: The LBA to start reading from
nlb: The number of LBAs to read. NOTE: nlb is a zero-based value
dbuf: Pointer to data-payload
mbuf: Pointer to meta-payload

xnvme_nvm_sanitize¶

int xnvme_nvm_sanitize(struct xnvme_cmd_ctx *ctx, uint8_t sanact, uint8_t ause, uint32_t ovrpat, uint8_t owpass, uint8_t oipbp, uint8_t nodas)¶

Submit and wait for completion of an Sanitize command.

Todo:: consider timeout, reset, and need for library/dev re-initialization

Note

Success of this function only means that the sanitize command succeeded and that the sanitize operation has started.

Return

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

Parameters

ctx: Pointer to xnvme_cmd_ctx
sanact: Sanitize action; 0x1: Exit failure mode, 0x2: Block Erase, 0x3 Overwrite, 0x4 Crypto Erase
ause: Allow Unrestricted Sanitize Exit; 0x0: Restricted Mode, 0x1: Unrestricted Mode
ovrpat: Overwrite Pattern; 32-bit pattern used by the Overwrite action
owpass: Overwrite pass Count, how many times the media is to be overwritten; 0x0: 15 overwrite passes
oipbp: Overwrite invert pattern between passes; 0x0: Disabled, 0x1: Enabled
nodas: No Deallocate After Sanitize; 0x0: Attempt to deallocate; 0x1 Do not attempt to deallocate

xnvme_nvm_scopy¶

int xnvme_nvm_scopy(struct xnvme_cmd_ctx *ctx, uint32_t nsid, uint64_t sdlba, struct xnvme_spec_nvm_scopy_fmt_zero *ranges, uint8_t nr, enum xnvme_nvm_scopy_fmt copy_fmt)¶

Submit, and optionally wait for completion of a NVMe Simple-Copy-Command.

See

xnvme_cmd_opts

Return

On success, 0 is returned. On error, -1 is returned, errno set to indicate and ctx.cpl filled with lower-level status codes

Parameters

ctx: Pointer to command context (xnvme_cmd_ctx)
nsid: Namespace Identifier
sdlba: The Starting Destination LBA to start copying to
ranges: Pointer to ranges-buffer, see xnvme_spec_nvm_scopy_fmt_zero
nr: Number of ranges in the given ranges-buffer, zero-based value
copy_fmt: For of ranges

xnvme_nvm_write¶

int xnvme_nvm_write(struct xnvme_cmd_ctx *ctx, uint32_t nsid, uint64_t slba, uint16_t nlb, const void *dbuf, const void *mbuf)¶

Submit, and optionally wait for completion of, a NVMe Write.

Return

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

Parameters

ctx: Pointer to command context (xnvme_cmd_ctx)
nsid: Namespace Identifier
slba: The LBA to start the write at
nlb: Number of LBAs to be written. NOTE: nlb is a zero-based value
dbuf: Pointer to buffer; Payload as indicated by ‘ctx->opts’
mbuf: Pointer to buffer; Payload as indicated by ‘ctx->opts’

xnvme_nvm_write_uncorrectable¶

int xnvme_nvm_write_uncorrectable(struct xnvme_cmd_ctx *ctx, uint32_t nsid, uint64_t slba, uint16_t nlb)¶

Submit a write uncorrected command.

Parameters

ctx: Pointer to command context (xnvme_cmd_ctx)
nsid: Namespace Identifier
slba: The Starting Destination LBA
nlb: Number Of Logical Blocks

xnvme_nvm_write_zeroes¶

int xnvme_nvm_write_zeroes(struct xnvme_cmd_ctx *ctx, uint32_t nsid, uint64_t sdlba, uint16_t nlb)¶

Submit a write zeroes command.

See

xnvme_cmd_opts

Return

On success, 0 is returned. On error, -1 is returned, errno set to indicate and param ctx.cpl filled with lower-level status codes

Parameters

ctx: Pointer to command context (xnvme_cmd_ctx)
nsid: Namespace Identifier
sdlba: The Starting Destination LBA to start copying to
nlb: Number Of Logical Blocks