rte_common.h revision 43192222
1/*-
2 *   BSD LICENSE
3 *
4 *   Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
5 *   All rights reserved.
6 *
7 *   Redistribution and use in source and binary forms, with or without
8 *   modification, are permitted provided that the following conditions
9 *   are met:
10 *
11 *     * Redistributions of source code must retain the above copyright
12 *       notice, this list of conditions and the following disclaimer.
13 *     * Redistributions in binary form must reproduce the above copyright
14 *       notice, this list of conditions and the following disclaimer in
15 *       the documentation and/or other materials provided with the
16 *       distribution.
17 *     * Neither the name of Intel Corporation nor the names of its
18 *       contributors may be used to endorse or promote products derived
19 *       from this software without specific prior written permission.
20 *
21 *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24 *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25 *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26 *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
27 *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28 *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29 *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30 *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31 *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32 */
33
34#ifndef _RTE_COMMON_H_
35#define _RTE_COMMON_H_
36
37/**
38 * @file
39 *
40 * Generic, commonly-used macro and inline function definitions
41 * for DPDK.
42 */
43
44#ifdef __cplusplus
45extern "C" {
46#endif
47
48#include <stdint.h>
49#include <stdlib.h>
50#include <ctype.h>
51#include <errno.h>
52#include <limits.h>
53
54#ifndef typeof
55#define typeof __typeof__
56#endif
57
58#ifndef asm
59#define asm __asm__
60#endif
61
62/** C extension macro for environments lacking C11 features. */
63#if !defined(__STDC_VERSION__) || __STDC_VERSION__ < 201112L
64#define RTE_STD_C11 __extension__
65#else
66#define RTE_STD_C11
67#endif
68
69#ifdef RTE_ARCH_STRICT_ALIGN
70typedef uint64_t unaligned_uint64_t __attribute__ ((aligned(1)));
71typedef uint32_t unaligned_uint32_t __attribute__ ((aligned(1)));
72typedef uint16_t unaligned_uint16_t __attribute__ ((aligned(1)));
73#else
74typedef uint64_t unaligned_uint64_t;
75typedef uint32_t unaligned_uint32_t;
76typedef uint16_t unaligned_uint16_t;
77#endif
78
79/**
80 * Force alignment
81 */
82#define __rte_aligned(a) __attribute__((__aligned__(a)))
83
84/**
85 * Force a structure to be packed
86 */
87#define __rte_packed __attribute__((__packed__))
88
89/******* Macro to mark functions and fields scheduled for removal *****/
90#define __rte_deprecated	__attribute__((__deprecated__))
91
92/*********** Macros to eliminate unused variable warnings ********/
93
94/**
95 * short definition to mark a function parameter unused
96 */
97#define __rte_unused __attribute__((__unused__))
98
99/**
100 * definition to mark a variable or function parameter as used so
101 * as to avoid a compiler warning
102 */
103#define RTE_SET_USED(x) (void)(x)
104
105/*********** Macros for pointer arithmetic ********/
106
107/**
108 * add a byte-value offset to a pointer
109 */
110#define RTE_PTR_ADD(ptr, x) ((void*)((uintptr_t)(ptr) + (x)))
111
112/**
113 * subtract a byte-value offset from a pointer
114 */
115#define RTE_PTR_SUB(ptr, x) ((void*)((uintptr_t)ptr - (x)))
116
117/**
118 * get the difference between two pointer values, i.e. how far apart
119 * in bytes are the locations they point two. It is assumed that
120 * ptr1 is greater than ptr2.
121 */
122#define RTE_PTR_DIFF(ptr1, ptr2) ((uintptr_t)(ptr1) - (uintptr_t)(ptr2))
123
124/*********** Macros/static functions for doing alignment ********/
125
126
127/**
128 * Macro to align a pointer to a given power-of-two. The resultant
129 * pointer will be a pointer of the same type as the first parameter, and
130 * point to an address no higher than the first parameter. Second parameter
131 * must be a power-of-two value.
132 */
133#define RTE_PTR_ALIGN_FLOOR(ptr, align) \
134	((typeof(ptr))RTE_ALIGN_FLOOR((uintptr_t)ptr, align))
135
136/**
137 * Macro to align a value to a given power-of-two. The resultant value
138 * will be of the same type as the first parameter, and will be no
139 * bigger than the first parameter. Second parameter must be a
140 * power-of-two value.
141 */
142#define RTE_ALIGN_FLOOR(val, align) \
143	(typeof(val))((val) & (~((typeof(val))((align) - 1))))
144
145/**
146 * Macro to align a pointer to a given power-of-two. The resultant
147 * pointer will be a pointer of the same type as the first parameter, and
148 * point to an address no lower than the first parameter. Second parameter
149 * must be a power-of-two value.
150 */
151#define RTE_PTR_ALIGN_CEIL(ptr, align) \
152	RTE_PTR_ALIGN_FLOOR((typeof(ptr))RTE_PTR_ADD(ptr, (align) - 1), align)
153
154/**
155 * Macro to align a value to a given power-of-two. The resultant value
156 * will be of the same type as the first parameter, and will be no lower
157 * than the first parameter. Second parameter must be a power-of-two
158 * value.
159 */
160#define RTE_ALIGN_CEIL(val, align) \
161	RTE_ALIGN_FLOOR(((val) + ((typeof(val)) (align) - 1)), align)
162
163/**
164 * Macro to align a pointer to a given power-of-two. The resultant
165 * pointer will be a pointer of the same type as the first parameter, and
166 * point to an address no lower than the first parameter. Second parameter
167 * must be a power-of-two value.
168 * This function is the same as RTE_PTR_ALIGN_CEIL
169 */
170#define RTE_PTR_ALIGN(ptr, align) RTE_PTR_ALIGN_CEIL(ptr, align)
171
172/**
173 * Macro to align a value to a given power-of-two. The resultant
174 * value will be of the same type as the first parameter, and
175 * will be no lower than the first parameter. Second parameter
176 * must be a power-of-two value.
177 * This function is the same as RTE_ALIGN_CEIL
178 */
179#define RTE_ALIGN(val, align) RTE_ALIGN_CEIL(val, align)
180
181/**
182 * Checks if a pointer is aligned to a given power-of-two value
183 *
184 * @param ptr
185 *   The pointer whose alignment is to be checked
186 * @param align
187 *   The power-of-two value to which the ptr should be aligned
188 *
189 * @return
190 *   True(1) where the pointer is correctly aligned, false(0) otherwise
191 */
192static inline int
193rte_is_aligned(void *ptr, unsigned align)
194{
195	return RTE_PTR_ALIGN(ptr, align) == ptr;
196}
197
198/*********** Macros for compile type checks ********/
199
200/**
201 * Triggers an error at compilation time if the condition is true.
202 */
203#ifndef __OPTIMIZE__
204#define RTE_BUILD_BUG_ON(condition) ((void)sizeof(char[1 - 2*!!(condition)]))
205#else
206extern int RTE_BUILD_BUG_ON_detected_error;
207#define RTE_BUILD_BUG_ON(condition) do {             \
208	((void)sizeof(char[1 - 2*!!(condition)]));   \
209	if (condition)                               \
210		RTE_BUILD_BUG_ON_detected_error = 1; \
211} while(0)
212#endif
213
214/*********** Macros to work with powers of 2 ********/
215
216/**
217 * Returns true if n is a power of 2
218 * @param n
219 *     Number to check
220 * @return 1 if true, 0 otherwise
221 */
222static inline int
223rte_is_power_of_2(uint32_t n)
224{
225	return n && !(n & (n - 1));
226}
227
228/**
229 * Aligns input parameter to the next power of 2
230 *
231 * @param x
232 *   The integer value to algin
233 *
234 * @return
235 *   Input parameter aligned to the next power of 2
236 */
237static inline uint32_t
238rte_align32pow2(uint32_t x)
239{
240	x--;
241	x |= x >> 1;
242	x |= x >> 2;
243	x |= x >> 4;
244	x |= x >> 8;
245	x |= x >> 16;
246
247	return x + 1;
248}
249
250/**
251 * Aligns 64b input parameter to the next power of 2
252 *
253 * @param v
254 *   The 64b value to align
255 *
256 * @return
257 *   Input parameter aligned to the next power of 2
258 */
259static inline uint64_t
260rte_align64pow2(uint64_t v)
261{
262	v--;
263	v |= v >> 1;
264	v |= v >> 2;
265	v |= v >> 4;
266	v |= v >> 8;
267	v |= v >> 16;
268	v |= v >> 32;
269
270	return v + 1;
271}
272
273/*********** Macros for calculating min and max **********/
274
275/**
276 * Macro to return the minimum of two numbers
277 */
278#define RTE_MIN(a, b) \
279	__extension__ ({ \
280		typeof (a) _a = (a); \
281		typeof (b) _b = (b); \
282		_a < _b ? _a : _b; \
283	})
284
285/**
286 * Macro to return the maximum of two numbers
287 */
288#define RTE_MAX(a, b) \
289	__extension__ ({ \
290		typeof (a) _a = (a); \
291		typeof (b) _b = (b); \
292		_a > _b ? _a : _b; \
293	})
294
295/*********** Other general functions / macros ********/
296
297#ifdef __SSE2__
298#include <emmintrin.h>
299/**
300 * PAUSE instruction for tight loops (avoid busy waiting)
301 */
302static inline void
303rte_pause (void)
304{
305	_mm_pause();
306}
307#else
308static inline void
309rte_pause(void) {}
310#endif
311
312/**
313 * Searches the input parameter for the least significant set bit
314 * (starting from zero).
315 * If a least significant 1 bit is found, its bit index is returned.
316 * If the content of the input parameter is zero, then the content of the return
317 * value is undefined.
318 * @param v
319 *     input parameter, should not be zero.
320 * @return
321 *     least significant set bit in the input parameter.
322 */
323static inline uint32_t
324rte_bsf32(uint32_t v)
325{
326	return (uint32_t)__builtin_ctz(v);
327}
328
329#ifndef offsetof
330/** Return the offset of a field in a structure. */
331#define offsetof(TYPE, MEMBER)  __builtin_offsetof (TYPE, MEMBER)
332#endif
333
334#define _RTE_STR(x) #x
335/** Take a macro value and get a string version of it */
336#define RTE_STR(x) _RTE_STR(x)
337
338/**
339 * ISO C helpers to modify format strings using variadic macros.
340 * This is a replacement for the ", ## __VA_ARGS__" GNU extension.
341 * An empty %s argument is appended to avoid a dangling comma.
342 */
343#define RTE_FMT(fmt, ...) fmt "%.0s", __VA_ARGS__ ""
344#define RTE_FMT_HEAD(fmt, ...) fmt
345#define RTE_FMT_TAIL(fmt, ...) __VA_ARGS__
346
347/** Mask value of type "tp" for the first "ln" bit set. */
348#define	RTE_LEN2MASK(ln, tp)	\
349	((tp)((uint64_t)-1 >> (sizeof(uint64_t) * CHAR_BIT - (ln))))
350
351/** Number of elements in the array. */
352#define	RTE_DIM(a)	(sizeof (a) / sizeof ((a)[0]))
353
354/**
355 * Converts a numeric string to the equivalent uint64_t value.
356 * As well as straight number conversion, also recognises the suffixes
357 * k, m and g for kilobytes, megabytes and gigabytes respectively.
358 *
359 * If a negative number is passed in  i.e. a string with the first non-black
360 * character being "-", zero is returned. Zero is also returned in the case of
361 * an error with the strtoull call in the function.
362 *
363 * @param str
364 *     String containing number to convert.
365 * @return
366 *     Number.
367 */
368static inline uint64_t
369rte_str_to_size(const char *str)
370{
371	char *endptr;
372	unsigned long long size;
373
374	while (isspace((int)*str))
375		str++;
376	if (*str == '-')
377		return 0;
378
379	errno = 0;
380	size = strtoull(str, &endptr, 0);
381	if (errno)
382		return 0;
383
384	if (*endptr == ' ')
385		endptr++; /* allow 1 space gap */
386
387	switch (*endptr){
388	case 'G': case 'g': size *= 1024; /* fall-through */
389	case 'M': case 'm': size *= 1024; /* fall-through */
390	case 'K': case 'k': size *= 1024; /* fall-through */
391	default:
392		break;
393	}
394	return size;
395}
396
397/**
398 * Function to terminate the application immediately, printing an error
399 * message and returning the exit_code back to the shell.
400 *
401 * This function never returns
402 *
403 * @param exit_code
404 *     The exit code to be returned by the application
405 * @param format
406 *     The format string to be used for printing the message. This can include
407 *     printf format characters which will be expanded using any further parameters
408 *     to the function.
409 */
410void
411rte_exit(int exit_code, const char *format, ...)
412	__attribute__((noreturn))
413	__attribute__((format(printf, 2, 3)));
414
415#ifdef __cplusplus
416}
417#endif
418
419#endif
420