gcc/doc/gccint/passes-and-files-of-the-compiler/pass-manager.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 .. _pass-manager:
   7
   8 Pass manager
   9 ************
  10
  11 The pass manager is located in :samp:`passes.cc`, :samp:`tree-optimize.c`
  12 and :samp:`tree-pass.h`.
  13 It processes passes as described in :samp:`passes.def`.
  14 Its job is to run all of the individual passes in the correct order,
  15 and take care of standard bookkeeping that applies to every pass.
  16
  17 The theory of operation is that each pass defines a structure that
  18 represents everything we need to know about that pass---when it
  19 should be run, how it should be run, what intermediate language
  20 form or on-the-side data structures it needs.  We register the pass
  21 to be run in some particular order, and the pass manager arranges
  22 for everything to happen in the correct order.
  23
  24 The actuality doesn't completely live up to the theory at present.
  25 Command-line switches and ``timevar_id_t`` enumerations must still
  26 be defined elsewhere.  The pass manager validates constraints but does
  27 not attempt to (re-)generate data structures or lower intermediate
  28 language form based on the requirements of the next pass.  Nevertheless,
  29 what is present is useful, and a far sight better than nothing at all.
  30
  31 Each pass should have a unique name.
  32 Each pass may have its own dump file (for GCC debugging purposes).
  33 Passes with a name starting with a star do not dump anything.
  34 Sometimes passes are supposed to share a dump file / option name.
  35 To still give these unique names, you can use a prefix that is delimited
  36 by a space from the part that is used for the dump file / option name.
  37 E.g. When the pass name is "ud dce", the name used for dump file/options
  38 is "dce".
  39
  40 .. todo:: describe the global variables set up by the pass manager,
  41   and a brief description of how a new pass should use it.
  42   I need to look at what info RTL passes use first…