gcc/jit/jit-common.h

   1 /* Core of implementation of libgccjit.so
   2    Copyright (C) 2013-2024 Free Software Foundation, Inc.
   3    Contributed by David Malcolm <dmalcolm@redhat.com>.
   4
   5 This file is part of GCC.
   6
   7 GCC is free software; you can redistribute it and/or modify it
   8 under the terms of the GNU General Public License as published by
   9 the Free Software Foundation; either version 3, or (at your option)
  10 any later version.
  11
  12 GCC is distributed in the hope that it will be useful, but
  13 WITHOUT ANY WARRANTY; without even the implied warranty of
  14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15 General Public License for more details.
  16
  17 You should have received a copy of the GNU General Public License
  18 along with GCC; see the file COPYING3.  If not see
  19 <http://www.gnu.org/licenses/>.  */
  20
  21 #ifndef JIT_COMMON_H
  22 #define JIT_COMMON_H
  23
  24 #include "libgccjit.h"
  25
  26 #include "vec.h"
  27 #include "tree.h"
  28 #include "inchash.h"
  29 #include "tree-iterator.h"
  30
  31 #ifdef GCC_VERSION
  32 #if GCC_VERSION >= 4001
  33 #define GNU_PRINTF(M, N) __attribute__ ((format (gnu_printf, (M), (N))))
  34 #else
  35 #define GNU_PRINTF(M, N)
  36 #endif
  37 #endif
  38
  39 const int NUM_GCC_JIT_TYPES = GCC_JIT_TYPE_BFLOAT16 + 1;
  40
  41 /* This comment is included by the docs.
  42
  43    In order to allow jit objects to be usable outside of a compile
  44    whilst working with the existing structure of GCC's code the
  45    C API is implemented in terms of a gcc::jit::recording::context,
  46    which records the calls made to it.
  47
  48    When a gcc_jit_context is compiled, the recording context creates a
  49    playback context.  The playback context invokes the bulk of the GCC
  50    code, and within the "frontend" parsing hook, plays back the recorded
  51    API calls, creating GCC tree objects.
  52
  53    So there are two parallel families of classes: those relating to
  54    recording, and those relating to playback:
  55
  56    * Visibility: recording objects are exposed back to client code,
  57      whereas playback objects are internal to the library.
  58
  59    * Lifetime: recording objects have a lifetime equal to that of the
  60      recording context that created them, whereas playback objects only
  61      exist within the frontend hook.
  62
  63    * Memory allocation: recording objects are allocated by the recording
  64      context, and automatically freed by it when the context is released,
  65      whereas playback objects are allocated within the GC heap, and
  66      garbage-collected; they can own GC-references.
  67
  68    * Integration with rest of GCC: recording objects are unrelated to the
  69      rest of GCC, whereas playback objects are wrappers around "tree"
  70      instances.  Hence you can't ask a recording rvalue or lvalue what its
  71      type is, whereas you can for a playback rvalue of lvalue (since it
  72      can work with the underlying GCC tree nodes).
  73
  74    * Instancing: There can be multiple recording contexts "alive" at once
  75      (albeit it only one compiling at once), whereas there can only be one
  76      playback context alive at one time (since it interacts with the GC).
  77
  78    Ultimately if GCC could support multiple GC heaps and contexts, and
  79    finer-grained initialization, then this recording vs playback
  80    distinction could be eliminated.
  81
  82    During a playback, we associate objects from the recording with
  83    their counterparts during this playback.  For simplicity, we store this
  84    within the recording objects, as ``void *m_playback_obj``, casting it to
  85    the appropriate playback object subclass.  For these casts to make
  86    sense, the two class hierarchies need to have the same structure.
  87
  88    Note that the playback objects that ``m_playback_obj`` points to are
  89    GC-allocated, but the recording objects don't own references:
  90    these associations only exist within a part of the code where
  91    the GC doesn't collect, and are set back to NULL before the GC can
  92    run.
  93
  94    End of comment for inclusion in the docs.  */
  95
  96 namespace gcc {
  97
  98 namespace jit {
  99
 100 class result;
 101 class dump;
 102 class logger;
 103 class builtins_manager; // declared within jit-builtins.h
 104 class tempdir;
 105
 106 namespace recording {
 107
 108   /* Recording types.  */
 109
 110   /* Indentation indicates inheritance: */
 111   class context;
 112   class memento;
 113     class string;
 114     class location;
 115     class type;
 116       class function_type;
 117       class compound_type;
 118         class struct_;
 119         class union_;
 120       class vector_type;
 121       class array_type;
 122     class field;
 123       class bitfield;
 124     class fields;
 125     class function;
 126     class block;
 127     class rvalue;
 128       class lvalue;
 129         class local;
 130         class global;
 131         class param;
 132       class base_call;
 133       class function_pointer;
 134     class statement;
 135       class extended_asm;
 136     class case_;
 137   class top_level_asm;
 138
 139   /* End of recording types. */
 140 }
 141
 142 namespace playback {
 143   /* Playback types.  */
 144
 145   /* Indentation indicates inheritance: */
 146   class context;
 147   class wrapper;
 148     class type;
 149       class compound_type;
 150     class field;
 151     class function;
 152     class block;
 153     class rvalue;
 154       class lvalue;
 155         class param;
 156     class source_file;
 157     class source_line;
 158     class location;
 159     class case_;
 160
 161   /* End of playback types. */
 162 }
 163
 164 typedef playback::context replayer;
 165
 166 class dump
 167 {
 168 public:
 169   dump (recording::context &ctxt,
 170         const char *filename,
 171         bool update_locations);
 172   ~dump ();
 173
 174   recording::context &get_context () { return m_ctxt; }
 175
 176   void write (const char *fmt, ...)
 177     GNU_PRINTF(2, 3);
 178
 179   bool update_locations () const { return m_update_locations; }
 180
 181   recording::location *
 182   make_location () const;
 183
 184   FILE *get_file () const { return m_file; }
 185
 186 private:
 187   recording::context &m_ctxt;
 188   const char *m_filename;
 189   bool m_update_locations;
 190   int m_line;
 191   int m_column;
 192   FILE *m_file;
 193 };
 194
 195 /* A hidden enum of boolean options that are only exposed via API
 196    entrypoints, rather than via gcc_jit_context_set_bool_option.  */
 197
 198 enum inner_bool_option
 199 {
 200   INNER_BOOL_OPTION_ALLOW_UNREACHABLE_BLOCKS,
 201   INNER_BOOL_OPTION_USE_EXTERNAL_DRIVER,
 202   INNER_BOOL_OPTION_PRINT_ERRORS_TO_STDERR,
 203
 204   NUM_INNER_BOOL_OPTIONS
 205 };
 206
 207 /* Flags for global variables class.  For when the playback of the
 208    global need to know what will happen to it later.  */
 209 enum global_var_flags
 210 {
 211   GLOBAL_VAR_FLAGS_NONE = 0,
 212   GLOBAL_VAR_FLAGS_WILL_BE_RVAL_INIT = 1,
 213   GLOBAL_VAR_FLAGS_WILL_BE_BLOB_INIT = 2,
 214 };
 215
 216 } // namespace gcc::jit
 217
 218 } // namespace gcc
 219
 220 #endif /* JIT_COMMON_H */