Documentation - C API
Portability features

Table of Contents

Author:
Andrea Vedaldi

Platform dependent details are isolated in the host.h. 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
http://en.wikipedia.org/wiki/64-bit_computing

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_LP64, or VL_COMPILER_LLP64 (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 different models are ILP32 (int, long, and pointer 32 bit), LP64 (int 32 bit, long and pointer 64 bit), ILP64 (int, long, and pointer 64 bit), and LLP64 (int, long 32 bit and pointer 64 – and long long – 64 bit). Note in particular that long long is 64 bit in all models of interest. The following table summarizes them:

Compiler data models.
Data model short int long long long void* Compiler
ILP32 16 32 32 64 32 Most 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

Macros such as VL_UINT32_C can be used to generate integer literal with the correct suffix for a type of a given width.

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.

Multi-threading

The file defines VL_THREADS_WIN if multi-threading support is enabled and the host supports Windows threads and VL_THREADS_POSIX if it supports POSIX threads.