Documentation>C API
Portability features

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 ;
  generic.h
  Generic (General support functionalities)
  VL_EXPORT
  #define VL_EXPORT
  Declares a DLL exported symbol.
  Definition: host.h:35
  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 ; }
  VL_INLINE
  #define VL_INLINE
  Adds appropriate inline function qualifier.
  Definition: host.h:36

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.