BUG-REPORTING

   1
   2 Bugs can be reported on liboil at https://bugs.freedesktop.org/.
   3
   4 When starting a program that uses liboil, it is not uncommon to
   5 see an error message such as:
   6
   7
   8   OIL: ERROR liboiltest.c 309: oil_test_check_impl(): function
   9   fbCompositeSolid_nx8888mmx in class composite_over_argb_const_src
  10   failed check (1.67772e+07 > 100) outside=0
  11
  12
  13 This message is an error for liboil, but because of the way that
  14 liboil works, the error does not affect the performance of the
  15 program being run.
  16
  17
  18 Bug reporting:
  19
  20  1. I get a message like the one above:
  21
  22     What to do:
  23
  24       - File a bug on the liboil package of your distro with a
  25         severity/priority of 'normal'.  You may also want to file the
  26         bug and/or search for duplicates in the upstream bugzilla.
  27
  28     What to include:
  29
  30       - The output of oil-bugreport.
  31
  32     Triaging:
  33
  34       - Debug messages with the same function ('fbCompositeSolid_nx8888mmx')
  35         are duplicates.  If the function is different, they are not
  36         duplicates and should be separate bug reports.
  37
  38
  39  2. I get a message like the one above and my program crashes.  I think
  40     it's caused by liboil.
  41
  42     It's not.  The bug is elsewhere.  Really.  The debug message means
  43     that liboil caught a potential crash and is avoiding it.
  44
  45
  46  3. My program crashes on startup and the backtrace includes oil_init().
  47
  48     What to do:
  49
  50       - File a bug on liboil with a severity 'crasher'.
  51
  52     What to include:
  53
  54       - The version of liboil
  55
  56       - A stack backtrace.  Alternately, set 'OIL_DEBUG=3' in the
  57         environment and capture the output of the program as it
  58         crashes.
  59
  60       - The output of oil-bugreport.
  61
  62     Workarounds:
  63
  64       - User:  Set 'OIL_CPU_FLAGS=0' in your environment.  This will make
  65         function calls to liboil really slow, but will generally avoid
  66         any serious problems.
  67
  68       - Distributor:  Find the offending function the source code and
  69         disable it by commenting out the function and the OIL_DEFINE_IMPL()
  70         line (usually immediately following it).
  71
  72
  73  4. When I debug a program that uses liboil, gdb stops with SIGILL.
  74
  75     Illegal instruction signals can be a normal occurance during the
  76     startup of liboil, depending on your particular CPU.  Liboil is
  77     either testing features of your CPU and the kernel is reporting
  78     that a feature is not supported, or liboil is running an
  79     implementation that isn't flagged correctly for the CPU features
  80     that it uses.  In the latter case, an error message is printed,
  81     which should be reported as a normal bug.
  82
  83     By default, gdb stops the debugged program when it gets a SIGILL
  84     signal.  That's not the desired behavior however, since liboil is
  85     prepared (and sometimes expecting) to get the signal.  So you
  86     should use the gdb command 'c' to continue past these signals.  If
  87     you do lots of liboil debugging (like I do), you may prefer to
  88     ignore all SIGILL signals using the command 'handle SIGILL nostop
  89     noprint'.
  90
  91
  92
  93