libxnvme_buf.h#

Functions#

xnvme_buf_alloc#

void *xnvme_buf_alloc(const struct xnvme_dev *dev, size_t nbytes)#

Allocate a buffer for IO with the given device.

The buffer will be aligned to device geometry and DMA allocated if required by the backend for command payloads

Note

nbytes must be greater than zero and a multiple of minimal granularity

Note

De-allocate the buffer using xnvme_buf_free()

Note

Control plane: serialised with the other control-plane calls, not with I/O on the same device, queue or buffer; see Thread Safety in the API documentation

Parameters:
  • dev – Device handle obtained with xnvme_dev_open()

  • nbytes – The size of the allocated buffer in bytes

Returns:

On success, a pointer to the allocated memory is returned. On error, NULL is returned and errno set to indicate the error.

xnvme_buf_clear#

int xnvme_buf_clear(void *buf, size_t nbytes)#

Write zeroes to the first ‘nbytes’ of ‘buf’.

Parameters:
  • buf – Pointer to the buffer to fill with zeroes

  • nbytes – Amount of bytes to fill with zeroes in buf

Returns:

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

xnvme_buf_diff#

int xnvme_buf_diff(const void *expected, const void *actual, size_t nbytes, size_t *diff)#

Compare two buffers and count the number of differing bytes.

Parameters:
  • expected – Pointer to buffer containing the expected data

  • actual – Pointer to buffer to compare against the expected data

  • nbytes – Number of bytes to compare

  • diff – Output pointer storing the number of differing bytes

Returns:

0 on success, negative errno on error.

xnvme_buf_fill#

int xnvme_buf_fill(void *buf, size_t nbytes, const char *content)#

Fills buf with content nbytes of content.

The behaviour of this function changes according to the value of content.

If content is a single character, the buffer will be filled with nbytes repetitions of this character. NOTE: Make sure the argument uses string notation, e.g., “!”. Giving a pointer to a char won’t work.

If content is a file name, the buffer will be filled with nbytes of the content of this file.

If content == “zero”, the buffer will be filled with 0s If content == “anum”, the buffer will be filled with ASCII characters in order If content == “rand-k”, the buffer will be filled with ASCII characters randomly sampled with srand(time(NULL)) If content == “rand-t”, the buffer will be filled with ASCII characters randomly sampled with srand(0)

Parameters:
  • buf – Pointer to the buffer to fill

  • content – A single character, name of a file, or special “zero”, “anum”, “rand-k”, “rand-t”

  • nbytes – Amount of bytes to fill in buf

Returns:

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

xnvme_buf_free#

void xnvme_buf_free(const struct xnvme_dev *dev, void *buf)#

Free the given IO buffer allocated with xnvme_buf_alloc().

Note

Control plane: serialised with the other control-plane calls, not with I/O on the same device, queue or buffer; see Thread Safety in the API documentation

Parameters:

xnvme_buf_from_file#

int xnvme_buf_from_file(void *buf, size_t nbytes, const char *path)#

Read content of file into buffer.

Parameters:
  • buf – Pointer to the buffer

  • nbytes – Size of buf

  • path – Source to read from

Returns:

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

xnvme_buf_get_alignment#

int xnvme_buf_get_alignment(const struct xnvme_dev *dev, size_t *align)#

Retrieve the alignment of memory to register with the given device.

The alignment is a power of two, and at least sizeof(void *). It is the larger of what the device needs to register memory, of any kind it takes, and what its I/O path needs of command payloads. Retrieve it before allocating memory that is to be registered, to allocate it suitably.

Parameters:
  • dev – Device handle obtained with xnvme_dev_open()

  • align – Set to the alignment on success

Returns:

On success, 0 is returned. On error, negative errno is returned and align is left untouched; -ENOSYS when the device does not register memory.

xnvme_buf_memcpy#

int xnvme_buf_memcpy(void *dst, const void *src, size_t nbytes)#

Copy ‘nbytes’ from ‘src’ to ‘dst’.

Parameters:
  • dst – Pointer to the destination buffer

  • src – Pointer to the source buffer

  • nbytes – Amount of bytes to copy

Returns:

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

xnvme_buf_phys_alloc#

void *xnvme_buf_phys_alloc(const struct xnvme_dev *dev, size_t nbytes, uint64_t *phys)#

Allocate a buffer of physical memory, aligned for IO with the given device.

Note

nbytes must be greater than zero and a multiple of minimal granularity

Note

De-allocate the buffer using xnvme_buf_phys_free()

Note

Control plane: serialised with the other control-plane calls, not with I/O on the same device, queue or buffer; see Thread Safety in the API documentation

Parameters:
  • dev – Device handle obtained with xnvme_dev_open()

  • nbytes – The size of the allocated buffer in bytes

  • phys – A pointer to the variable to hold the physical address of the allocated buffer. If NULL, the physical address is not returned.

Returns:

On success, a pointer to the allocated memory is returned. On error, NULL is returned and errno set to indicate the error.

xnvme_buf_phys_free#

void xnvme_buf_phys_free(const struct xnvme_dev *dev, void *buf)#

Free the given buffer of physical memory allocated with xnvme_buf_phys_alloc().

Note

Control plane: serialised with the other control-plane calls, not with I/O on the same device, queue or buffer; see Thread Safety in the API documentation

Parameters:

xnvme_buf_phys_realloc#

void *xnvme_buf_phys_realloc(const struct xnvme_dev *dev, void *buf, size_t nbytes, uint64_t *phys)#

Re-allocate a buffer of physical memory, aligned for IO with the given device.

Note

nbytes must be greater than zero and a multiple of minimal granularity

Note

De-allocate the buffer using xnvme_buf_phys_free()

Note

Control plane: serialised with the other control-plane calls, not with I/O on the same device, queue or buffer; see Thread Safety in the API documentation

Parameters:
  • dev – Device handle obtained with xnvme_dev_open()

  • buf – The buffer to reallocate

  • nbytes – The size of the allocated buffer in bytes

  • phys – A pointer to the variable to hold the physical address of the allocated buffer. If NULL, the physical address is not returned.

Returns:

On success, a pointer to the allocated memory is returned. On error, NULL is returned and errno set to indicate the error.

xnvme_buf_realloc#

void *xnvme_buf_realloc(const struct xnvme_dev *dev, void *buf, size_t nbytes)#

Reallocate a buffer for IO with the given device.

The buffer will be aligned to device geometry and DMA allocated if required by the backend for IO

Note

nbytes must be greater than zero and a multiple of minimal granularity

Note

De-allocate the buffer using xnvme_buf_free()

Note

Control plane: serialised with the other control-plane calls, not with I/O on the same device, queue or buffer; see Thread Safety in the API documentation

Parameters:
  • dev – Device handle obtained with xnvme_dev_open()

  • buf – The buffer to reallocate

  • nbytes – The size of the allocated buffer in bytes

Returns:

On success, a pointer to the allocated memory is returned. On error, NULL is returned and errno set to indicate the error.

xnvme_buf_register#

int xnvme_buf_register(const struct xnvme_dev *dev, void *vaddr, size_t nbytes)#

Register memory of the caller’s for use as command payload with the given device.

Registering makes memory the caller allocated itself, rather than with xnvme_buf_alloc(), usable as the payload of commands to the device.

Each registration is given back by one call to xnvme_buf_unregister(). Registering a range that is registered already, or a range within one, is counted on that registration rather than registered again; a range that overlaps a registration otherwise is refused with -EBUSY. Memory from xnvme_buf_alloc() is usable already, and registering and unregistering it does nothing.

Note

Unregister the memory with xnvme_buf_unregister()

Note

vaddr and nbytes must be multiples of the alignment given by xnvme_buf_get_alignment()

Note

Control plane: serialised with the other control-plane calls, not with I/O on the same device, queue or buffer; see Thread Safety in the API documentation

Parameters:
  • dev – Device handle obtained with xnvme_dev_open()

  • vaddr – The address the caller accesses the memory at

  • nbytes – The number of bytes to register, starting at vaddr

Returns:

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

xnvme_buf_to_file#

int xnvme_buf_to_file(void *buf, size_t nbytes, const char *path)#

Write content of buffer into file.

  • If file exists, then it is truncated / overwritten

  • If file does NOT exist, then it is created

  • When file is created, permissions are set to user WRITE + READ

Parameters:
  • buf – Pointer to the buffer

  • nbytes – Size of buf

  • path – Destination where buffer will be dumped to

Returns:

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

xnvme_buf_unregister#

int xnvme_buf_unregister(const struct xnvme_dev *dev, void *vaddr)#

Unregister memory registered with xnvme_buf_register().

Note

Control plane: serialised with the other control-plane calls, not with I/O on the same device, queue or buffer; see Thread Safety in the API documentation

Parameters:
  • dev – Device handle obtained with xnvme_dev_open()

  • vaddr – The address the memory was registered at

Returns:

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

xnvme_buf_virt_alloc#

void *xnvme_buf_virt_alloc(size_t alignment, size_t nbytes)#

Allocate a buffer of virtual memory of the given alignment and nbytes.

Note

You must use xnvme_buf_virt_free() to de-allocate the buffer

Parameters:
  • alignment – The alignment in bytes

  • nbytes – The size of the buffer in bytes

Returns:

On success, a pointer to the allocated memory is return. On error, NULL is returned and errno set to indicate the error

xnvme_buf_virt_free#

void xnvme_buf_virt_free(void *buf)#

Free the given virtual memory buffer.

Parameters:

xnvme_buf_vtophys#

int xnvme_buf_vtophys(const struct xnvme_dev *dev, void *buf, uint64_t *phys)#

Retrieve the physical address of the given buffer.

The intended use for this function is to provide the physical-address of a buffer-allocation allocated with xnvme_buf_phys_alloc() or xnvme_buf_alloc(), where the ‘phys’ argument was either not provided.

Note

Control plane: serialised with the other control-plane calls, not with I/O on the same device, queue or buffer; see Thread Safety in the API documentation

Parameters:
  • dev – Device handle obtained with xnvme_dev_open()

  • buf – Pointer to a buffer allocated with xnvme_buf_alloc()

  • phys – A pointer to the variable to hold the physical address of the given buffer.

Returns:

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

Header#

/**
 * SPDX-FileCopyrightText: Samsung Electronics Co., Ltd
 *
 * SPDX-License-Identifier: BSD-3-Clause
 *
 * @file libxnvme_buf.h
 */

/**
 * Allocate a buffer for IO with the given device
 *
 * The buffer will be aligned to device geometry and DMA allocated if required by the backend for
 * command payloads
 *
 * @note nbytes must be greater than zero and a multiple of minimal granularity
 * @note De-allocate the buffer using xnvme_buf_free()
 * @note Control plane: serialised with the other control-plane calls, not with I/O on the
 * same device, queue or buffer; see Thread Safety in the API documentation
 *
 * @param dev Device handle obtained with xnvme_dev_open()
 * @param nbytes The size of the allocated buffer in bytes
 *
 * @return On success, a pointer to the allocated memory is returned. On error, NULL is returned
 * and `errno` set to indicate the error.
 */
void *
xnvme_buf_alloc(const struct xnvme_dev *dev, size_t nbytes);

/**
 * Reallocate a buffer for IO with the given device
 *
 * The buffer will be aligned to device geometry and DMA allocated if required by the backend for
 * IO
 *
 * @note nbytes must be greater than zero and a multiple of minimal granularity
 * @note De-allocate the buffer using xnvme_buf_free()
 * @note Control plane: serialised with the other control-plane calls, not with I/O on the
 * same device, queue or buffer; see Thread Safety in the API documentation
 *
 * @param dev Device handle obtained with xnvme_dev_open()
 * @param buf The buffer to reallocate
 * @param nbytes The size of the allocated buffer in bytes
 *
 * @return On success, a pointer to the allocated memory is returned. On error, NULL is returned
 * and `errno` set to indicate the error.
 */
void *
xnvme_buf_realloc(const struct xnvme_dev *dev, void *buf, size_t nbytes);

/**
 * Free the given IO buffer allocated with xnvme_buf_alloc()
 *
 * @note Control plane: serialised with the other control-plane calls, not with I/O on the
 * same device, queue or buffer; see Thread Safety in the API documentation
 *
 * @param dev Device handle obtained with xnvme_dev_open()
 * @param buf Pointer to a buffer allocated with xnvme_buf_alloc()
 */
void
xnvme_buf_free(const struct xnvme_dev *dev, void *buf);

/**
 * Allocate a buffer of physical memory, aligned for IO with the given device
 *
 * @note nbytes must be greater than zero and a multiple of minimal granularity
 * @note De-allocate the buffer using xnvme_buf_phys_free()
 * @note Control plane: serialised with the other control-plane calls, not with I/O on the
 * same device, queue or buffer; see Thread Safety in the API documentation
 *
 * @param dev Device handle obtained with xnvme_dev_open()
 * @param nbytes The size of the allocated buffer in bytes
 * @param phys A pointer to the variable to hold the physical address of the allocated buffer. If
 * NULL, the physical address is not returned.
 *
 * @return On success, a pointer to the allocated memory is returned. On error, NULL is returned
 * and `errno` set to indicate the error.
 */
void *
xnvme_buf_phys_alloc(const struct xnvme_dev *dev, size_t nbytes, uint64_t *phys);

/**
 * Free the given buffer of physical memory allocated with xnvme_buf_phys_alloc()
 *
 * @note Control plane: serialised with the other control-plane calls, not with I/O on the
 * same device, queue or buffer; see Thread Safety in the API documentation
 *
 * @param dev Device handle obtained with xnvme_dev_open()
 * @param buf Pointer to a buffer allocated with xnvme_buf_phys_alloc()
 */
void
xnvme_buf_phys_free(const struct xnvme_dev *dev, void *buf);

/**
 * Re-allocate a buffer of physical memory, aligned for IO with the given device
 *
 * @note nbytes must be greater than zero and a multiple of minimal granularity
 * @note De-allocate the buffer using xnvme_buf_phys_free()
 * @note Control plane: serialised with the other control-plane calls, not with I/O on the
 * same device, queue or buffer; see Thread Safety in the API documentation
 *
 * @param dev Device handle obtained with xnvme_dev_open()
 * @param buf The buffer to reallocate
 * @param nbytes The size of the allocated buffer in bytes
 * @param phys A pointer to the variable to hold the physical address of the allocated buffer. If
 * NULL, the physical address is not returned.
 *
 * @return On success, a pointer to the allocated memory is returned. On error, NULL is returned
 * and `errno` set to indicate the error.
 */
void *
xnvme_buf_phys_realloc(const struct xnvme_dev *dev, void *buf, size_t nbytes, uint64_t *phys);

/**
 * Retrieve the physical address of the given buffer
 *
 * The intended use for this function is to provide the physical-address of a buffer-allocation
 * allocated with xnvme_buf_phys_alloc() or xnvme_buf_alloc(), where the 'phys' argument was either
 * not provided.
 *
 * @note Control plane: serialised with the other control-plane calls, not with I/O on the
 * same device, queue or buffer; see Thread Safety in the API documentation
 *
 * @param dev Device handle obtained with xnvme_dev_open()
 * @param buf Pointer to a buffer allocated with xnvme_buf_alloc()
 * @param phys A pointer to the variable to hold the physical address of the given buffer.
 *
 * @return On success, 0 is returned. On error, negative `errno` is returned.
 */
int
xnvme_buf_vtophys(const struct xnvme_dev *dev, void *buf, uint64_t *phys);

/**
 * Register memory of the caller's for use as command payload with the given device
 *
 * Registering makes memory the caller allocated itself, rather than with xnvme_buf_alloc(),
 * usable as the payload of commands to the device.
 *
 * Each registration is given back by one call to xnvme_buf_unregister(). Registering a range
 * that is registered already, or a range within one, is counted on that registration rather than
 * registered again; a range that overlaps a registration otherwise is refused with `-EBUSY`.
 * Memory from xnvme_buf_alloc() is usable already, and registering and unregistering it does
 * nothing.
 *
 * @note Unregister the memory with xnvme_buf_unregister()
 * @note vaddr and nbytes must be multiples of the alignment given by xnvme_buf_get_alignment()
 * @note Control plane: serialised with the other control-plane calls, not with I/O on the
 * same device, queue or buffer; see Thread Safety in the API documentation
 *
 * @param dev Device handle obtained with xnvme_dev_open()
 * @param vaddr The address the caller accesses the memory at
 * @param nbytes The number of bytes to register, starting at vaddr
 *
 * @return On success, 0 is returned. On error, negative `errno` is returned.
 */
int
xnvme_buf_register(const struct xnvme_dev *dev, void *vaddr, size_t nbytes);

/**
 * Unregister memory registered with xnvme_buf_register()
 *
 * @note Control plane: serialised with the other control-plane calls, not with I/O on the
 * same device, queue or buffer; see Thread Safety in the API documentation
 *
 * @param dev Device handle obtained with xnvme_dev_open()
 * @param vaddr The address the memory was registered at
 *
 * @return On success, 0 is returned. On error, negative `errno` is returned.
 */
int
xnvme_buf_unregister(const struct xnvme_dev *dev, void *vaddr);

/**
 * Retrieve the alignment of memory to register with the given device
 *
 * The alignment is a power of two, and at least `sizeof(void *)`. It is the larger of what the
 * device needs to register memory, of any kind it takes, and what its I/O path needs of command
 * payloads. Retrieve it before allocating memory that is to be registered, to allocate it
 * suitably.
 *
 * @param dev Device handle obtained with xnvme_dev_open()
 * @param align Set to the alignment on success
 *
 * @return On success, 0 is returned. On error, negative `errno` is returned and `align` is left
 * untouched; `-ENOSYS` when the device does not register memory.
 */
int
xnvme_buf_get_alignment(const struct xnvme_dev *dev, size_t *align);

/**
 * Allocate a buffer of virtual memory of the given `alignment` and `nbytes`
 *
 * @note You must use xnvme_buf_virt_free() to de-allocate the buffer
 *
 * @param alignment The alignment in bytes
 * @param nbytes The size of the buffer in bytes
 *
 * @return On success, a pointer to the allocated memory is return. On error, NULL is returned and
 * `errno` set to indicate the error
 */
void *
xnvme_buf_virt_alloc(size_t alignment, size_t nbytes);

/**
 * Free the given virtual memory buffer
 *
 * @param buf Pointer to a buffer allocated with xnvme_buf_virt_alloc()
 */
void
xnvme_buf_virt_free(void *buf);

/**
 * Fills `buf` with content `nbytes` of content
 *
 * The behaviour of this function changes according to the value of content.
 *
 * If content is a single character, the buffer will be filled with nbytes
 * repetitions of this character.
 * NOTE: Make sure the argument uses string notation, e.g., "!". Giving a pointer
 * to a char won't work.
 *
 * If content is a file name, the buffer will be filled with nbytes of the
 * content of this file.
 *
 * If content == "zero", the buffer will be filled with 0s
 * If content == "anum", the buffer will be filled with ASCII characters in order
 * If content == "rand-k", the buffer will be filled with ASCII characters
 * randomly sampled with `srand(time(NULL))`
 * If content == "rand-t", the buffer will be filled with ASCII characters
 * randomly sampled with `srand(0)`
 *
 * @param buf Pointer to the buffer to fill
 * @param content A single character, name of a file, or special "zero", "anum", "rand-k", "rand-t"
 * @param nbytes Amount of bytes to fill in buf
 *
 * @return On success, 0 is returned. On error, negative `errno` is returned.
 */
int
xnvme_buf_fill(void *buf, size_t nbytes, const char *content);

/**
 * Write zeroes to the first 'nbytes' of 'buf'
 *
 * @param buf Pointer to the buffer to fill with zeroes
 * @param nbytes Amount of bytes to fill with zeroes in buf
 *
 * @return On success, 0 is returned. On error, negative `errno` is returned.
 */
int
xnvme_buf_clear(void *buf, size_t nbytes);

/**
 * Copy 'nbytes' from 'src' to 'dst'
 *
 * @param dst Pointer to the destination buffer
 * @param src Pointer to the source buffer
 * @param nbytes Amount of bytes to copy
 *
 * @return On success, 0 is returned. On error, negative `errno` is returned.
 */
int
xnvme_buf_memcpy(void *dst, const void *src, size_t nbytes);

/**
 * Compare two buffers and count the number of differing bytes.
 *
 * @param expected Pointer to buffer containing the expected data
 * @param actual Pointer to buffer to compare against the expected data
 * @param nbytes Number of bytes to compare
 * @param diff Output pointer storing the number of differing bytes
 *
 * @return 0 on success, negative `errno` on error.
 */
int
xnvme_buf_diff(const void *expected, const void *actual, size_t nbytes, size_t *diff);

/**
 * Write content of buffer into file
 *
 * - If file exists, then it is truncated / overwritten
 * - If file does NOT exist, then it is created
 * - When file is created, permissions are set to user WRITE + READ
 *
 * @param buf Pointer to the buffer
 * @param nbytes Size of buf
 * @param path Destination where buffer will be dumped to
 *
 * @return On success, 0 is returned. On error, negative `errno` is returned.
 */
int
xnvme_buf_to_file(void *buf, size_t nbytes, const char *path);

/**
 * Read content of file into buffer
 *
 * @param buf Pointer to the buffer
 * @param nbytes Size of buf
 * @param path Source to read from
 *
 * @return On success, 0 is returned. On error, negative `errno` is returned.
 */
int
xnvme_buf_from_file(void *buf, size_t nbytes, const char *path);