[ViewVC] Diff of: cvs/cvsroot/libecb/ecb.pod

Comparing cvsroot/libecb/ecb.pod (file contents):
Revision 1.37 by sf-exg, Wed Aug 24 23:28:47 2011 UTC vs.
Revision 1.86 by root, Thu Apr 30 23:24:45 2020 UTC

…		…
10		10
11	Its homepage can be found here:	11	Its homepage can be found here:
12		12
13	http://software.schmorp.de/pkg/libecb	13	http://software.schmorp.de/pkg/libecb
14		14
15	It mainly provides a number of wrappers around GCC built-ins, together	15	It mainly provides a number of wrappers around many compiler built-ins,
16	with replacement functions for other compilers. In addition to this,	16	together with replacement functions for other compilers. In addition
17	it provides a number of other lowlevel C utilities, such as endianness	17	to this, it provides a number of other lowlevel C utilities, such as
18	detection, byte swapping or bit rotations.	18	endianness detection, byte swapping or bit rotations.
19		19
20	Or in other words, things that should be built into any standard C system,	20	Or in other words, things that should be built into any standard C
21	but aren't, implemented as efficient as possible with GCC, and still	21	system, but aren't, implemented as efficient as possible with GCC (clang,
22	correct with other compilers.	22	msvc...), and still correct with other compilers.
23		23
24	More might come.	24	More might come.
25		25
26	=head2 ABOUT THE HEADER	26	=head2 ABOUT THE HEADER
27		27
…		…
54	only a generic name is used (C<expr>, C<cond>, C<value> and so on), then	54	only a generic name is used (C<expr>, C<cond>, C<value> and so on), then
55	the corresponding function relies on C to implement the correct types, and	55	the corresponding function relies on C to implement the correct types, and
56	is usually implemented as a macro. Specifically, a "bool" in this manual	56	is usually implemented as a macro. Specifically, a "bool" in this manual
57	refers to any kind of boolean value, not a specific type.	57	refers to any kind of boolean value, not a specific type.
58		58
		59	=head2 TYPES / TYPE SUPPORT
		60
		61	ecb.h makes sure that the following types are defined (in the expected way):
		62
		63	int8_t uint8_
		64	int16_t uint16_t
		65	int32_t uint32_
		66	int64_t uint64_t
		67	int_fast8_t uint_fast8_t
		68	int_fast16_t uint_fast16_t
		69	int_fast32_t uint_fast32_t
		70	int_fast64_t uint_fast64_t
		71	intptr_t uintptr_t
		72
		73	The macro C<ECB_PTRSIZE> is defined to the size of a pointer on this
		74	platform (currently C<4> or C<8>) and can be used in preprocessor
		75	expressions.
		76
		77	For C<ptrdiff_t> and C<size_t> use C<stddef.h>/C<cstddef>.
		78
		79	=head2 LANGUAGE/ENVIRONMENT/COMPILER VERSIONS
		80
		81	All the following symbols expand to an expression that can be tested in
		82	preprocessor instructions as well as treated as a boolean (use C<!!> to
		83	ensure it's either C<0> or C<1> if you need that).
		84
		85	=over 4
		86
		87	=item ECB_C
		88
		89	True if the implementation defines the C<__STDC__> macro to a true value,
		90	while not claiming to be C++, i..e C, but not C++.
		91
		92	=item ECB_C99
		93
		94	True if the implementation claims to be compliant to C99 (ISO/IEC
		95	9899:1999) or any later version, while not claiming to be C++.
		96
		97	Note that later versions (ECB_C11) remove core features again (for
		98	example, variable length arrays).
		99
		100	=item ECB_C11, ECB_C17
		101
		102	True if the implementation claims to be compliant to C11/C17 (ISO/IEC
		103	9899:2011, :20187) or any later version, while not claiming to be C++.
		104
		105	=item ECB_CPP
		106
		107	True if the implementation defines the C<__cplusplus__> macro to a true
		108	value, which is typically true for C++ compilers.
		109
		110	=item ECB_CPP11, ECB_CPP14, ECB_CPP17
		111
		112	True if the implementation claims to be compliant to C++11/C++14/C++17
		113	(ISO/IEC 14882:2011, :2014, :2017) or any later version.
		114
		115	Note that many C++20 features will likely have their own feature test
		116	macros (see e.g. L<http://eel.is/c++draft/cpp.predefined#1.8>).
		117
		118	=item ECB_OPTIMIZE_SIZE
		119
		120	Is C<1> when the compiler optimizes for size, C<0> otherwise. This symbol
		121	can also be defined before including F<ecb.h>, in which case it will be
		122	unchanged.
		123
		124	=item ECB_GCC_VERSION (major, minor)
		125
		126	Expands to a true value (suitable for testing by the preprocessor) if the
		127	compiler used is GNU C and the version is the given version, or higher.
		128
		129	This macro tries to return false on compilers that claim to be GCC
		130	compatible but aren't.
		131
		132	=item ECB_EXTERN_C
		133
		134	Expands to C<extern "C"> in C++, and a simple C<extern> in C.
		135
		136	This can be used to declare a single external C function:
		137
		138	ECB_EXTERN_C int printf (const char *format, ...);
		139
		140	=item ECB_EXTERN_C_BEG / ECB_EXTERN_C_END
		141
		142	These two macros can be used to wrap multiple C<extern "C"> definitions -
		143	they expand to nothing in C.
		144
		145	They are most useful in header files:
		146
		147	ECB_EXTERN_C_BEG
		148
		149	int mycfun1 (int x);
		150	int mycfun2 (int x);
		151
		152	ECB_EXTERN_C_END
		153
		154	=item ECB_STDFP
		155
		156	If this evaluates to a true value (suitable for testing by the
		157	preprocessor), then C<float> and C<double> use IEEE 754 single/binary32
		158	and double/binary64 representations internally I<and> the endianness of
		159	both types match the endianness of C<uint32_t> and C<uint64_t>.
		160
		161	This means you can just copy the bits of a C<float> (or C<double>) to an
		162	C<uint32_t> (or C<uint64_t>) and get the raw IEEE 754 bit representation
		163	without having to think about format or endianness.
		164
		165	This is true for basically all modern platforms, although F<ecb.h> might
		166	not be able to deduce this correctly everywhere and might err on the safe
		167	side.
		168
		169	=item ECB_AMD64, ECB_AMD64_X32
		170
		171	These two macros are defined to C<1> on the x86_64/amd64 ABI and the X32
		172	ABI, respectively, and undefined elsewhere.
		173
		174	The designers of the new X32 ABI for some inexplicable reason decided to
		175	make it look exactly like amd64, even though it's completely incompatible
		176	to that ABI, breaking about every piece of software that assumed that
		177	C<__x86_64> stands for, well, the x86-64 ABI, making these macros
		178	necessary.
		179
		180	=back
		181
		182	=head2 MACRO TRICKERY
		183
		184	=over 4
		185
		186	=item ECB_CONCAT (a, b)
		187
		188	Expands any macros in C<a> and C<b>, then concatenates the result to form
		189	a single token. This is mainly useful to form identifiers from components,
		190	e.g.:
		191
		192	#define S1 str
		193	#define S2 cpy
		194
		195	ECB_CONCAT (S1, S2)(dst, src); // == strcpy (dst, src);
		196
		197	=item ECB_STRINGIFY (arg)
		198
		199	Expands any macros in C<arg> and returns the stringified version of
		200	it. This is mainly useful to get the contents of a macro in string form,
		201	e.g.:
		202
		203	#define SQL_LIMIT 100
		204	sql_exec ("select * from table limit " ECB_STRINGIFY (SQL_LIMIT));
		205
		206	=item ECB_STRINGIFY_EXPR (expr)
		207
		208	Like C<ECB_STRINGIFY>, but additionally evaluates C<expr> to make sure it
		209	is a valid expression. This is useful to catch typos or cases where the
		210	macro isn't available:
		211
		212	#include <errno.h>
		213
		214	ECB_STRINGIFY (EDOM); // "33" (on my system at least)
		215	ECB_STRINGIFY_EXPR (EDOM); // "33"
		216
		217	// now imagine we had a typo:
		218
		219	ECB_STRINGIFY (EDAM); // "EDAM"
		220	ECB_STRINGIFY_EXPR (EDAM); // error: EDAM undefined
		221
		222	=back
		223
59	=head2 GCC ATTRIBUTES	224	=head2 ATTRIBUTES
60		225
61	A major part of libecb deals with GCC attributes. These are additional	226	A major part of libecb deals with additional attributes that can be
62	attributes that you can assign to functions, variables and sometimes even	227	assigned to functions, variables and sometimes even types - much like
63	types - much like C<const> or C<volatile> in C.	228	C<const> or C<volatile> in C. They are implemented using either GCC
64		229	attributes or other compiler/language specific features. Attributes
65	While GCC allows declarations to show up in many surprising places,
66	but not in many expected places, the safest way is to put attribute
67	declarations before the whole declaration:	230	declarations must be put before the whole declaration:
68		231
69	ecb_const int mysqrt (int a);	232	ecb_const int mysqrt (int a);
70	ecb_unused int i;	233	ecb_unused int i;
71		234
72	For variables, it is often nicer to put the attribute after the name, and
73	avoid multiple declarations using commas:
74
75	int i ecb_unused;
76
77	=over 4	235	=over 4
78
79	=item ecb_attribute ((attrs...))
80
81	A simple wrapper that expands to C<__attribute__((attrs))> on GCC, and to
82	nothing on other compilers, so the effect is that only GCC sees these.
83
84	Example: use the C<deprecated> attribute on a function.
85
86	ecb_attribute((__deprecated__)) void
87	do_not_use_me_anymore (void);
88		236
89	=item ecb_unused	237	=item ecb_unused
90		238
91	Marks a function or a variable as "unused", which simply suppresses a	239	Marks a function or a variable as "unused", which simply suppresses a
92	warning by GCC when it detects it as unused. This is useful when you e.g.	240	warning by the compiler when it detects it as unused. This is useful when
93	declare a variable but do not always use it:	241	you e.g. declare a variable but do not always use it:
94		242
95	{	243	{
96	int var ecb_unused;	244	ecb_unused int var;
97		245
98	#ifdef SOMECONDITION	246	#ifdef SOMECONDITION
99	var = ...;	247	var = ...;
100	return var;	248	return var;
101	#else	249	#else
102	return 0;	250	return 0;
103	#endif	251	#endif
104	}	252	}
105		253
		254	=item ecb_deprecated
		255
		256	Similar to C<ecb_unused>, but marks a function, variable or type as
		257	deprecated. This makes some compilers warn when the type is used.
		258
		259	=item ecb_deprecated_message (message)
		260
		261	Same as C<ecb_deprecated>, but if possible, the specified diagnostic is
		262	used instead of a generic depreciation message when the object is being
		263	used.
		264
106	=item ecb_inline	265	=item ecb_inline
107		266
108	This is not actually an attribute, but you use it like one. It expands	267	Expands either to (a compiler-specific equivalent of) C<static inline> or
109	either to C<static inline> or to just C<static>, if inline isn't	268	to just C<static>, if inline isn't supported. It should be used to declare
110	supported. It should be used to declare functions that should be inlined,	269	functions that should be inlined, for code size or speed reasons.
111	for code size or speed reasons.
112		270
113	Example: inline this function, it surely will reduce codesize.	271	Example: inline this function, it surely will reduce codesize.
114		272
115	ecb_inline int	273	ecb_inline int
116	negmul (int a, int b)	274	negmul (int a, int b)
…		…
118	return - (a * b);	276	return - (a * b);
119	}	277	}
120		278
121	=item ecb_noinline	279	=item ecb_noinline
122		280
123	Prevent a function from being inlined - it might be optimised away, but	281	Prevents a function from being inlined - it might be optimised away, but
124	not inlined into other functions. This is useful if you know your function	282	not inlined into other functions. This is useful if you know your function
125	is rarely called and large enough for inlining not to be helpful.	283	is rarely called and large enough for inlining not to be helpful.
126		284
127	=item ecb_noreturn	285	=item ecb_noreturn
128		286
…		…
138	}	296	}
139		297
140	In this case, the compiler would probably be smart enough to deduce it on	298	In this case, the compiler would probably be smart enough to deduce it on
141	its own, so this is mainly useful for declarations.	299	its own, so this is mainly useful for declarations.
142		300
		301	=item ecb_restrict
		302
		303	Expands to the C<restrict> keyword or equivalent on compilers that support
		304	them, and to nothing on others. Must be specified on a pointer type or
		305	an array index to indicate that the memory doesn't alias with any other
		306	restricted pointer in the same scope.
		307
		308	Example: multiply a vector, and allow the compiler to parallelise the
		309	loop, because it knows it doesn't overwrite input values.
		310
		311	void
		312	multiply (ecb_restrict float *src,
		313	ecb_restrict float *dst,
		314	int len, float factor)
		315	{
		316	int i;
		317
		318	for (i = 0; i < len; ++i)
		319	dst [i] = src [i] * factor;
		320	}
		321
143	=item ecb_const	322	=item ecb_const
144		323
145	Declares that the function only depends on the values of its arguments,	324	Declares that the function only depends on the values of its arguments,
146	much like a mathematical function. It specifically does not read or write	325	much like a mathematical function. It specifically does not read or write
147	any memory any arguments might point to, global variables, or call any	326	any memory any arguments might point to, global variables, or call any
…		…
207	functions only called in exceptional or rare cases.	386	functions only called in exceptional or rare cases.
208		387
209	=item ecb_artificial	388	=item ecb_artificial
210		389
211	Declares the function as "artificial", in this case meaning that this	390	Declares the function as "artificial", in this case meaning that this
212	function is not really mean to be a function, but more like an accessor	391	function is not really meant to be a function, but more like an accessor
213	- many methods in C++ classes are mere accessor functions, and having a	392	- many methods in C++ classes are mere accessor functions, and having a
214	crash reported in such a method, or single-stepping through them, is not	393	crash reported in such a method, or single-stepping through them, is not
215	usually so helpful, especially when it's inlined to just a few instructions.	394	usually so helpful, especially when it's inlined to just a few instructions.
216		395
217	Marking them as artificial will instruct the debugger about just this,	396	Marking them as artificial will instruct the debugger about just this,
…		…
237		416
238	=head2 OPTIMISATION HINTS	417	=head2 OPTIMISATION HINTS
239		418
240	=over 4	419	=over 4
241		420
242	=item bool ecb_is_constant(expr)	421	=item bool ecb_is_constant (expr)
243		422
244	Returns true iff the expression can be deduced to be a compile-time	423	Returns true iff the expression can be deduced to be a compile-time
245	constant, and false otherwise.	424	constant, and false otherwise.
246		425
247	For example, when you have a C<rndm16> function that returns a 16 bit	426	For example, when you have a C<rndm16> function that returns a 16 bit
…		…
265	return is_constant (n) && !(n & (n - 1))	444	return is_constant (n) && !(n & (n - 1))
266	? rndm16 () & (num - 1)	445	? rndm16 () & (num - 1)
267	: (n * (uint32_t)rndm16 ()) >> 16;	446	: (n * (uint32_t)rndm16 ()) >> 16;
268	}	447	}
269		448
270	=item bool ecb_expect (expr, value)	449	=item ecb_expect (expr, value)
271		450
272	Evaluates C<expr> and returns it. In addition, it tells the compiler that	451	Evaluates C<expr> and returns it. In addition, it tells the compiler that
273	the C<expr> evaluates to C<value> a lot, which can be used for static	452	the C<expr> evaluates to C<value> a lot, which can be used for static
274	branch optimisations.	453	branch optimisations.
275		454
…		…
322	{	501	{
323	if (ecb_expect_false (current + size > end))	502	if (ecb_expect_false (current + size > end))
324	real_reserve_method (size); /* presumably noinline */	503	real_reserve_method (size); /* presumably noinline */
325	}	504	}
326		505
327	=item bool ecb_assume (cond)	506	=item ecb_assume (cond)
328		507
329	Try to tell the compiler that some condition is true, even if it's not	508	Tries to tell the compiler that some condition is true, even if it's not
330	obvious.	509	obvious. This is not a function, but a statement: it cannot be used in
		510	another expression.
331		511
332	This can be used to teach the compiler about invariants or other	512	This can be used to teach the compiler about invariants or other
333	conditions that might improve code generation, but which are impossible to	513	conditions that might improve code generation, but which are impossible to
334	deduce form the code itself.	514	deduce form the code itself.
335		515
…		…
352		532
353	Then the compiler I<might> be able to optimise out the second call	533	Then the compiler I<might> be able to optimise out the second call
354	completely, as it knows that C<< current + 1 > end >> is false and the	534	completely, as it knows that C<< current + 1 > end >> is false and the
355	call will never be executed.	535	call will never be executed.
356		536
357	=item bool ecb_unreachable ()	537	=item ecb_unreachable ()
358		538
359	This function does nothing itself, except tell the compiler that it will	539	This function does nothing itself, except tell the compiler that it will
360	never be executed. Apart from suppressing a warning in some cases, this	540	never be executed. Apart from suppressing a warning in some cases, this
361	function can be used to implement C<ecb_assume> or similar functions.	541	function can be used to implement C<ecb_assume> or similar functionality.
362		542
363	=item bool ecb_prefetch (addr, rw, locality)	543	=item ecb_prefetch (addr, rw, locality)
364		544
365	Tells the compiler to try to prefetch memory at the given C<addr>ess	545	Tells the compiler to try to prefetch memory at the given C<addr>ess
366	for either reading (C<rw> = 0) or writing (C<rw> = 1). A C<locality> of	546	for either reading (C<rw> = 0) or writing (C<rw> = 1). A C<locality> of
367	C<0> means that there will only be one access later, C<3> means that	547	C<0> means that there will only be one access later, C<3> means that
368	the data will likely be accessed very often, and values in between mean	548	the data will likely be accessed very often, and values in between mean
369	something... in between. The memory pointed to by the address does not	549	something... in between. The memory pointed to by the address does not
370	need to be accessible (it could be a null pointer for example), but C<rw>	550	need to be accessible (it could be a null pointer for example), but C<rw>
371	and C<locality> must be compile-time constants.	551	and C<locality> must be compile-time constants.
372		552
		553	This is a statement, not a function: you cannot use it as part of an
		554	expression.
		555
373	An obvious way to use this is to prefetch some data far away, in a big	556	An obvious way to use this is to prefetch some data far away, in a big
374	array you loop over. This prefetches memory some 128 array elements later,	557	array you loop over. This prefetches memory some 128 array elements later,
375	in the hope that it will be ready when the CPU arrives at that location.	558	in the hope that it will be ready when the CPU arrives at that location.
376		559
377	int sum = 0;	560	int sum = 0;
…		…
414		597
415	=item int ecb_ctz32 (uint32_t x)	598	=item int ecb_ctz32 (uint32_t x)
416		599
417	=item int ecb_ctz64 (uint64_t x)	600	=item int ecb_ctz64 (uint64_t x)
418		601
		602	=item int ecb_ctz (T x) [C++]
		603
419	Returns the index of the least significant bit set in C<x> (or	604	Returns the index of the least significant bit set in C<x> (or
420	equivalently the number of bits set to 0 before the least significant bit	605	equivalently the number of bits set to 0 before the least significant bit
421	set), starting from 0. If C<x> is 0 the result is undefined.	606	set), starting from 0. If C<x> is 0 the result is undefined.
422		607
423	For smaller types than C<uint32_t> you can safely use C<ecb_ctz32>.	608	For smaller types than C<uint32_t> you can safely use C<ecb_ctz32>.
424		609
		610	The overloaded C++ C<ecb_ctz> function supports C<uint8_t>, C<uint16_t>,
		611	C<uint32_t> and C<uint64_t> types.
		612
425	For example:	613	For example:
426		614
427	ecb_ctz32 (3) = 0	615	ecb_ctz32 (3) = 0
428	ecb_ctz32 (6) = 1	616	ecb_ctz32 (6) = 1
429		617
		618	=item bool ecb_is_pot32 (uint32_t x)
		619
		620	=item bool ecb_is_pot64 (uint32_t x)
		621
		622	=item bool ecb_is_pot (T x) [C++]
		623
		624	Returns true iff C<x> is a power of two or C<x == 0>.
		625
		626	For smaller types than C<uint32_t> you can safely use C<ecb_is_pot32>.
		627
		628	The overloaded C++ C<ecb_is_pot> function supports C<uint8_t>, C<uint16_t>,
		629	C<uint32_t> and C<uint64_t> types.
		630
430	=item int ecb_ld32 (uint32_t x)	631	=item int ecb_ld32 (uint32_t x)
431		632
432	=item int ecb_ld64 (uint64_t x)	633	=item int ecb_ld64 (uint64_t x)
		634
		635	=item int ecb_ld64 (T x) [C++]
433		636
434	Returns the index of the most significant bit set in C<x>, or the number	637	Returns the index of the most significant bit set in C<x>, or the number
435	of digits the number requires in binary (so that C<< 2**ld <= x <	638	of digits the number requires in binary (so that C<< 2**ld <= x <
436	2**(ld+1) >>). If C<x> is 0 the result is undefined. A common use case is	639	2**(ld+1) >>). If C<x> is 0 the result is undefined. A common use case is
437	to compute the integer binary logarithm, i.e. C<floor (log2 (n))>, for	640	to compute the integer binary logarithm, i.e. C<floor (log2 (n))>, for
…		…
442	the given data type), while C<ecb_ld> returns how many bits the number	645	the given data type), while C<ecb_ld> returns how many bits the number
443	itself requires.	646	itself requires.
444		647
445	For smaller types than C<uint32_t> you can safely use C<ecb_ld32>.	648	For smaller types than C<uint32_t> you can safely use C<ecb_ld32>.
446		649
		650	The overloaded C++ C<ecb_ld> function supports C<uint8_t>, C<uint16_t>,
		651	C<uint32_t> and C<uint64_t> types.
		652
447	=item int ecb_popcount32 (uint32_t x)	653	=item int ecb_popcount32 (uint32_t x)
448		654
449	=item int ecb_popcount64 (uint64_t x)	655	=item int ecb_popcount64 (uint64_t x)
450		656
		657	=item int ecb_popcount (T x) [C++]
		658
451	Returns the number of bits set to 1 in C<x>.	659	Returns the number of bits set to 1 in C<x>.
452		660
453	For smaller types than C<uint32_t> you can safely use C<ecb_popcount32>.	661	For smaller types than C<uint32_t> you can safely use C<ecb_popcount32>.
		662
		663	The overloaded C++ C<ecb_popcount> function supports C<uint8_t>, C<uint16_t>,
		664	C<uint32_t> and C<uint64_t> types.
454		665
455	For example:	666	For example:
456		667
457	ecb_popcount32 (7) = 3	668	ecb_popcount32 (7) = 3
458	ecb_popcount32 (255) = 8	669	ecb_popcount32 (255) = 8
459		670
		671	=item uint8_t ecb_bitrev8 (uint8_t x)
		672
		673	=item uint16_t ecb_bitrev16 (uint16_t x)
		674
		675	=item uint32_t ecb_bitrev32 (uint32_t x)
		676
		677	=item T ecb_bitrev (T x) [C++]
		678
		679	Reverses the bits in x, i.e. the MSB becomes the LSB, MSB-1 becomes LSB+1
		680	and so on.
		681
		682	The overloaded C++ C<ecb_bitrev> function supports C<uint8_t>, C<uint16_t> and C<uint32_t> types.
		683
		684	Example:
		685
		686	ecb_bitrev8 (0xa7) = 0xea
		687	ecb_bitrev32 (0xffcc4411) = 0x882233ff
		688
		689	=item T ecb_bitrev (T x) [C++]
		690
		691	Overloaded C++ bitrev function.
		692
		693	C<T> must be one of C<uint8_t>, C<uint16_t> or C<uint32_t>.
		694
460	=item uint32_t ecb_bswap16 (uint32_t x)	695	=item uint32_t ecb_bswap16 (uint32_t x)
461		696
462	=item uint32_t ecb_bswap32 (uint32_t x)	697	=item uint32_t ecb_bswap32 (uint32_t x)
463		698
464	=item uint64_t ecb_bswap64 (uint64_t x)	699	=item uint64_t ecb_bswap64 (uint64_t x)
		700
		701	=item T ecb_bswap (T x)
465		702
466	These functions return the value of the 16-bit (32-bit, 64-bit) value	703	These functions return the value of the 16-bit (32-bit, 64-bit) value
467	C<x> after reversing the order of bytes (0x11223344 becomes 0x44332211 in	704	C<x> after reversing the order of bytes (0x11223344 becomes 0x44332211 in
468	C<ecb_bswap32>).	705	C<ecb_bswap32>).
469		706
		707	The overloaded C++ C<ecb_bswap> function supports C<uint8_t>, C<uint16_t>,
		708	C<uint32_t> and C<uint64_t> types.
		709
470	=item uint8_t ecb_rotl8 (uint8_t x, unsigned int count)	710	=item uint8_t ecb_rotl8 (uint8_t x, unsigned int count)
471		711
472	=item uint16_t ecb_rotl16 (uint16_t x, unsigned int count)	712	=item uint16_t ecb_rotl16 (uint16_t x, unsigned int count)
473		713
474	=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)	714	=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)
…		…
485		725
486	These two families of functions return the value of C<x> after rotating	726	These two families of functions return the value of C<x> after rotating
487	all the bits by C<count> positions to the right (C<ecb_rotr>) or left	727	all the bits by C<count> positions to the right (C<ecb_rotr>) or left
488	(C<ecb_rotl>).	728	(C<ecb_rotl>).
489		729
490	Current GCC versions understand these functions and usually compile them	730	Current GCC/clang versions understand these functions and usually compile
491	to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on	731	them to "optimal" code (e.g. a single C<rol> or a combination of C<shld>
492	x86).	732	on x86).
		733
		734	=item T ecb_rotl (T x, unsigned int count) [C++]
		735
		736	=item T ecb_rotr (T x, unsigned int count) [C++]
		737
		738	Overloaded C++ rotl/rotr functions.
		739
		740	C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>.
		741
		742	=back
		743
		744	=head2 HOST ENDIANNESS CONVERSION
		745
		746	=over 4
		747
		748	=item uint_fast16_t ecb_be_u16_to_host (uint_fast16_t v)
		749
		750	=item uint_fast32_t ecb_be_u32_to_host (uint_fast32_t v)
		751
		752	=item uint_fast64_t ecb_be_u64_to_host (uint_fast64_t v)
		753
		754	=item uint_fast16_t ecb_le_u16_to_host (uint_fast16_t v)
		755
		756	=item uint_fast32_t ecb_le_u32_to_host (uint_fast32_t v)
		757
		758	=item uint_fast64_t ecb_le_u64_to_host (uint_fast64_t v)
		759
		760	Convert an unsigned 16, 32 or 64 bit value from big or little endian to host byte order.
		761
		762	The naming convention is C<ecb_>(C<be>\|C<le>)C<_u>C<16\|32\|64>C<_to_host>,
		763	where C<be> and C<le> stand for big endian and little endian, respectively.
		764
		765	=item uint_fast16_t ecb_host_to_be_u16 (uint_fast16_t v)
		766
		767	=item uint_fast32_t ecb_host_to_be_u32 (uint_fast32_t v)
		768
		769	=item uint_fast64_t ecb_host_to_be_u64 (uint_fast64_t v)
		770
		771	=item uint_fast16_t ecb_host_to_le_u16 (uint_fast16_t v)
		772
		773	=item uint_fast32_t ecb_host_to_le_u32 (uint_fast32_t v)
		774
		775	=item uint_fast64_t ecb_host_to_le_u64 (uint_fast64_t v)
		776
		777	Like above, but converts I<from> host byte order to the specified
		778	endianness.
		779
		780	=back
		781
		782	In C++ the following additional template functions are supported:
		783
		784	=over 4
		785
		786	=item T ecb_be_to_host (T v)
		787
		788	=item T ecb_le_to_host (T v)
		789
		790	=item T ecb_host_to_be (T v)
		791
		792	=item T ecb_host_to_le (T v)
		793
		794	=back
		795
		796	These functions work like their C counterparts, above, but use templates,
		797	which make them useful in generic code.
		798
		799	C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>
		800	(so unlike their C counterparts, there is a version for C<uint8_t>, which
		801	again can be useful in generic code).
		802
		803	=head2 UNALIGNED LOAD/STORE
		804
		805	These function load or store unaligned multi-byte values.
		806
		807	=over 4
		808
		809	=item uint_fast16_t ecb_peek_u16_u (const void *ptr)
		810
		811	=item uint_fast32_t ecb_peek_u32_u (const void *ptr)
		812
		813	=item uint_fast64_t ecb_peek_u64_u (const void *ptr)
		814
		815	These functions load an unaligned, unsigned 16, 32 or 64 bit value from
		816	memory.
		817
		818	=item uint_fast16_t ecb_peek_be_u16_u (const void *ptr)
		819
		820	=item uint_fast32_t ecb_peek_be_u32_u (const void *ptr)
		821
		822	=item uint_fast64_t ecb_peek_be_u64_u (const void *ptr)
		823
		824	=item uint_fast16_t ecb_peek_le_u16_u (const void *ptr)
		825
		826	=item uint_fast32_t ecb_peek_le_u32_u (const void *ptr)
		827
		828	=item uint_fast64_t ecb_peek_le_u64_u (const void *ptr)
		829
		830	Like above, but additionally convert from big endian (C<be>) or little
		831	endian (C<le>) byte order to host byte order while doing so.
		832
		833	=item ecb_poke_u16_u (void *ptr, uint16_t v)
		834
		835	=item ecb_poke_u32_u (void *ptr, uint32_t v)
		836
		837	=item ecb_poke_u64_u (void *ptr, uint64_t v)
		838
		839	These functions store an unaligned, unsigned 16, 32 or 64 bit value to
		840	memory.
		841
		842	=item ecb_poke_be_u16_u (void *ptr, uint_fast16_t v)
		843
		844	=item ecb_poke_be_u32_u (void *ptr, uint_fast32_t v)
		845
		846	=item ecb_poke_be_u64_u (void *ptr, uint_fast64_t v)
		847
		848	=item ecb_poke_le_u16_u (void *ptr, uint_fast16_t v)
		849
		850	=item ecb_poke_le_u32_u (void *ptr, uint_fast32_t v)
		851
		852	=item ecb_poke_le_u64_u (void *ptr, uint_fast64_t v)
		853
		854	Like above, but additionally convert from host byte order to big endian
		855	(C<be>) or little endian (C<le>) byte order while doing so.
		856
		857	=back
		858
		859	In C++ the following additional template functions are supported:
		860
		861	=over 4
		862
		863	=item T ecb_peek<T> (const void *ptr)
		864
		865	=item T ecb_peek_be<T> (const void *ptr)
		866
		867	=item T ecb_peek_le<T> (const void *ptr)
		868
		869	=item T ecb_peek_u<T> (const void *ptr)
		870
		871	=item T ecb_peek_be_u<T> (const void *ptr)
		872
		873	=item T ecb_peek_le_u<T> (const void *ptr)
		874
		875	Similarly to their C counterparts, these functions load an unsigned 8, 16,
		876	32 or 64 bit value from memory, with optional conversion from big/little
		877	endian.
		878
		879	Since the type cannot be deduced, it has to be specified explicitly, e.g.
		880
		881	uint_fast16_t v = ecb_peek<uint16_t> (ptr);
		882
		883	C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>.
		884
		885	Unlike their C counterparts, these functions support 8 bit quantities
		886	(C<uint8_t>) and also have an aligned version (without the C<_u> prefix),
		887	all of which hopefully makes them more useful in generic code.
		888
		889	=item ecb_poke (void *ptr, T v)
		890
		891	=item ecb_poke_be (void *ptr, T v)
		892
		893	=item ecb_poke_le (void *ptr, T v)
		894
		895	=item ecb_poke_u (void *ptr, T v)
		896
		897	=item ecb_poke_be_u (void *ptr, T v)
		898
		899	=item ecb_poke_le_u (void *ptr, T v)
		900
		901	Again, similarly to their C counterparts, these functions store an
		902	unsigned 8, 16, 32 or z64 bit value to memory, with optional conversion to
		903	big/little endian.
		904
		905	C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>.
		906
		907	Unlike their C counterparts, these functions support 8 bit quantities
		908	(C<uint8_t>) and also have an aligned version (without the C<_u> prefix),
		909	all of which hopefully makes them more useful in generic code.
		910
		911	=back
		912
		913	=head2 FLOATING POINT FIDDLING
		914
		915	=over 4
		916
		917	=item ECB_INFINITY [-UECB_NO_LIBM]
		918
		919	Evaluates to positive infinity if supported by the platform, otherwise to
		920	a truly huge number.
		921
		922	=item ECB_NAN [-UECB_NO_LIBM]
		923
		924	Evaluates to a quiet NAN if supported by the platform, otherwise to
		925	C<ECB_INFINITY>.
		926
		927	=item float ecb_ldexpf (float x, int exp) [-UECB_NO_LIBM]
		928
		929	Same as C<ldexpf>, but always available.
		930
		931	=item uint32_t ecb_float_to_binary16 (float x) [-UECB_NO_LIBM]
		932
		933	=item uint32_t ecb_float_to_binary32 (float x) [-UECB_NO_LIBM]
		934
		935	=item uint64_t ecb_double_to_binary64 (double x) [-UECB_NO_LIBM]
		936
		937	These functions each take an argument in the native C<float> or C<double>
		938	type and return the IEEE 754 bit representation of it (binary16/half,
		939	binary32/single or binary64/double precision).
		940
		941	The bit representation is just as IEEE 754 defines it, i.e. the sign bit
		942	will be the most significant bit, followed by exponent and mantissa.
		943
		944	This function should work even when the native floating point format isn't
		945	IEEE compliant, of course at a speed and code size penalty, and of course
		946	also within reasonable limits (it tries to convert NaNs, infinities and
		947	denormals, but will likely convert negative zero to positive zero).
		948
		949	On all modern platforms (where C<ECB_STDFP> is true), the compiler should
		950	be able to optimise away this function completely.
		951
		952	These functions can be helpful when serialising floats to the network - you
		953	can serialise the return value like a normal uint16_t/uint32_t/uint64_t.
		954
		955	Another use for these functions is to manipulate floating point values
		956	directly.
		957
		958	Silly example: toggle the sign bit of a float.
		959
		960	/* On gcc-4.7 on amd64, */
		961	/* this results in a single add instruction to toggle the bit, and 4 extra */
		962	/* instructions to move the float value to an integer register and back. */
		963
		964	x = ecb_binary32_to_float (ecb_float_to_binary32 (x) ^ 0x80000000U)
		965
		966	=item float ecb_binary16_to_float (uint16_t x) [-UECB_NO_LIBM]
		967
		968	=item float ecb_binary32_to_float (uint32_t x) [-UECB_NO_LIBM]
		969
		970	=item double ecb_binary64_to_double (uint64_t x) [-UECB_NO_LIBM]
		971
		972	The reverse operation of the previous function - takes the bit
		973	representation of an IEEE binary16, binary32 or binary64 number (half,
		974	single or double precision) and converts it to the native C<float> or
		975	C<double> format.
		976
		977	This function should work even when the native floating point format isn't
		978	IEEE compliant, of course at a speed and code size penalty, and of course
		979	also within reasonable limits (it tries to convert normals and denormals,
		980	and might be lucky for infinities, and with extraordinary luck, also for
		981	negative zero).
		982
		983	On all modern platforms (where C<ECB_STDFP> is true), the compiler should
		984	be able to optimise away this function completely.
		985
		986	=item uint16_t ecb_binary32_to_binary16 (uint32_t x)
		987
		988	=item uint32_t ecb_binary16_to_binary32 (uint16_t x)
		989
		990	Convert a IEEE binary32/single precision to binary16/half format, and vice
		991	versa, handling all details (round-to-nearest-even, subnormals, infinity
		992	and NaNs) correctly.
		993
		994	These are functions are available under C<-DECB_NO_LIBM>, since
		995	they do not rely on the platform floating point format. The
		996	C<ecb_float_to_binary16> and C<ecb_binary16_to_float> functions are
		997	usually what you want.
493		998
494	=back	999	=back
495		1000
496	=head2 ARITHMETIC	1001	=head2 ARITHMETIC
497		1002
…		…
510	C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be	1015	C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be
511	negatable, that is, both C<m> and C<-m> must be representable in its	1016	negatable, that is, both C<m> and C<-m> must be representable in its
512	type (this typically excludes the minimum signed integer value, the same	1017	type (this typically excludes the minimum signed integer value, the same
513	limitation as for C</> and C<%> in C).	1018	limitation as for C</> and C<%> in C).
514		1019
515	Current GCC versions compile this into an efficient branchless sequence on	1020	Current GCC/clang versions compile this into an efficient branchless
516	almost all CPUs.	1021	sequence on almost all CPUs.
517		1022
518	For example, when you want to rotate forward through the members of an	1023	For example, when you want to rotate forward through the members of an
519	array for increasing C<m> (which might be negative), then you should use	1024	array for increasing C<m> (which might be negative), then you should use
520	C<ecb_mod>, as the C<%> operator might give either negative results, or	1025	C<ecb_mod>, as the C<%> operator might give either negative results, or
521	change direction for negative values:	1026	change direction for negative values:
…		…
527		1032
528	=item x = ecb_div_ru (val, div)	1033	=item x = ecb_div_ru (val, div)
529		1034
530	Returns C<val> divided by C<div> rounded down or up, respectively.	1035	Returns C<val> divided by C<div> rounded down or up, respectively.
531	C<val> and C<div> must have integer types and C<div> must be strictly	1036	C<val> and C<div> must have integer types and C<div> must be strictly
532	positive.	1037	positive. Note that these functions are implemented with macros in C
		1038	and with function templates in C++.
533		1039
534	=back	1040	=back
535		1041
536	=head2 UTILITY	1042	=head2 UTILITY
537		1043
…		…
547	for (i = 0; i < ecb_array_length (primes); i++)	1053	for (i = 0; i < ecb_array_length (primes); i++)
548	sum += primes [i];	1054	sum += primes [i];
549		1055
550	=back	1056	=back
551		1057
		1058	=head2 SYMBOLS GOVERNING COMPILATION OF ECB.H ITSELF
552		1059
		1060	These symbols need to be defined before including F<ecb.h> the first time.
		1061
		1062	=over 4
		1063
		1064	=item ECB_NO_THREADS
		1065
		1066	If F<ecb.h> is never used from multiple threads, then this symbol can
		1067	be defined, in which case memory fences (and similar constructs) are
		1068	completely removed, leading to more efficient code and fewer dependencies.
		1069
		1070	Setting this symbol to a true value implies C<ECB_NO_SMP>.
		1071
		1072	=item ECB_NO_SMP
		1073
		1074	The weaker version of C<ECB_NO_THREADS> - if F<ecb.h> is used from
		1075	multiple threads, but never concurrently (e.g. if the system the program
		1076	runs on has only a single CPU with a single core, no hyperthreading and so
		1077	on), then this symbol can be defined, leading to more efficient code and
		1078	fewer dependencies.
		1079
		1080	=item ECB_NO_LIBM
		1081
		1082	When defined to C<1>, do not export any functions that might introduce
		1083	dependencies on the math library (usually called F<-lm>) - these are
		1084	marked with [-UECB_NO_LIBM].
		1085
		1086	=back
		1087
		1088	=head1 UNDOCUMENTED FUNCTIONALITY
		1089
		1090	F<ecb.h> is full of undocumented functionality as well, some of which is
		1091	intended to be internal-use only, some of which we forgot to document, and
		1092	some of which we hide because we are not sure we will keep the interface
		1093	stable.
		1094
		1095	While you are welcome to rummage around and use whatever you find useful
		1096	(we can't stop you), keep in mind that we will change undocumented
		1097	functionality in incompatible ways without thinking twice, while we are
		1098	considerably more conservative with documented things.
		1099
		1100	=head1 AUTHORS
		1101
		1102	C<libecb> is designed and maintained by:
		1103
		1104	Emanuele Giaquinta <e.giaquinta@glauco.it>
		1105	Marc Alexander Lehmann <schmorp@schmorp.de>
		1106
		1107

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing cvsroot/libecb/ecb.pod (file contents): Revision 1.37 by sf-exg, Wed Aug 24 23:28:47 2011 UTC vs. Revision 1.86 by root, Thu Apr 30 23:24:45 2020 UTC

Diff Legend

Comparing cvsroot/libecb/ecb.pod (file contents):
Revision 1.37 by sf-exg, Wed Aug 24 23:28:47 2011 UTC vs.
Revision 1.86 by root, Thu Apr 30 23:24:45 2020 UTC