xnvme_nvm
Header
/**
* SPDX-FileCopyrightText: Samsung Electronics Co., Ltd
*
* SPDX-License-Identifier: BSD-3-Clause
*
* @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 slba The LBA to start the write at
* @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 slba, 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);
/**
* Deallocate or hint at read/write usage of a range.
*
* @param ctx Pointer to command context (::xnvme_cmd_ctx)
* @param nsid Namespace Identifier
* @param dsm_range A buffer of ranges, each with context attributes, slba and nlb
* @param nr Number of ranges in the given ranges-buffer, zero-based value
* @param ad The NVM subsystem may deallocate all provided ranges
* @param idw The dataset should be optimized for write access as an integral unit
* @param idr The dataset should be optimized for read access as an integral unit
*
* @return On success, 0 is returned. On error, -1 is returned.
*/
int
xnvme_nvm_dsm(struct xnvme_cmd_ctx *ctx, uint32_t nsid, struct xnvme_spec_dsm_range *dsm_range,
uint8_t nr, bool ad, bool idw, bool idr);
/**
* Submit, and wait for completion of a I/O management receive command
*
* @see xnvme_cmd_opts
*
* @param ctx Pointer to command context (::xnvme_cmd_ctx)
* @param nsid Namespace Identifier
* @param mo Management operation
* @param mos Management operation specific field
* @param dbuf pointer to data-payload
* @param dbuf_nbytes size of the data-payload in bytes
*
* @return On success, 0 is returned. On error, negative `errno` is returned.
*/
int
xnvme_nvm_mgmt_recv(struct xnvme_cmd_ctx *ctx, uint32_t nsid, uint8_t mo, uint16_t mos, void *dbuf,
uint32_t dbuf_nbytes);
/**
* Submit, and wait for completion of a I/O management send command
*
* @see xnvme_cmd_opts
*
* @param ctx Pointer to command context (::xnvme_cmd_ctx)
* @param nsid Namespace Identifier
* @param mo Management operation
* @param mos Management operation specific field
* @param dbuf pointer to data-payload
* @param dbuf_nbytes size of the data-payload in bytes
*
* @return On success, 0 is returned. On error, negative `errno` is returned.
*/
int
xnvme_nvm_mgmt_send(struct xnvme_cmd_ctx *ctx, uint32_t nsid, uint8_t mo, uint16_t mos, void *dbuf,
uint32_t dbuf_nbytes);
#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
-
enumerator XNVME_NVM_SCOPY_FMT_ZERO
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.
-
enumerator XNVME_SPEC_SGL_DESCR_TYPE_DATA_BLOCK
Structs
Functions
xnvme_nvm_dsm
-
int xnvme_nvm_dsm(struct xnvme_cmd_ctx *ctx, uint32_t nsid, struct xnvme_spec_dsm_range *dsm_range, uint8_t nr, bool ad, bool idw, bool idr)
Deallocate or hint at read/write usage of a range.
- Parameters:
ctx – Pointer to command context (xnvme_cmd_ctx)
nsid – Namespace Identifier
dsm_range – A buffer of ranges, each with context attributes, slba and nlb
nr – Number of ranges in the given ranges-buffer, zero-based value
ad – The NVM subsystem may deallocate all provided ranges
idw – The dataset should be optimized for write access as an integral unit
idr – The dataset should be optimized for read access as an integral unit
- Returns:
On success, 0 is returned. On error, -1 is returned.
xnvme_nvm_mgmt_recv
-
int xnvme_nvm_mgmt_recv(struct xnvme_cmd_ctx *ctx, uint32_t nsid, uint8_t mo, uint16_t mos, void *dbuf, uint32_t dbuf_nbytes)
Submit, and wait for completion of a I/O management receive command.
See also
xnvme_cmd_opts
- Parameters:
ctx – Pointer to command context (xnvme_cmd_ctx)
nsid – Namespace Identifier
mo – Management operation
mos – Management operation specific field
dbuf – pointer to data-payload
dbuf_nbytes – size of the data-payload in bytes
- Returns:
On success, 0 is returned. On error, negative
errno
is returned.
xnvme_nvm_mgmt_send
-
int xnvme_nvm_mgmt_send(struct xnvme_cmd_ctx *ctx, uint32_t nsid, uint8_t mo, uint16_t mos, void *dbuf, uint32_t dbuf_nbytes)
Submit, and wait for completion of a I/O management send command.
See also
xnvme_cmd_opts
- Parameters:
ctx – Pointer to command context (xnvme_cmd_ctx)
nsid – Namespace Identifier
mo – Management operation
mos – Management operation specific field
dbuf – pointer to data-payload
dbuf_nbytes – size of the data-payload in bytes
- Returns:
On success, 0 is returned. On error, negative
errno
is returned.
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)
SPDX-FileCopyrightText: Samsung Electronics Co., Ltd.
SPDX-License-Identifier: BSD-3-Clause Submit, and optionally wait for completion of, a NVMe Read
- 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
- Returns:
On success, 0 is returned. On error, negative
errno
is returned.
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.
- 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
- Returns:
On success, 0 is returned. On error, negative
errno
is returned.
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 also
xnvme_cmd_opts
- 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
- Returns:
On success, 0 is returned. On error, -1 is returned,
errno
set to indicate andctx.cpl
filled with lower-level status codes
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.
- 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’
- Returns:
On success, 0 is returned. On error, negative
errno
is returned.
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 slba, uint16_t nlb)
Submit a write zeroes command.
See also
xnvme_cmd_opts
- Parameters:
ctx – Pointer to command context (xnvme_cmd_ctx)
nsid – Namespace Identifier
slba – The LBA to start the write at
nlb – Number Of Logical Blocks
- Returns:
On success, 0 is returned. On error, -1 is returned,
errno
set to indicate and param ctx.cpl filled with lower-level status codes