C API

host.h File Reference


Detailed Description

This module provides functionalities to identify the host operating system, C compiler, and CPU architecture. It also provides a few features to abstract from such details.

See also:
http://predef.sourceforge.net/index.php

Host operating system

The module defines a symbol to identify the host operating system: VL_OS_WIN for Windows, VL_OS_LINUX for Linux, VL_OS_MACOSX for Mac OS X, and so on.

Host compiler

The module defines a symbol to identify the host compiler: VL_COMPILER_MSC for Microsoft Visual C++, VL_COMPILER_GNUC for GNU C, and so on. The (integer) value of such symbols corresponds the version of the compiler.

The module defines a symbol to identify the data model of the compiler: VL_COMPILER_ILP32, VL_COMPILER_LP32, or VL_COMPILER_LP64 (see Sect. Data models). For convenience, it also defines a number of atomic types of prescribed width (vl_int8, vl_int16, vl_int32, etc.).

Remarks:
While some of such functionalities are provided by the standard header stdint.h, the latter is not supported by all platforms.

Data models

The C language defines a number of atomic data types (such as char, short, int and so on). The number of bits (width) used to represent each data type depends on the compiler data model. The following table summarizes the relevant conventions:

Compiler data models. The table shows how many bits are allocated to each atomic data type according to each model.
Data model short int long long long void* Compiler
ILP32 16 32 32 64 32 common 32 bit architectures
LP64 16 32 64 64 64 UNIX-64 (Linux, Mac OS X)
ILP64 16 64 64 64 64 Alpha, Cray
SLIP64 64 64 64 64 64
LLP64 16 32 32 64 64 Windows-64

Other compiler-specific features

The module provides the macro VL_EXPORT to declare symbols exported from the library and the macro VL_INLINE to declare inline functions. Such features are not part of the C89 standard, and change depending on the compiler.

Example:
The following header file declares a function f that should be visible from outside the library.
 #include <vl/generic.h>
 VL_EXPORT void f () ;
 VL_EXPORT int i ;
Notice that the macro VL_EXPORT needs not to be included again when the function is defined.
Example:
The following header file declares an inline function f:
 #include <vl/generic.h>
 VL_INLINE int f() ;
 
 VL_INLINE int f() { return 1 ; }
Here the first instruction defines the function f, where the second declares it. Notice that since this is an inline function, its definition must be found in the header file rather than in an implementation file. Notice also that definition and declaration can be merged.
These macros translate according to the following tables:

Macros for exporting library symbols
Platform Macro name Value when building the library Value when importing the library
Unix/GCC VL_EXPORT empty (assumes -visibility=hidden GCC option) __attribute__((visibility ("default")))
Win/Visual C++ VL_EXPORT __declspec(dllexport) __declspec(dllimport)

Macros for declaring inline functions
Platform Macro name Value
Unix/GCC VL_INLINE static inline
Win/Visual C++ VL_INLINE static __inline

Host CPU architecture

The module defines a symbol to identify the host CPU architecture: VL_ARCH_IX86 for Intel x86, VL_ARCH_IA64 for Intel 64, and so on.

Endianness

The module defines a symbol to identify the host CPU endianness: VL_ARCH_BIG_ENDIAN for big endian and VL_ARCH_LITTLE_ENDIAN for little endian. The functions vl_swap_host_big_endianness_8(), vl_swap_host_big_endianness_4(), vl_swap_host_big_endianness_2() to change the endianness of data (from/to host and network order).

Recall that endianness concerns the way multi-byte data types (such as 16, 32 and 64 bits integers) are stored into the addressable memory. All CPUs uses a contiguous address range to store atomic data types (e.g. a 16-bit integer could be assigned to the addresses 0x10001 and 0x10002), but the order may differ.

  • The convention is big endian, or in network order, if the most significant byte of the multi-byte data types is assigned to the smaller memory address. This is the convention used for instance by the PPC architecture.

  • The convention is little endian if the least significant byte is assigned to the smaller memory address. This is the convention used for instance by the x86 architecture.

Remarks:
The names “big endian” and “little endian” are a little confusing. “Big endian” means “big endian first”, i.e. the address of the most significant byte comes first. Similarly, “little endian” means “little endian first”, in the sense that the address of the least significant byte comes first.
Endianness is a concern when data is either exchanged with processors that use different conventions, transmitted over a network, or stored to a file. For the latter two cases, one usually saves data in big endian (network) order regardless of the host CPU.

Author:
Andrea Vedaldi

Definition in file host.h.

Go to the source code of this file.


Atomic data types

#define VL_TRUE   1
 true (1) constant
#define VL_FALSE   0
 false (0) constant
typedef long long vl_int64
 Signed 64-bit integer.
typedef int vl_int32
 Signed 32-bit integer.
typedef short vl_int16
 Signed 16-bit integer.
typedef char vl_int8
 Signed 8-bit integer.
typedef long long unsigned vl_uint64
 Unsigned 64-bit integer.
typedef int unsigned vl_uint32
 Unsigned 32-bit integer.
typedef short unsigned vl_uint16
 Unsigned 16-bit integer.
typedef char unsigned vl_uint8
 Unsigned 8-bit integer.
typedef int vl_int
 Same as int.
typedef unsigned int vl_uint
 Same as unsigned int.
typedef int vl_bool
 Boolean.
typedef vl_int64 vl_intptr
 Integer holding a pointer.
typedef vl_uint64 vl_uintptr
 Unsigned integer holding a pointer.

Defines

Identifying the host operating system
#define VL_OS_LINUX   1
 Defined if the host operating system is Linux.
#define VL_OS_MACOSX   1
 Defined if the host operating system is Mac OS X.
#define VL_OS_WIN   1
 Defined if the host operating system is Windows (32 or 64).
#define VL_OS_WIN64   1
 Defined if the host operating system is Windows-64.
Identifying the host compiler
#define VL_COMPILER_GNUC
 Defined if the host compiler is GNU C.
#define VL_COMPILER_MSC   _MSC_VER
 Defined if the host compiler is Microsoft Visual C++.
#define VL_COMPILER_LCC   1
 Defined if the host compiler is GNU C.
Identifying the host CPU architecture
#define VL_ARCH_IX86   300
 Defined if the host CPU is of the Intel x86 family.
#define VL_ARCH_IA64
 Defined if the host CPU is of the Intel Architecture-64 family.
Identifying the host data model
#define VL_COMPILER_LLP64
 Defined if the host compiler data model is LLP64.
#define VL_COMPILER_LP64
 Defined if the host compiler data model is LP64.
#define VL_COMPILER_ILP32
 Defined if the host compiler data model is ILP32.
Identifying the host endianness
#define VL_ARCH_LITTLE_ENDIAN
 Defined if the host CPU is little endian.
#define VL_ARCH_BIG_ENDIAN
 Defined if the host CPU is big endian.
Printing the atomic data types
#define VL_FL_INT64   "I64"
 prinf length flag for vl_int64 and vl_uint64.
#define VL_FL_INT32   ""
 prinf length flag for vl_int32 and vl_uint32.
#define VL_FL_INT16   "h"
 prinf length flag for vl_int16 and vl_uint16.
#define VL_FL_INT8   "hh"
 prinf length flag for vl_int8 and vl_uint8.
Atomic data types limits
#define VL_BIG_INT   0x7FFFFFFFL
 Largest integer (math constant).
#define VL_SMALL_INT   (- VL_BIG_INT - 1)
 Smallest integer (math constant).
#define VL_BIG_UINT   0xFFFFFFFFUL
 Largest unsigned integer (math constant).

Functions

VL_EXPORT void vl_set_simd_enabled (vl_bool x)
 Enalbe/disable usage of SIMD instructions.
VL_EXPORT vl_bool vl_get_simd_enabled ()
 Are SIMD instructons enabled?
Endianness detection and conversion
VL_INLINE void vl_swap_host_big_endianness_8 (void *dst, void *src)
 Host <-> big endian transformation for 8-bytes value.
VL_INLINE void vl_swap_host_big_endianness_4 (void *dst, void *src)
 Host <-> big endian transformation for 4-bytes value.
VL_INLINE void vl_swap_host_big_endianness_2 (void *dst, void *src)
 Host <-> big endian transformation for 2-bytes value.
Obtaining host info at run time
VL_EXPORT void vl_print_host_info ()
 Print host information.
VL_EXPORT vl_bool vl_cpu_has_sse3 ()
 Check for SSE3 instruction set.
VL_EXPORT vl_bool vl_cpu_has_sse2 ()
 Check for SSE2 instruction set.

Define Documentation

#define VL_ARCH_BIG_ENDIAN

See also:
Endianness

Definition at line 126 of file host.h.

#define VL_ARCH_IA64

See also:
Host CPU architecture

Definition at line 86 of file host.h.

#define VL_ARCH_IX86   300

See also:
Host CPU architecture

Definition at line 69 of file host.h.

#define VL_ARCH_LITTLE_ENDIAN

See also:
Endianness

Definition at line 121 of file host.h.

#define VL_COMPILER_GNUC

Value:

(__GNUC__ * 10000 \
+ __GNUC_MINOR__ * 100)
This macro is defined if the compiler is GNUC. Its value is calculated as
 10000 * MAJOR + 100 * MINOR + PATCHLEVEL
See also:
Host compiler

Definition at line 48 of file host.h.

Referenced by vl_print_host_info().

#define VL_COMPILER_ILP32

See also:
Data models

Definition at line 111 of file host.h.

#define VL_COMPILER_LCC   1

This macro is defined if the compiler is GNUC. Its value is calculated as

 10000 * MAJOR + 100 * MINOR + PATCHLEVEL
See also:
Host compiler

Definition at line 59 of file host.h.

#define VL_COMPILER_LLP64

See also:
Data models

Definition at line 98 of file host.h.

#define VL_COMPILER_LP64

See also:
Data models

Definition at line 106 of file host.h.

#define VL_COMPILER_MSC   _MSC_VER

See also:
Host compiler

Definition at line 54 of file host.h.

Referenced by vl_print_host_info().


Function Documentation

VL_EXPORT vl_bool vl_cpu_has_sse2 (  ) 

Returns:
true if SSE2 is present.

Definition at line 433 of file host.c.

VL_EXPORT vl_bool vl_cpu_has_sse3 (  ) 

Returns:
true if SSE3 is present.

Definition at line 421 of file host.c.

VL_EXPORT vl_bool vl_get_simd_enabled (  ) 

Returns:
true is SIMD is enabled.

Definition at line 413 of file host.c.

Referenced by vl_print_host_info().

VL_EXPORT void vl_set_simd_enabled ( vl_bool  x  ) 

Parameters:
x set to true to enable SIMD instructions.
Notice that usage of SIMD instructions may be prevented due to lack of CPU support and data alignment issues.

See also:
vl_cpu_has_sse2(), vl_cpu_has_sse3(), etc.

Definition at line 405 of file host.c.

VL_INLINE void vl_swap_host_big_endianness_2 ( void *  dst,
void *  src 
)

Parameters:
dst destination 2-byte buffer.
src source 2-byte bufffer.
See also:
Endianness.

Definition at line 353 of file host.h.

VL_INLINE void vl_swap_host_big_endianness_4 ( void *  dst,
void *  src 
)

Parameters:
dst destination 4-byte buffer.
src source 4-byte bufffer.
See also:
Endianness.

Definition at line 327 of file host.h.

VL_INLINE void vl_swap_host_big_endianness_8 ( void *  dst,
void *  src 
)

Parameters:
dst destination 8-byte buffer.
src source 8-byte bufffer.
See also:
Endianness.

Definition at line 293 of file host.h.