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
dataBuffer to fill
data_sizeSize of the buffer
chFill byte
countNumber 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
s1First sequence number
s2Second 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
s1First sequence number
s2Second 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
s1First sequence number
s2Second sequence number
Returns
true if s1 is less than s2, or false otherwise.