gcc/doc/gccint/target-macros/layout-of-source-language-data-types.rst

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. _type-layout:
   7
   8 Layout of Source Language Data Types
   9 ************************************
  10
  11 These macros define the sizes and other characteristics of the standard
  12 basic data types used in programs being compiled.  Unlike the macros in
  13 the previous section, these apply to specific features of C and related
  14 languages, rather than to fundamental aspects of storage layout.
  15
  16 .. c:macro:: INT_TYPE_SIZE
  17
  18   A C expression for the size in bits of the type ``int`` on the
  19   target machine.  If you don't define this, the default is one word.
  20
  21 .. c:macro:: SHORT_TYPE_SIZE
  22
  23   A C expression for the size in bits of the type ``short`` on the
  24   target machine.  If you don't define this, the default is half a word.
  25   (If this would be less than one storage unit, it is rounded up to one
  26   unit.)
  27
  28 .. c:macro:: LONG_TYPE_SIZE
  29
  30   A C expression for the size in bits of the type ``long`` on the
  31   target machine.  If you don't define this, the default is one word.
  32
  33 .. c:macro:: ADA_LONG_TYPE_SIZE
  34
  35   On some machines, the size used for the Ada equivalent of the type
  36   ``long`` by a native Ada compiler differs from that used by C.  In
  37   that situation, define this macro to be a C expression to be used for
  38   the size of that type.  If you don't define this, the default is the
  39   value of ``LONG_TYPE_SIZE``.
  40
  41 .. c:macro:: LONG_LONG_TYPE_SIZE
  42
  43   A C expression for the size in bits of the type ``long long`` on the
  44   target machine.  If you don't define this, the default is two
  45   words.  If you want to support GNU Ada on your machine, the value of this
  46   macro must be at least 64.
  47
  48 .. c:macro:: CHAR_TYPE_SIZE
  49
  50   A C expression for the size in bits of the type ``char`` on the
  51   target machine.  If you don't define this, the default is
  52   ``BITS_PER_UNIT``.
  53
  54 .. c:macro:: BOOL_TYPE_SIZE
  55
  56   A C expression for the size in bits of the C++ type ``bool`` and
  57   C99 type ``_Bool`` on the target machine.  If you don't define
  58   this, and you probably shouldn't, the default is ``CHAR_TYPE_SIZE``.
  59
  60 .. c:macro:: FLOAT_TYPE_SIZE
  61
  62   A C expression for the size in bits of the type ``float`` on the
  63   target machine.  If you don't define this, the default is one word.
  64
  65 .. c:macro:: DOUBLE_TYPE_SIZE
  66
  67   A C expression for the size in bits of the type ``double`` on the
  68   target machine.  If you don't define this, the default is two
  69   words.
  70
  71 .. c:macro:: LONG_DOUBLE_TYPE_SIZE
  72
  73   A C expression for the size in bits of the type ``long double`` on
  74   the target machine.  If you don't define this, the default is two
  75   words.
  76
  77 .. c:macro:: SHORT_FRACT_TYPE_SIZE
  78
  79   A C expression for the size in bits of the type ``short _Fract`` on
  80   the target machine.  If you don't define this, the default is
  81   ``BITS_PER_UNIT``.
  82
  83 .. c:macro:: FRACT_TYPE_SIZE
  84
  85   A C expression for the size in bits of the type ``_Fract`` on
  86   the target machine.  If you don't define this, the default is
  87   ``BITS_PER_UNIT * 2``.
  88
  89 .. c:macro:: LONG_FRACT_TYPE_SIZE
  90
  91   A C expression for the size in bits of the type ``long _Fract`` on
  92   the target machine.  If you don't define this, the default is
  93   ``BITS_PER_UNIT * 4``.
  94
  95 .. c:macro:: LONG_LONG_FRACT_TYPE_SIZE
  96
  97   A C expression for the size in bits of the type ``long long _Fract`` on
  98   the target machine.  If you don't define this, the default is
  99   ``BITS_PER_UNIT * 8``.
 100
 101 .. c:macro:: SHORT_ACCUM_TYPE_SIZE
 102
 103   A C expression for the size in bits of the type ``short _Accum`` on
 104   the target machine.  If you don't define this, the default is
 105   ``BITS_PER_UNIT * 2``.
 106
 107 .. c:macro:: ACCUM_TYPE_SIZE
 108
 109   A C expression for the size in bits of the type ``_Accum`` on
 110   the target machine.  If you don't define this, the default is
 111   ``BITS_PER_UNIT * 4``.
 112
 113 .. c:macro:: LONG_ACCUM_TYPE_SIZE
 114
 115   A C expression for the size in bits of the type ``long _Accum`` on
 116   the target machine.  If you don't define this, the default is
 117   ``BITS_PER_UNIT * 8``.
 118
 119 .. c:macro:: LONG_LONG_ACCUM_TYPE_SIZE
 120
 121   A C expression for the size in bits of the type ``long long _Accum`` on
 122   the target machine.  If you don't define this, the default is
 123   ``BITS_PER_UNIT * 16``.
 124
 125 .. c:macro:: LIBGCC2_GNU_PREFIX
 126
 127   This macro corresponds to the ``TARGET_LIBFUNC_GNU_PREFIX`` target
 128   hook and should be defined if that hook is overriden to be true.  It
 129   causes function names in libgcc to be changed to use a ``__gnu_``
 130   prefix for their name rather than the default ``__``.  A port which
 131   uses this macro should also arrange to use :samp:`t-gnu-prefix` in
 132   the libgcc :samp:`config.host`.
 133
 134 .. c:macro:: WIDEST_HARDWARE_FP_SIZE
 135
 136   A C expression for the size in bits of the widest floating-point format
 137   supported by the hardware.  If you define this macro, you must specify a
 138   value less than or equal to the value of ``LONG_DOUBLE_TYPE_SIZE``.
 139   If you do not define this macro, the value of ``LONG_DOUBLE_TYPE_SIZE``
 140   is the default.
 141
 142 .. c:macro:: DEFAULT_SIGNED_CHAR
 143
 144   An expression whose value is 1 or 0, according to whether the type
 145   ``char`` should be signed or unsigned by default.  The user can
 146   always override this default with the options :option:`-fsigned-char`
 147   and :option:`-funsigned-char`.
 148
 149 .. include:: tm.rst.in
 150   :start-after: [TARGET_DEFAULT_SHORT_ENUMS]
 151   :end-before: [TARGET_DEFAULT_SHORT_ENUMS]
 152
 153
 154 .. c:macro:: SIZE_TYPE
 155
 156   A C expression for a string describing the name of the data type to use
 157   for size values.  The typedef name ``size_t`` is defined using the
 158   contents of the string.
 159
 160   The string can contain more than one keyword.  If so, separate them with
 161   spaces, and write first any length keyword, then ``unsigned`` if
 162   appropriate, and finally ``int``.  The string must exactly match one
 163   of the data type names defined in the function
 164   ``c_common_nodes_and_builtins`` in the file :samp:`c-family/c-common.cc`.
 165   You may not omit ``int`` or change the order---that would cause the
 166   compiler to crash on startup.
 167
 168   If you don't define this macro, the default is ``"long unsigned
 169   int"``.
 170
 171 .. c:macro:: SIZETYPE
 172
 173   GCC defines internal types (``sizetype``, ``ssizetype``,
 174   ``bitsizetype`` and ``sbitsizetype``) for expressions
 175   dealing with size.  This macro is a C expression for a string describing
 176   the name of the data type from which the precision of ``sizetype``
 177   is extracted.
 178
 179   The string has the same restrictions as ``SIZE_TYPE`` string.
 180
 181   If you don't define this macro, the default is ``SIZE_TYPE``.
 182
 183 .. c:macro:: PTRDIFF_TYPE
 184
 185   A C expression for a string describing the name of the data type to use
 186   for the result of subtracting two pointers.  The typedef name
 187   ``ptrdiff_t`` is defined using the contents of the string.  See
 188   ``SIZE_TYPE`` above for more information.
 189
 190   If you don't define this macro, the default is ``"long int"``.
 191
 192 .. c:macro:: WCHAR_TYPE
 193
 194   A C expression for a string describing the name of the data type to use
 195   for wide characters.  The typedef name ``wchar_t`` is defined using
 196   the contents of the string.  See ``SIZE_TYPE`` above for more
 197   information.
 198
 199   If you don't define this macro, the default is ``"int"``.
 200
 201 .. c:macro:: WCHAR_TYPE_SIZE
 202
 203   A C expression for the size in bits of the data type for wide
 204   characters.  This is used in ``cpp``, which cannot make use of
 205   ``WCHAR_TYPE``.
 206
 207 .. c:macro:: WINT_TYPE
 208
 209   A C expression for a string describing the name of the data type to
 210   use for wide characters passed to ``printf`` and returned from
 211   ``getwc``.  The typedef name ``wint_t`` is defined using the
 212   contents of the string.  See ``SIZE_TYPE`` above for more
 213   information.
 214
 215   If you don't define this macro, the default is ``"unsigned int"``.
 216
 217 .. c:macro:: INTMAX_TYPE
 218
 219   A C expression for a string describing the name of the data type that
 220   can represent any value of any standard or extended signed integer type.
 221   The typedef name ``intmax_t`` is defined using the contents of the
 222   string.  See ``SIZE_TYPE`` above for more information.
 223
 224   If you don't define this macro, the default is the first of
 225   ``"int"``, ``"long int"``, or ``"long long int"`` that has as
 226   much precision as ``long long int``.
 227
 228 .. c:macro:: UINTMAX_TYPE
 229
 230   A C expression for a string describing the name of the data type that
 231   can represent any value of any standard or extended unsigned integer
 232   type.  The typedef name ``uintmax_t`` is defined using the contents
 233   of the string.  See ``SIZE_TYPE`` above for more information.
 234
 235   If you don't define this macro, the default is the first of
 236   ``"unsigned int"``, ``"long unsigned int"``, or ``"long long
 237   unsigned int"`` that has as much precision as ``long long unsigned
 238   int``.
 239
 240 .. c:macro:: SIG_ATOMIC_TYPE
 241              INT8_TYPE
 242              INT16_TYPE
 243              INT32_TYPE
 244              INT64_TYPE
 245              UINT8_TYPE
 246              UINT16_TYPE
 247              UINT32_TYPE
 248              UINT64_TYPE
 249              INT_LEAST8_TYPE
 250              INT_LEAST16_TYPE
 251              INT_LEAST32_TYPE
 252              INT_LEAST64_TYPE
 253              UINT_LEAST8_TYPE
 254              UINT_LEAST16_TYPE
 255              UINT_LEAST32_TYPE
 256              UINT_LEAST64_TYPE
 257              INT_FAST8_TYPE
 258              INT_FAST16_TYPE
 259              INT_FAST32_TYPE
 260              INT_FAST64_TYPE
 261              UINT_FAST8_TYPE
 262              UINT_FAST16_TYPE
 263              UINT_FAST32_TYPE
 264              UINT_FAST64_TYPE
 265              INTPTR_TYPE
 266              UINTPTR_TYPE
 267
 268   C expressions for the standard types ``sig_atomic_t``,
 269   ``int8_t``, ``int16_t``, ``int32_t``, ``int64_t``,
 270   ``uint8_t``, ``uint16_t``, ``uint32_t``, ``uint64_t``,
 271   ``int_least8_t``, ``int_least16_t``, ``int_least32_t``,
 272   ``int_least64_t``, ``uint_least8_t``, ``uint_least16_t``,
 273   ``uint_least32_t``, ``uint_least64_t``, ``int_fast8_t``,
 274   ``int_fast16_t``, ``int_fast32_t``, ``int_fast64_t``,
 275   ``uint_fast8_t``, ``uint_fast16_t``, ``uint_fast32_t``,
 276   ``uint_fast64_t``, ``intptr_t``, and ``uintptr_t``.  See
 277   ``SIZE_TYPE`` above for more information.
 278
 279   If any of these macros evaluates to a null pointer, the corresponding
 280   type is not supported; if GCC is configured to provide
 281   ``<stdint.h>`` in such a case, the header provided may not conform
 282   to C99, depending on the type in question.  The defaults for all of
 283   these macros are null pointers.
 284
 285 .. c:macro:: TARGET_PTRMEMFUNC_VBIT_LOCATION
 286
 287   The C++ compiler represents a pointer-to-member-function with a struct
 288   that looks like:
 289
 290   .. code-block:: c++
 291
 292       struct {
 293         union {
 294           void (*fn)();
 295           ptrdiff_t vtable_index;
 296         };
 297         ptrdiff_t delta;
 298       };
 299
 300   The C++ compiler must use one bit to indicate whether the function that
 301   will be called through a pointer-to-member-function is virtual.
 302   Normally, we assume that the low-order bit of a function pointer must
 303   always be zero.  Then, by ensuring that the vtable_index is odd, we can
 304   distinguish which variant of the union is in use.  But, on some
 305   platforms function pointers can be odd, and so this doesn't work.  In
 306   that case, we use the low-order bit of the ``delta`` field, and shift
 307   the remainder of the ``delta`` field to the left.
 308
 309   GCC will automatically make the right selection about where to store
 310   this bit using the ``FUNCTION_BOUNDARY`` setting for your platform.
 311   However, some platforms such as ARM/Thumb have ``FUNCTION_BOUNDARY``
 312   set such that functions always start at even addresses, but the lowest
 313   bit of pointers to functions indicate whether the function at that
 314   address is in ARM or Thumb mode.  If this is the case of your
 315   architecture, you should define this macro to
 316   ``ptrmemfunc_vbit_in_delta``.
 317
 318   In general, you should not have to define this macro.  On architectures
 319   in which function addresses are always even, according to
 320   ``FUNCTION_BOUNDARY``, GCC will automatically define this macro to
 321   ``ptrmemfunc_vbit_in_pfn``.
 322
 323 .. c:macro:: TARGET_VTABLE_USES_DESCRIPTORS
 324
 325   Normally, the C++ compiler uses function pointers in vtables.  This
 326   macro allows the target to change to use 'function descriptors'
 327   instead.  Function descriptors are found on targets for whom a
 328   function pointer is actually a small data structure.  Normally the
 329   data structure consists of the actual code address plus a data
 330   pointer to which the function's data is relative.
 331
 332   If vtables are used, the value of this macro should be the number
 333   of words that the function descriptor occupies.
 334
 335 .. c:macro:: TARGET_VTABLE_ENTRY_ALIGN
 336
 337   By default, the vtable entries are void pointers, the so the alignment
 338   is the same as pointer alignment.  The value of this macro specifies
 339   the alignment of the vtable entry in bits.  It should be defined only
 340   when special alignment is necessary. \*/
 341
 342 .. c:macro:: TARGET_VTABLE_DATA_ENTRY_DISTANCE
 343
 344   There are a few non-descriptor entries in the vtable at offsets below
 345   zero.  If these entries must be padded (say, to preserve the alignment
 346   specified by ``TARGET_VTABLE_ENTRY_ALIGN``), set this to the number
 347   of words in each data entry.