util.h File Reference

General utility functions. More...

Data Structures
struct	spdk_single_ioviter
struct	spdk_ioviter
	An N-way iovec iterator. More...
struct	spdk_iov_xfer
	Transfer state for iterative copying in or out of an iovec. More...

Macros
#define	__STDC_WANT_LIB_EXT1__   1
#define	SPDK_CACHE_LINE_SIZE   64
#define	spdk_min(a, b)   (((a)<(b))?(a):(b))
#define	spdk_max(a, b)   (((a)>(b))?(a):(b))
#define	SPDK_COUNTOF(arr)   (sizeof(arr) / sizeof((arr)[0]))
#define	SPDK_CONTAINEROF(ptr, type, member)   ((type *)((uintptr_t)ptr - offsetof(type, member)))
#define	SPDK_SIZEOF(ptr, member)   (offsetof(__typeof__(*(ptr)), member) + sizeof((ptr)->member))
	Returns size of an object pointer by ptr up to and including member.
#define	SPDK_SIZEOF_MEMBER(type, member)   (sizeof(((type *)0)->member))
	Get the size of a member of a struct.
#define	SPDK_COUNTOF_MEMBER(type, member)   (SPDK_COUNTOF(((type *)0)->member))
	Get the number of elements in an array of a struct member.
#define	SPDK_SEC_TO_MSEC   1000ULL
#define	SPDK_SEC_TO_USEC   1000000ULL
#define	SPDK_SEC_TO_NSEC   1000000000ULL
#define	SPDK_CEIL_DIV(x, y)   (((x)+(y)-1)/(y))
#define	SPDK_ALIGN_FLOOR(val, align)    (__typeof__(val))((val) & (~((__typeof__(val))((align) - 1))))
	Macro to align a value to a given power-of-two.
#define	SPDK_ALIGN_CEIL(val, align)    SPDK_ALIGN_FLOOR(((val) + ((__typeof__(val)) (align) - 1)), align)
	Macro to align a value to a given power-of-two.
#define	SPDK_BIT(n)   (1ul << (n))
#define	SPDK_FIELD_VALID(obj, field, ...)    _SPDK_FIELD_VALID(obj, field, ## __VA_ARGS__, (obj)->size)
	Check if a given field is valid in a structure with size tracking.
#define	_SPDK_FIELD_VALID(obj, field, size, ...)    ((size) >= (offsetof(__typeof__(*(obj)), field) + sizeof((obj)->field)))
#define	SPDK_GET_FIELD(obj, field, defval, ...)    _SPDK_GET_FIELD(obj, field, defval, ## __VA_ARGS__, (obj)->size)
	Get a field from a structure with size tracking.
#define	_SPDK_GET_FIELD(obj, field, defval, size, ...)    (SPDK_FIELD_VALID(obj, field, size) ? (obj)->field : (defval))
#define	SPDK_IOVITER_SIZE(count)   (sizeof(struct spdk_single_ioviter) * (count - 2) + sizeof(struct spdk_ioviter))
#define	SPDK_IOV_ONE(piov, piovcnt, buf, buflen)
	Initialize an iovec with just the single given buffer.
#define	SPDK_CLANG_ANALYZER_PREINIT_PTR_ARRAY(arr, arr_size, buf_size)
	Scan build is really pessimistic and assumes that mempool functions can dequeue NULL buffers even if they return success.
#define	SPDK_SN32_CMPMAX   (1U << (32 - 1))

Functions
uint32_t	spdk_u32log2 (uint32_t x)
static uint32_t	spdk_align32pow2 (uint32_t x)
uint64_t	spdk_u64log2 (uint64_t x)
static uint64_t	spdk_align64pow2 (uint64_t x)
static bool	spdk_u32_is_pow2 (uint32_t x)
	Check if a uint32_t is a power of 2.
static bool	spdk_u64_is_pow2 (uint64_t x)
	Check if a uint64_t is a power of 2.
static uint64_t	spdk_divide_round_up (uint64_t num, uint64_t divisor)
size_t	spdk_ioviter_first (struct spdk_ioviter *iter, struct iovec *siov, size_t siovcnt, struct iovec *diov, size_t diovcnt, void **src, void **dst)
	Initialize and move to the first common segment of the two given iovecs.
size_t	spdk_ioviter_firstv (struct spdk_ioviter *iter, uint32_t count, struct iovec **iov, size_t *iovcnt, void **out)
	Initialize and move to the first common segment of the N given iovecs.
size_t	spdk_ioviter_next (struct spdk_ioviter *iter, void **src, void **dst)
	Move to the next segment in the iterator.
size_t	spdk_ioviter_nextv (struct spdk_ioviter *iter, void **out)
	Move to the next segment in the iterator.
void	spdk_iov_memset (struct iovec *iovs, int iovcnt, int c)
	Operate like memset across an iovec.
size_t	spdk_iovcpy (struct iovec *siov, size_t siovcnt, struct iovec *diov, size_t diovcnt)
	Copy the data described by the source iovec to the destination iovec.
size_t	spdk_iovmove (struct iovec *siov, size_t siovcnt, struct iovec *diov, size_t diovcnt)
	Same as spdk_iovcpy(), but the src/dst buffers might overlap.
void	spdk_iov_xfer_init (struct spdk_iov_xfer *ix, struct iovec *iovs, int iovcnt)
	Initialize a transfer context to point to the given iovec.
size_t	spdk_iov_xfer_from_buf (struct spdk_iov_xfer *ix, const void *buf, size_t buf_len)
	Copy from the given buf up to buf_len bytes, into the given ix iovec iterator, advancing the iterator as needed.
size_t	spdk_iov_xfer_to_buf (struct spdk_iov_xfer *ix, const void *buf, size_t buf_len)
	Copy from the given ix iovec iterator into the given buf up to buf_len bytes, advancing the iterator as needed.
void	spdk_copy_iovs_to_buf (void *buf, size_t buf_len, struct iovec *iovs, int iovcnt)
	Copy iovs contents to buf through memcpy.
void	spdk_copy_buf_to_iovs (struct iovec *iovs, int iovcnt, void *buf, size_t buf_len)
	Copy buf contents to iovs through memcpy.
static uint32_t	spdk_sn32_add (uint32_t s1, uint32_t s2)
	Add two sequence numbers s1 and s2.
static bool	spdk_sn32_lt (uint32_t s1, uint32_t s2)
	Compare if sequence number s1 is less than s2.
static bool	spdk_sn32_gt (uint32_t s1, uint32_t s2)
	Compare if sequence number s1 is greater than s2.
static void	spdk_memset_s (void *data, size_t data_size, int ch, size_t count)
	Copies the value (unsigned char)ch into each of the first count characters of the object pointed to by data data_size is used to check that filling count bytes won't lead to buffer overflow.

Detailed Description

General utility functions.

Macro Definition Documentation

SPDK_ALIGN_CEIL

#define SPDK_ALIGN_CEIL	(		val,
			align )    SPDK_ALIGN_FLOOR(((val) + ((__typeof__(val)) (align) - 1)), align)

Macro to align a value to a given power-of-two.

The resultant value will be of the same type as the first parameter, and will be no lower than the first parameter. Second parameter must be a power-of-two value.

SPDK_ALIGN_FLOOR

#define SPDK_ALIGN_FLOOR	(		val,
			align )    (__typeof__(val))((val) & (~((__typeof__(val))((align) - 1))))

Macro to align a value to a given power-of-two.

The resultant value will be of the same type as the first parameter, and will be no bigger than the first parameter. Second parameter must be a power-of-two value.

SPDK_CLANG_ANALYZER_PREINIT_PTR_ARRAY

#define SPDK_CLANG_ANALYZER_PREINIT_PTR_ARRAY	(		arr,
			arr_size,
			buf_size )

Value:

        do { \
                static char dummy_buf[buf_size]; \
                int i; \
                for (i = 0; i < arr_size; i++) { \
                        arr[i] = (void *)dummy_buf; \
                } \
        } while (0)

Scan build is really pessimistic and assumes that mempool functions can dequeue NULL buffers even if they return success.

This is obviously a false positive, but the mempool dequeue can be done in a DPDK inline function that we can't decorate with usual assert(buf != NULL). Instead, we'll preinitialize the dequeued buffer array with some dummy objects.

SPDK_FIELD_VALID

#define SPDK_FIELD_VALID	(		obj,
			field,
			... )    _SPDK_FIELD_VALID(obj, field, ## __VA_ARGS__, (obj)->size)

Check if a given field is valid in a structure with size tracking.

The third parameter is optional and can be used to specify the size of the object. If unset, (obj)->size will be used by default.

SPDK_GET_FIELD

#define SPDK_GET_FIELD	(		obj,
			field,
			defval,
			... )    _SPDK_GET_FIELD(obj, field, defval, ## __VA_ARGS__, (obj)->size)

Get a field from a structure with size tracking.

The fourth parameter is optional and can be used to specify the size of the object. If unset, (obj)->size will be used by default.

SPDK_IOV_ONE

#define SPDK_IOV_ONE	(		piov,
			piovcnt,
			buf,
			buflen )

Value:

        do {    \
        (piov)->iov_base = (buf);                       \
        (piov)->iov_len = (buflen);                     \
        *(piovcnt) = 1;                                 \
} while (0)

Initialize an iovec with just the single given buffer.

Function Documentation

spdk_iov_xfer_from_buf()

size_t spdk_iov_xfer_from_buf	(	struct spdk_iov_xfer *	ix,
		const void *	buf,
		size_t	buf_len )

Copy from the given buf up to buf_len bytes, into the given ix iovec iterator, advancing the iterator as needed.

. Returns the number of bytes copied.

spdk_iov_xfer_to_buf()

size_t spdk_iov_xfer_to_buf	(	struct spdk_iov_xfer *	ix,
		const void *	buf,
		size_t	buf_len )

Copy from the given ix iovec iterator into the given buf up to buf_len bytes, advancing the iterator as needed.

Returns the number of bytes copied.

spdk_iovcpy()

size_t spdk_iovcpy	(	struct iovec *	siov,
		size_t	siovcnt,
		struct iovec *	diov,
		size_t	diovcnt )

Copy the data described by the source iovec to the destination iovec.

Returns

The number of bytes copied.

spdk_ioviter_first()

size_t spdk_ioviter_first	(	struct spdk_ioviter *	iter,
		struct iovec *	siov,
		size_t	siovcnt,
		struct iovec *	diov,
		size_t	diovcnt,
		void **	src,
		void **	dst )

Initialize and move to the first common segment of the two given iovecs.

See spdk_ioviter_next().

spdk_ioviter_firstv()

size_t spdk_ioviter_firstv	(	struct spdk_ioviter *	iter,
		uint32_t	count,
		struct iovec **	iov,
		size_t *	iovcnt,
		void **	out )

Initialize and move to the first common segment of the N given iovecs.

See spdk_ioviter_nextv().

spdk_ioviter_next()

size_t spdk_ioviter_next	(	struct spdk_ioviter *	iter,
		void **	src,
		void **	dst )

Move to the next segment in the iterator.

This will iterate through the segments of the source and destination and return the individual segments, one by one. For example, if the source consists of one element of length 4k and the destination consists of 4 elements each of length 1k, this function will return 4 1k src+dst pairs of buffers, and then return 0 bytes to indicate the iteration is complete on the fifth call.

spdk_ioviter_nextv()

size_t spdk_ioviter_nextv	(	struct spdk_ioviter *	iter,
		void **	out )

Move to the next segment in the iterator.

This will iterate through the segments of the iovecs in the iterator and return the individual segments, one by one. For example, if the set consists one iovec of one element of length 4k and another iovec of 4 elements each of length 1k, this function will return 4 1k pairs of buffers, and then return 0 bytes to indicate the iteration is complete on the fifth call.

spdk_iovmove()

size_t spdk_iovmove	(	struct iovec *	siov,
		size_t	siovcnt,
		struct iovec *	diov,
		size_t	diovcnt )

Same as spdk_iovcpy(), but the src/dst buffers might overlap.

Returns

The number of bytes copied.

spdk_memset_s()

static void spdk_memset_s ( void * data, size_t data_size, int ch, size_t count )

inlinestatic

Copies the value (unsigned char)ch into each of the first count characters of the object pointed to by data data_size is used to check that filling count bytes won't lead to buffer overflow.

Parameters

data	Buffer to fill
data_size	Size of the buffer
ch	Fill byte
count	Number of bytes to fill

spdk_sn32_add()

static uint32_t spdk_sn32_add ( uint32_t s1, uint32_t s2 )

inlinestatic

Add two sequence numbers s1 and s2.

Parameters

s1	First sequence number
s2	Second sequence number

Returns

Sum of s1 and s2 based on serial number arithmetic.

spdk_sn32_gt()

static bool spdk_sn32_gt ( uint32_t s1, uint32_t s2 )

inlinestatic

Compare if sequence number s1 is greater than s2.

Parameters

s1	First sequence number
s2	Second sequence number

Returns

true if s1 is greater than s2, or false otherwise.

spdk_sn32_lt()

static bool spdk_sn32_lt ( uint32_t s1, uint32_t s2 )

inlinestatic

Compare if sequence number s1 is less than s2.

Parameters

s1	First sequence number
s2	Second sequence number

Returns

true if s1 is less than s2, or false otherwise.