# Compiler Definitions API

Source: https://sh4zam.com/api/cdefs/

> Preprocessor definitions: back-end and target detection, TLS model, utilities and aliasing types

This file contains commonly used preprocessor definitions used throughout the project: library-wide configuration defines, compiler detection, compiler attributes, the TLS model and conversion utilities. `SHZ_TARGET` is auto-detected from compiler macros, and `SHZ_BACKEND` selects the implementation: the SH4 back-end is chosen only when targeting SH4 in single-precision FPU mode, otherwise the portable software back-end is used. `SHZ_CONVERT()` performs a zero-cost conversion between layout-compatible types and is what the `_from()` and `_to()` adapters are built on. Upstream keeps the compiler attribute macros (`SHZ_INLINE`, `SHZ_FORCE_INLINE`, `SHZ_ALIGNAS`, ...) out of its reference; they appear here only when Doxygen exposes them.

- **C header:** `#include <sh4zam/shz_cdefs.h>`
- **C++ header:** `#include <sh4zam/shz_cdefs.hpp>`
- **Symbols:** 67

## Back-Ends

List of architectures which SH4ZAM can auto-detect.

| Symbol | Description |
| --- | --- |
| [`SHZ_SH4`](https://sh4zam.com/api/cdefs/SHZ_SH4/) | Back-end for the Dreamcast's SH4. |
| [`SHZ_PPC`](https://sh4zam.com/api/cdefs/SHZ_PPC/) | Back-end for the Gamecube/Wii's Gekko PPC. |
| [`SHZ_MIPS`](https://sh4zam.com/api/cdefs/SHZ_MIPS/) | Back-end for MIPS architectures. |
| [`SHZ_ARM`](https://sh4zam.com/api/cdefs/SHZ_ARM/) | Back-end for ARM architectures. |
| [`SHZ_X86_64`](https://sh4zam.com/api/cdefs/SHZ_X86_64/) | Back-end for x86_64 architectures. |
| [`SHZ_SPU`](https://sh4zam.com/api/cdefs/SHZ_SPU/) | Back-end for the Cell B/E SPU architecture. |
| [`SHZ_WASM`](https://sh4zam.com/api/cdefs/SHZ_WASM/) | Back-end for WebAssembly. |
| [`SHZ_SW`](https://sh4zam.com/api/cdefs/SHZ_SW/) | Generic C-based software back-end. |

## TLS Models

Defines for different mechanisms for thread-local storage.

| Symbol | Description |
| --- | --- |
| [`SHZ_TLS_DISABLED`](https://sh4zam.com/api/cdefs/SHZ_TLS_DISABLED/) | No thread-local variables. |
| [`SHZ_TLS_IMPLICIT`](https://sh4zam.com/api/cdefs/SHZ_TLS_IMPLICIT/) | Use `thread_local` keyword for TLS. |
| [`SHZ_TLS_PTHREAD`](https://sh4zam.com/api/cdefs/SHZ_TLS_PTHREAD/) | Use pthread unique keys for TLS. |
| [`SHZ_TLS_CTHREAD`](https://sh4zam.com/api/cdefs/SHZ_TLS_CTHREAD/) | Use C11 thread TSS keys for TLS. |

## Compiler Detection

Defines for identifying the detected compiler.

| Symbol | Description |
| --- | --- |
| [`SHZ_GNUC`](https://sh4zam.com/api/cdefs/SHZ_GNUC/) | Defined when building with a GCC-compatible compiler. |

## Utilities

Miscellaneous function-like macros

| Symbol | Description |
| --- | --- |
| [`SHZ_STRINGIFY_LITERAL`](https://sh4zam.com/api/cdefs/SHZ_STRINGIFY_LITERAL/) | Stringifies a literal expression. |
| [`SHZ_STRINGIFY`](https://sh4zam.com/api/cdefs/SHZ_STRINGIFY/) | Stringifies an expression *after* preprocessing, supporting macro expansion. |
| [`SHZ_COUNT_OF`](https://sh4zam.com/api/cdefs/SHZ_COUNT_OF/) | Returns the number of elements within a statically sized array. |
| [`SHZ_CONTAINER_OF`](https://sh4zam.com/api/cdefs/SHZ_CONTAINER_OF/) | Returns the containing structure from a pointer to one of its members. |
| [`SHZ_SWAP`](https://sh4zam.com/api/cdefs/SHZ_SWAP/) | Macro which swaps the two values held by `a` and `b`. |
| [`SHZ_DECLARE_STRUCT`](https://sh4zam.com/api/cdefs/SHZ_DECLARE_STRUCT/) | Macro which forward declares a struct and its typedef. |
| [`SHZ_DECLARE_STRUCT_ALIGNED`](https://sh4zam.com/api/cdefs/SHZ_DECLARE_STRUCT_ALIGNED/) | Macro which forward declares a manually aligned struct and its typedef. |

## TLS Utilities

Macros for declaring and managing thread-local variables.

| Symbol | Description |
| --- | --- |
| [`SHZ_TLS_DECL`](https://sh4zam.com/api/cdefs/SHZ_TLS_DECL/) | Declares a TLS variable with disabled model (so not thread-local). |
| [`SHZ_TLS_REF`](https://sh4zam.com/api/cdefs/SHZ_TLS_REF/) | References a TLS variable, with disabled model. |

## Aliasing Types

Types which may break C/C++'s strict aliasing rules

| Symbol | Description |
| --- | --- |
| [`shz_alias_int16_t`](https://sh4zam.com/api/cdefs/shz_alias_int16_t/) | int16_t type whose value may be aliased as another type. |
| [`shz_alias_uint16_t`](https://sh4zam.com/api/cdefs/shz_alias_uint16_t/) | uint16_t type whose value may be aliased as another type. |
| [`shz_alias_int32_t`](https://sh4zam.com/api/cdefs/shz_alias_int32_t/) | int32_t type whose value may be aliased as another type. |
| [`shz_alias_uint32_t`](https://sh4zam.com/api/cdefs/shz_alias_uint32_t/) | uint32_t type whose value may be aliased as another type. |
| [`shz_alias_float_t`](https://sh4zam.com/api/cdefs/shz_alias_float_t/) | float type whose value may be aliased as another type. |
| [`shz_alias_int64_t`](https://sh4zam.com/api/cdefs/shz_alias_int64_t/) | int64_t type whose value may be aliased as another type. |
| [`shz_alias_uint64_t`](https://sh4zam.com/api/cdefs/shz_alias_uint64_t/) | uint64_t type whose value may be aliased as another type. |
| [`shz_alias_double_t`](https://sh4zam.com/api/cdefs/shz_alias_double_t/) | double type whose value may be aliased as another type. |

## Macros

| Symbol | Description |
| --- | --- |
| [`SHZ_TARGET`](https://sh4zam.com/api/cdefs/SHZ_TARGET/) | Target architecture Determines the actual architecture we're building for. |
| [`SHZ_BACKEND`](https://sh4zam.com/api/cdefs/SHZ_BACKEND/) | SH4ZAM back-end Selects which SH4ZAM implementation to use for a given target. |
| [`SHZ_TLS_MODEL`](https://sh4zam.com/api/cdefs/SHZ_TLS_MODEL/) | thread_local storage. |

## Not in upstream reference

Public declarations that upstream keeps out of its Doxygen reference. Listed for completeness; prefer the documented API.

| Symbol | Description |
| --- | --- |
| [`SHZ_MSVC`](https://sh4zam.com/api/cdefs/SHZ_MSVC/) | Defined when building with Microsoft Visual C++. |
| [`SHZ_CLANG`](https://sh4zam.com/api/cdefs/SHZ_CLANG/) | Defined when bulding with Clang. |
| [`SHZ_MINGW64`](https://sh4zam.com/api/cdefs/SHZ_MINGW64/) | Defined when bulding with MinGW-w64. |
| [`SHZ_MINGW32`](https://sh4zam.com/api/cdefs/SHZ_MINGW32/) | Defined when building for 32-bit MinGW or other MinGW compiler(s). |
| [`SHZ_GCC`](https://sh4zam.com/api/cdefs/SHZ_GCC/) | Defined when building for GCC. |
| [`SHZ_ALIGNAS`](https://sh4zam.com/api/cdefs/SHZ_ALIGNAS/) | Forces a function or type to be aligned by `N` bytes. |
| [`SHZ_SIMD`](https://sh4zam.com/api/cdefs/SHZ_SIMD/) | Tells GCC that a scalar type is to be treated as a vector of size `N.` |
| [`SHZ_HOT`](https://sh4zam.com/api/cdefs/SHZ_HOT/) | Tells GCC that a particular function should be optimized for performance. |
| [`SHZ_COLD`](https://sh4zam.com/api/cdefs/SHZ_COLD/) | Tells GCC that a particular function should be optimized for size. |
| [`SHZ_FAST_MATH`](https://sh4zam.com/api/cdefs/SHZ_FAST_MATH/) | Put this before a function definition to tell GCC to use fast math optimizations on a specific function. |
| [`SHZ_NO_FAST_MATH`](https://sh4zam.com/api/cdefs/SHZ_NO_FAST_MATH/) | Put this before a function definition to tell GCC to NOT use fast math optimizations on a specific function. |
| [`SHZ_NO_UNROLL_LOOPS`](https://sh4zam.com/api/cdefs/SHZ_NO_UNROLL_LOOPS/) | Put this before a function definition to tell GCC to NOT unroll loops in a specific function. |
| [`SHZ_NO_OPTIMIZATION`](https://sh4zam.com/api/cdefs/SHZ_NO_OPTIMIZATION/) | Tells GCC to disable any optimizations when compiling a function. |
| [`SHZ_FUNC_ALIGNAS`](https://sh4zam.com/api/cdefs/SHZ_FUNC_ALIGNAS/) | Aligns a function within the .text segment by `N` bytes. |
| [`SHZ_FORCE_INLINE`](https://sh4zam.com/api/cdefs/SHZ_FORCE_INLINE/) | Forces GCC to inline the given function. |
| [`SHZ_NO_INLINE`](https://sh4zam.com/api/cdefs/SHZ_NO_INLINE/) | Prevents GCC from inlining the given function. |
| [`SHZ_FLATTEN`](https://sh4zam.com/api/cdefs/SHZ_FLATTEN/) | Forces GCC to inline all calls to other functions made within the tagged function. |
| [`SHZ_PACKED`](https://sh4zam.com/api/cdefs/SHZ_PACKED/) | Tells GCC not to introduce any extra padding for the given type. |
| [`SHZ_PURE`](https://sh4zam.com/api/cdefs/SHZ_PURE/) | Tells GCC the function has no effects other than returning a value that depends on its arguments and global variables. |
| [`SHZ_CONST`](https://sh4zam.com/api/cdefs/SHZ_CONST/) | Tells GCC the function has no effects other than returning a value that depends only on its arguments. |
| [`SHZ_ALIASING`](https://sh4zam.com/api/cdefs/SHZ_ALIASING/) | Tells GCC that the decorated pointer may be breaking strict aliasing rules for C and C++ |
| [`SHZ_DEPRECATED`](https://sh4zam.com/api/cdefs/SHZ_DEPRECATED/) | Emits a warning that a symbol has been deprecated with a message, upon use. |
| [`SHZ_LIKELY`](https://sh4zam.com/api/cdefs/SHZ_LIKELY/) | Tells GCC that the expression is likely to be true (used for conditional and loop optimizations) |
| [`SHZ_UNLIKELY`](https://sh4zam.com/api/cdefs/SHZ_UNLIKELY/) | Tells GCC that the expression is likely to be false (used for conditional and loop optimizations) |
| [`SHZ_RESTRICT`](https://sh4zam.com/api/cdefs/SHZ_RESTRICT/) | Tells GCC the pointer paraemter is unique and is not aliased by another parameter |
| [`SHZ_MEMORY_BARRIER_SOFT`](https://sh4zam.com/api/cdefs/SHZ_MEMORY_BARRIER_SOFT/) | Creates a software memory barrier beyond which any loads or stores may not be reordered |
| [`SHZ_MEMORY_BARRIER_HARD`](https://sh4zam.com/api/cdefs/SHZ_MEMORY_BARRIER_HARD/) | Creates a hardware memory barrier beyond which any loads or stores may not be reordered |
| [`SHZ_INSTR_BARRIER`](https://sh4zam.com/api/cdefs/SHZ_INSTR_BARRIER/) | Prevents the compiler from reordering instructions beyond the barrier. |
| [`SHZ_DECLS_BEGIN`](https://sh4zam.com/api/cdefs/SHZ_DECLS_BEGIN/) | Dummy define provided for C++ compatibility |
| [`SHZ_DECLS_END`](https://sh4zam.com/api/cdefs/SHZ_DECLS_END/) | Dummy define provided for C++ compatibility |
| [`SHZ_INLINE`](https://sh4zam.com/api/cdefs/SHZ_INLINE/) | Requests a function or member to be inlined (nonforcibly) OR to have static linkage. |
| [`SHZ_NOEXCEPT`](https://sh4zam.com/api/cdefs/SHZ_NOEXCEPT/) | Dummy define provided for C++ compatibility |
| [`SHZ_INIT`](https://sh4zam.com/api/cdefs/SHZ_INIT/) | Temporary struct initialization statement to use within C. |
| [`SHZ_CONVERT`](https://sh4zam.com/api/cdefs/SHZ_CONVERT/) | Conversion macro for zero-overhead conversions, taking the given `value` to a value of the given `type.` |