libxnvme_buf.h#

Functions#

xnvme_buf_alloc#

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

SPDX-FileCopyrightText: Samsung Electronics Co., Ltd.

SPDX-License-Identifier: BSD-3-Clause 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()

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

int xnvme_buf_diff_pr(const void *expected, const void *actual, size_t nbytes, int opts)#

Prints the number and value of bytes where expected is different from actual.

Parameters:

  • expected – Pointer to buffer of “expected” content

  • actual – Pointer to buffer to compare to “expected”

  • nbytes – Amount of bytes to compare

  • opts – printer options, see xnvme_pr

Returns:

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

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

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_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()

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

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

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

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_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_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.

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.