src/jit/v.lua

   1 ----------------------------------------------------------------------------
   2 -- Verbose mode of the LuaJIT compiler.
   3 --
   4 -- Copyright (C) 2005-2023 Mike Pall. All rights reserved.
   5 -- Released under the MIT license. See Copyright Notice in luajit.h
   6 ----------------------------------------------------------------------------
   7 --
   8 -- This module shows verbose information about the progress of the
   9 -- JIT compiler. It prints one line for each generated trace. This module
  10 -- is useful to see which code has been compiled or where the compiler
  11 -- punts and falls back to the interpreter.
  12 --
  13 -- Example usage:
  14 --
  15 --   luajit -jv -e "for i=1,1000 do for j=1,1000 do end end"
  16 --   luajit -jv=myapp.out myapp.lua
  17 --
  18 -- Default output is to stderr. To redirect the output to a file, pass a
  19 -- filename as an argument (use '-' for stdout) or set the environment
  20 -- variable LUAJIT_VERBOSEFILE. The file is overwritten every time the
  21 -- module is started.
  22 --
  23 -- The output from the first example should look like this:
  24 --
  25 -- [TRACE   1 (command line):1 loop]
  26 -- [TRACE   2 (1/3) (command line):1 -> 1]
  27 --
  28 -- The first number in each line is the internal trace number. Next are
  29 -- the file name ('(command line)') and the line number (':1') where the
  30 -- trace has started. Side traces also show the parent trace number and
  31 -- the exit number where they are attached to in parentheses ('(1/3)').
  32 -- An arrow at the end shows where the trace links to ('-> 1'), unless
  33 -- it loops to itself.
  34 --
  35 -- In this case the inner loop gets hot and is traced first, generating
  36 -- a root trace. Then the last exit from the 1st trace gets hot, too,
  37 -- and triggers generation of the 2nd trace. The side trace follows the
  38 -- path along the outer loop and *around* the inner loop, back to its
  39 -- start, and then links to the 1st trace. Yes, this may seem unusual,
  40 -- if you know how traditional compilers work. Trace compilers are full
  41 -- of surprises like this -- have fun! :-)
  42 --
  43 -- Aborted traces are shown like this:
  44 --
  45 -- [TRACE --- foo.lua:44 -- leaving loop in root trace at foo:lua:50]
  46 --
  47 -- Don't worry -- trace aborts are quite common, even in programs which
  48 -- can be fully compiled. The compiler may retry several times until it
  49 -- finds a suitable trace.
  50 --
  51 -- Of course this doesn't work with features that are not-yet-implemented
  52 -- (NYI error messages). The VM simply falls back to the interpreter. This
  53 -- may not matter at all if the particular trace is not very high up in
  54 -- the CPU usage profile. Oh, and the interpreter is quite fast, too.
  55 --
  56 -- Also check out the -jdump module, which prints all the gory details.
  57 --
  58 ------------------------------------------------------------------------------
  59
  60 -- Cache some library functions and objects.
  61 local jit = require("jit")
  62 local jutil = require("jit.util")
  63 local vmdef = require("jit.vmdef")
  64 local funcinfo, traceinfo = jutil.funcinfo, jutil.traceinfo
  65 local type, sub, format = type, string.sub, string.format
  66 local stdout, stderr = io.stdout, io.stderr
  67
  68 -- Active flag and output file handle.
  69 local active, out
  70
  71 ------------------------------------------------------------------------------
  72
  73 local startloc, startex
  74
  75 local function fmtfunc(func, pc)
  76   local fi = funcinfo(func, pc)
  77   if fi.loc then
  78     return fi.loc
  79   elseif fi.ffid then
  80     return vmdef.ffnames[fi.ffid]
  81   elseif fi.addr then
  82     return format("C:%x", fi.addr)
  83   else
  84     return "(?)"
  85   end
  86 end
  87
  88 -- Format trace error message.
  89 local function fmterr(err, info)
  90   if type(err) == "number" then
  91     if type(info) == "function" then info = fmtfunc(info) end
  92     local fmt = vmdef.traceerr[err]
  93     if fmt == "NYI: bytecode %s" then
  94       local oidx = 6 * info
  95       info = sub(vmdef.bcnames, oidx+1, oidx+6)
  96     end
  97     err = format(fmt, info)
  98   end
  99   return err
 100 end
 101
 102 -- Dump trace states.
 103 local function dump_trace(what, tr, func, pc, otr, oex)
 104   if what == "start" then
 105     startloc = fmtfunc(func, pc)
 106     startex = otr and "("..otr.."/"..(oex == -1 and "stitch" or oex)..") " or ""
 107   else
 108     if what == "abort" then
 109       local loc = fmtfunc(func, pc)
 110       if loc ~= startloc then
 111         out:write(format("[TRACE --- %s%s -- %s at %s]\n",
 112           startex, startloc, fmterr(otr, oex), loc))
 113       else
 114         out:write(format("[TRACE --- %s%s -- %s]\n",
 115           startex, startloc, fmterr(otr, oex)))
 116       end
 117     elseif what == "stop" then
 118       local info = traceinfo(tr)
 119       local link, ltype = info.link, info.linktype
 120       if ltype == "interpreter" then
 121         out:write(format("[TRACE %3s %s%s -- fallback to interpreter]\n",
 122           tr, startex, startloc))
 123       elseif ltype == "stitch" then
 124         out:write(format("[TRACE %3s %s%s %s %s]\n",
 125           tr, startex, startloc, ltype, fmtfunc(func, pc)))
 126       elseif link == tr or link == 0 then
 127         out:write(format("[TRACE %3s %s%s %s]\n",
 128           tr, startex, startloc, ltype))
 129       elseif ltype == "root" then
 130         out:write(format("[TRACE %3s %s%s -> %d]\n",
 131           tr, startex, startloc, link))
 132       else
 133         out:write(format("[TRACE %3s %s%s -> %d %s]\n",
 134           tr, startex, startloc, link, ltype))
 135       end
 136     else
 137       out:write(format("[TRACE %s]\n", what))
 138     end
 139     out:flush()
 140   end
 141 end
 142
 143 ------------------------------------------------------------------------------
 144
 145 -- Detach dump handlers.
 146 local function dumpoff()
 147   if active then
 148     active = false
 149     jit.attach(dump_trace)
 150     if out and out ~= stdout and out ~= stderr then out:close() end
 151     out = nil
 152   end
 153 end
 154
 155 -- Open the output file and attach dump handlers.
 156 local function dumpon(outfile)
 157   if active then dumpoff() end
 158   if not outfile then outfile = os.getenv("LUAJIT_VERBOSEFILE") end
 159   if outfile then
 160     out = outfile == "-" and stdout or assert(io.open(outfile, "w"))
 161   else
 162     out = stderr
 163   end
 164   jit.attach(dump_trace, "trace")
 165   active = true
 166 end
 167
 168 -- Public module functions.
 169 return {
 170   on = dumpon,
 171   off = dumpoff,
 172   start = dumpon -- For -j command line option.
 173 }
 174