HACKING

   1
   2 Hacking on liboil
   3 =================
   4
   5
   6 New Implementations
   7 -------------------
   8
   9   New implementations using GCC inline assembly code should go in
  10   liboil/${arch}, or liboil/i386_amd64 if they compile on both i386
  11   and amd64 architectures.  New implementations that are written in
  12   POSIX C should go in liboil/c.  New implementations written with
  13   MMX/SSE/Altivec instrinsics should go in liboil/mmx, liboil/sse,
  14   or liboil/altivec.
  15
  16   Implementations copied from other projects should generally be
  17   given a separate directory under liboil/, similar to liboil/motovec.
  18
  19   Things to check for when writing new implementations:
  20
  21     - handle the n==0 case correctly
  22
  23     - handle various array alignments correctly if the vectorized
  24       code has trouble loading misaligned data.  Sometimes this is
  25       only a problem on certain CPUs.
  26
  27     - unrolled loops and vectorized code needs to handle any extra
  28       array elements at the end of array.
  29
  30     - if a class has strides, they must be followed.
  31
  32   Things implementations can assume:
  33
  34     - n will never be negative
  35
  36     - alignment of individual array members.  For example, if the
  37       type is "u32", you can assume that pointers and strides are
  38       multiples of 4.
  39
  40   In general, if your implementation is enabled on the current CPU
  41   and 'make check' passes, it's probably a clean implementation.
  42
  43   Broken implementations (i.e., code that is a work-in-progress)
  44   are still allowed, as long as the broken code is wrapped in
  45   #ifdef ENABLE_BROKEN_IMPLS/#endif.
  46
  47
  48 New Classes
  49 -----------
  50
  51   Reference implementations for new classes should go in liboil/ref.
  52
  53   The naming of new classes is a tricky business.  The goal is to
  54   make the name short, easy to remember and type, but descriptive
  55   enough to differentiate it from alternatives.  This policy has
  56   not always been followed in the past, so don't follow that lead.
  57
  58   Try to:
  59
  60     - Use full names instead of abbreviations.  Some abbreviations
  61       however are common and acceptable, such as "diff", "avg", or
  62       "abs".
  63
  64     - Use a name that makes sense independent of the application
  65       that you may be copying it from.
  66
  67     - Use nouns instead of verbs (thus, "difference" instead of
  68       "subtract", or "sum" instead of "add").
  69
  70   Class names are made up of a base part that describes what the
  71   function does, appended with modifiers.  Common modifiers are
  72   for the type ("_f64", "_u8"), or to indicate inaccuracies or
  73   limitations in implementations ("_i10", "_l10").
  74
  75   _i10 stands for "inaccurate by a factor of 10", where the baseline
  76   accuracy is 2^-52 for doubles and 2^-24 (I think).  It's a decilog
  77   scale, so _i20 is a factor of 100, etc.  The baseline accuracy comes
  78   from the least expressible number greater than 1.0.
  79
  80   _l10 stands for "something is limited to 10".  Sometimes this means
  81   input range, e.g., _l15 is (was?) used for some function class that
  82   could only handle input values in the range [-1<<14, 1<<14-1].
  83   Another class uses this to mean that only 10 of the input values
  84   can be non-zero (oil_idct8x8theora_l10).
  85
  86   These modifiers are obviously not well-thought-out.  In order to
  87   be useful, applications need to be able to make predictions about
  88   accuracy based on value of n, input values, etc.  I also don't
  89   think that simply defining new classes is a maintainable solution.
  90
  91   Use of underscores in the base part of the class name is arbitrary.
  92   This may change in the future.
  93
  94   New classes should not use the modifier "_ns", since non-strided
  95   arrays are the default.
  96
  97   Parameters should generally follow the order:
  98
  99     i1, is1, i2, is2, ..., d1, ds1, ..., s1, ss1, ..., n, m
 100
 101   After you add a new class, it's necessary to run 'make update' in
 102   the liboil/ directory to regenerate some built headers.
 103
 104
 105
 106 Test Machines
 107 -------------
 108
 109   Machines that ds has access to:
 110
 111     power5.infradead.org - powerpc POWER5
 112     bombadil.infradead.org - powerpc PPC970MP (G5)
 113
 114
 115