* BUGS:

remove.
* BUG-REPORTING:
add.
* HACKING:
* Makefile.am:
* NEWS:
* README:
documentation fixes.

7 files changed, 131 insertions, 26 deletions

diff --git a/BUG-REPORTING b/BUG-REPORTING
new file mode 100644
index 0000000..3b5b30e
--- /dev/null
+++ b/BUG-REPORTING
@@ -0,0 +1,93 @@
+
+Bugs can be reported on liboil at https://bugs.freedesktop.org/.
+
+When starting a program that uses liboil, it is not uncommon to
+see an error message such as:
+
+
+  OIL: ERROR liboiltest.c 309: oil_test_check_impl(): function
+  fbCompositeSolid_nx8888mmx in class composite_over_argb_const_src
+  failed check (1.67772e+07 > 100) outside=0
+
+
+This message is an error for liboil, but because of the way that
+liboil works, the error does not affect the performance of the
+program being run.
+
+
+Bug reporting:
+
+ 1. I get a message like the one above:
+
+    What to do:
+
+      - File a bug on the liboil package of your distro with a
+        severity/priority of 'normal'.  You may also want to file the
+        bug and/or search for duplicates in the upstream bugzilla.
+
+    What to include:
+
+      - The output of oil-bugreport.
+
+    Triaging:
+
+      - Debug messages with the same function ('fbCompositeSolid_nx8888mmx')
+        are duplicates.  If the function is different, they are not
+        duplicates and should be separate bug reports.
+
+
+ 2. I get a message like the one above and my program crashes.  I think
+    it's caused by liboil.
+
+    It's not.  The bug is elsewhere.  Really.  The debug message means
+    that liboil caught a potential crash and is avoiding it.
+
+
+ 3. My program crashes on startup and the backtrace includes oil_init().
+
+    What to do:
+
+      - File a bug on liboil with a severity 'crasher'.
+
+    What to include:
+
+      - The version of liboil
+
+      - A stack backtrace.  Alternately, set 'OIL_DEBUG=3' in the
+        environment and capture the output of the program as it
+        crashes.
+
+      - The output of oil-bugreport.
+
+    Workarounds:
+
+      - User:  Set 'OIL_CPU_FLAGS=0' in your environment.  This will make
+        function calls to liboil really slow, but will generally avoid
+        any serious problems.
+
+      - Distributor:  Find the offending function the source code and
+        disable it by commenting out the function and the OIL_DEFINE_IMPL()
+        line (usually immediately following it).
+
+
+ 4. When I debug a program that uses liboil, gdb stops with SIGILL.
+ 
+    Illegal instruction signals can be a normal occurance during the
+    startup of liboil, depending on your particular CPU.  Liboil is
+    either testing features of your CPU and the kernel is reporting
+    that a feature is not supported, or liboil is running an
+    implementation that isn't flagged correctly for the CPU features
+    that it uses.  In the latter case, an error message is printed,
+    which should be reported as a normal bug.
+    
+    By default, gdb stops the debugged program when it gets a SIGILL
+    signal.  That's not the desired behavior however, since liboil is
+    prepared (and sometimes expecting) to get the signal.  So you
+    should use the gdb command 'c' to continue past these signals.  If
+    you do lots of liboil debugging (like I do), you may prefer to
+    ignore all SIGILL signals using the command 'handle SIGILL nostop
+    noprint'.
+
+
+
+
diff --git a/BUGS b/BUGS
deleted file mode 100644
index 2d80791..0000000
--- a/BUGS
+++ /dev/null
@@ -1,7 +0,0 @@
-
-setting DISABLED on an implementation doesn't really disable it.
-
-need a UNALIGNED cpu flag for cpus that can handle unaligned
-memory access.
-
-
diff --git a/ChangeLog b/ChangeLog
index 35d929d..5f09937 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,17 @@
 2006-11-05  David Schleef  <ds@schleef.org>
 
+	* BUGS:
+	  remove.
+	* BUG-REPORTING:
+	  add.
+	* HACKING:
+	* Makefile.am:
+	* NEWS:
+	* README:
+	  documentation fixes.
+
+2006-11-05  David Schleef  <ds@schleef.org>
+
 	* liboil/liboilcpu.c:
 	* liboil/liboilfunction.c:
 	  Clean up some debugging.
diff --git a/HACKING b/HACKING
index 0dafeab..2c05bc3 100644
--- a/HACKING
+++ b/HACKING
@@ -6,15 +6,17 @@ Hacking on liboil
 New Implementations
 -------------------
 
-  New implementations using gcc inline assembly code should go in
-  liboil/${arch}.  New implementations that are written in C should
-  go in liboil/c.  New implementations written in MMX/SSE/Altivec
-  instrinsics should go in liboil/mmx, liboil/sse, or liboil/altivec.
+  New implementations using GCC inline assembly code should go in
+  liboil/${arch}, or liboil/i386_amd64 if they compile on both i386
+  and amd64 architectures.  New implementations that are written in
+  POSIX C should go in liboil/c.  New implementations written with
+  MMX/SSE/Altivec instrinsics should go in liboil/mmx, liboil/sse,
+  or liboil/altivec.
 
   Implementations copied from other projects should generally be
   given a separate directory under liboil/, similar to liboil/motovec.
 
-  Checklist for implementations:
+  Things to check for when writing new implementations:
 
     - handle the n==0 case correctly
 
diff --git a/Makefile.am b/Makefile.am
index 278ef14..0e71e80 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -3,7 +3,7 @@ AUTOMAKE_OPTIONS = foreign
 
 SUBDIRS = liboil testsuite examples doc
 
-EXTRA_DIST = COPYING autogen.sh gtk-doc.make HACKING
+EXTRA_DIST = COPYING autogen.sh gtk-doc.make HACKING BUG-REPORTING
 
 pkgconfig_DATA = liboil-$(LIBOIL_MAJORMINOR).pc
 
diff --git a/NEWS b/NEWS
index 8b13789..6349d3d 100644
--- a/NEWS
+++ b/NEWS
@@ -1 +1,14 @@
 
+0.3.10
+======
+
+ - Lots of new classes and implementations were added for Schrödinger.
+ - Several i386 implementations also compile on amd64, so these were
+   copied over to a separate directory and are now enabled on amd64.
+ - Feature detection on amd64 has been fixed.
+ - All known startup warnings have been fixed.
+ - The core now handles arrays that are 'N plus a constant' in length.
+ - Wrap a bunch of functions in HAVE_UNALIGNED_ACCESS to indicate that
+   they require an architecture that handles unaligned access.
+
+
diff --git a/README b/README
index 8d98bfb..8f03bd0 100644
--- a/README
+++ b/README
@@ -10,7 +10,7 @@ nor installed.
 
 Using GCC is strongly recommended, since the most interesting bits
 of liboil are written in GCC-style inline assembly.  GCC versions
-prior to 3.2 are not supported.
+prior to 3.4 are not supported.
 
 
 Problems Compiling?
@@ -24,16 +24,17 @@ simply disable it and the corresponding OIL_DEFINE_IMPL() line.
 ABI warning
 ===========
 
-In general, liboil is not ABI stable.  However, portions of liboil
-are guaranteed to be stable through the 0.3.x series, and by using
+Only a portion of the liboil API is ABI stable.  This portion is
+guaranteed to be stable through the 0.3.x series, and by using
 a compatibility library, through the 0.4.x series as well.  This
 policy is designed to provide almost all applications the necessary
 ABI stability for the symbols likely to be used in liboil.
 
 Any symbols declared by including <liboil/liboil.h> follow this
 ABI policy.  This includes all liboil function classes as well
-as a limited number of core functionality, such as oil_init().
+as a limited number of core functions, such as oil_init().
 
+Functions defined in other header files should not be used.
 
 
 ABI Implementation
@@ -67,12 +68,3 @@ unduly cumbersome.
 
 
 
-Random Ideas
-============
-
-Why is trans8x8_f64 so slow on powerpc (compared to trans8x8_u16)?
-
-oil_restride_XXX() - copy with stride
-
-
-