Documentation/types.rst

   1 ***********
   2 Type System
   3 ***********
   4
   5 struct symbol is used to represent symbols & types but
   6 most parts pertaining to the types are in the field 'ctype'.
   7 For the purpose of this document, things can be simplified into:
   8
   9 .. code-block:: c
  10
  11         struct symbol {
  12                 enum type type; // SYM_...
  13                 struct ctype {
  14                         struct symbol *base_type;
  15                         unsigned long modifiers;
  16                         unsigned long alignment;
  17                         struct context_list *contexts;
  18                         struct indent *as;
  19                 };
  20         };
  21
  22 Some bits, also related to the type, are in struct symbol itself:
  23   * type
  24   * size_bits
  25   * rank
  26   * variadic
  27   * string
  28   * designated_init
  29   * forced_arg
  30   * accessed
  31   * transparent_union
  32
  33 * ``base_type`` is used for the associated base type.
  34 * ``modifiers`` is a bit mask for type specifiers (MOD_UNSIGNED, ...),
  35   type qualifiers (MOD_CONST, MOD_VOLATILE),
  36   storage classes (MOD_STATIC, MOD_EXTERN, ...), as well for various
  37   attributes. It's also used internally to keep track of some states
  38   (MOD_ACCESS or MOD_ADDRESSABLE).
  39 * ``alignment`` is used for the alignment, in bytes.
  40 * ``contexts`` is used to store the informations associated with the
  41   attribute ``context()``.
  42 * ``as`` is used to hold the identifier of the attribute ``address_space()``.
  43
  44 Kind of types
  45 =============
  46
  47 SYM_BASETYPE
  48 ------------
  49 Used by integer, floating-point, void, 'type', 'incomplete' & bad types.
  50
  51 For integer types:
  52   * .ctype.base_type points to ``int_ctype``, the generic/abstract integer type
  53   * .ctype.modifiers has MOD_UNSIGNED/SIGNED/EXPLICITLY_SIGNED set accordingly.
  54
  55 For floating-point types:
  56   * .ctype.base_type points to ``fp_ctype``, the generic/abstract float type
  57   * .ctype.modifiers is zero.
  58
  59 For the other base types:
  60   * .ctype.base_type is NULL
  61   * .ctype.modifiers is zero.
  62
  63 SYM_NODE
  64 --------
  65 It's used to make variants of existing types. For example,
  66 it's used as a top node for all declarations which can then
  67 have their own modifiers, address_space, contexts or alignment
  68 as well as the declaration's identifier.
  69
  70 Usage:
  71   * .ctype.base_type points to the unmodified type (which must not
  72     be a SYM_NODE itself)
  73   * .ctype.modifiers, .as, .alignment, .contexts will contains
  74     the 'variation' (MOD_CONST, the attributes, ...).
  75
  76 SYM_PTR
  77 -------
  78 For pointers:
  79   * .ctype.base_type points to the pointee type
  80   * .ctype.modifiers & .as are about the pointee too!
  81
  82 SYM_FN
  83 ------
  84 For functions:
  85   * .ctype.base_type points to the return type
  86   * .ctype.modifiers & .as should be about the function itself
  87     but some return type's modifiers creep here (for example, in
  88     int foo(void), MOD_SIGNED will be set for the function).
  89
  90 SYM_ARRAY
  91 ---------
  92 For arrays:
  93   * .ctype.base_type points to the underlying type
  94   * .ctype.modifiers & .as are a copy of the parent type (and unused)?
  95   * for literal strings, the modifier also contains MOD_STATIC
  96   * sym->array_size is *expression* for the array size.
  97
  98 SYM_STRUCT
  99 ----------
 100 For structs:
 101   * .ctype.base_type is NULL
 102   * .ctype.modifiers & .as are not used?
 103   * .ident is the name tag.
 104
 105 SYM_UNION
 106 ---------
 107 Same as for structs.
 108
 109 SYM_ENUM
 110 --------
 111 For enums:
 112   * .ctype.base_type points to the underlying type (integer)
 113   * .ctype.modifiers contains the enum signedness
 114   * .ident is the name tag.
 115
 116 SYM_BITFIELD
 117 ------------
 118 For bitfields:
 119   * .ctype.base_type points to the underlying type (integer)
 120   * .ctype.modifiers & .as are a copy of the parent type (and unused)?
 121   * .bit_size is the size of the bitfield.
 122
 123 SYM_RESTRICT
 124 ------------
 125 Used for bitwise types (aka 'restricted' types):
 126   * .ctype.base_type points to the underlying type (integer)
 127   * .ctype.modifiers & .as are like for SYM_NODE and the modifiers
 128     are inherited from the base type with MOD_SPECIFIER removed
 129   * .ident is the typedef name (if any).
 130
 131 SYM_FOULED
 132 ----------
 133 Used for bitwise types when the negation op (~) is
 134 used and the bit_size is smaller than an ``int``.
 135 There is a 1-to-1 mapping between a fouled type and
 136 its parent bitwise type.
 137
 138 Usage:
 139   * .ctype.base_type points to the parent type
 140   * .ctype.modifiers & .as are the same as for the parent type
 141   * .bit_size is bits_in_int.
 142
 143 SYM_TYPEOF
 144 ----------
 145 Should not be present after evaluation:
 146   * .initializer points to the expression representing the type
 147   * .ctype is not used.
 148
 149 Typeofs with a type as argument are directly evaluated during parsing.
 150
 151 SYM_LABEL
 152 ---------
 153 Used for labels only.
 154
 155 SYM_KEYWORD
 156 -----------
 157 Used for parsing only.
 158
 159 SYM_BAD
 160 -------
 161 Should not be used.
 162
 163 SYM_UNINTIALIZED
 164 ----------------
 165 Should not be used.