New documentation from Richard and Russell.

Change Maintainer to Jason Evans

Submitted by: "Richard Seaman, Jr." <dick@tar.com>

3 files changed, 71 insertions, 48 deletions

diff --git a/devel/linuxthreads/Makefile b/devel/linuxthreads/Makefile
index 181fa9386217..c4aa36f7ed74 100644
--- a/devel/linuxthreads/Makefile
+++ b/devel/linuxthreads/Makefile
@@ -12,7 +12,8 @@ CATEGORIES=    devel
 MASTER_SITES=  ftp://ftp.inria.fr/INRIA/Projects/cristal/Xavier.Leroy/
 ONLY_FOR_ARCHS= i386
 
-MAINTAINER=    dick@tar.com
+#MAINTAINER=    dick@tar.com
+MAINTAINER=    jasone@freebsd.org
 
 threads_files=	_atomic_lock.S  libc_spinlock.h   uthread_rwlock.c \
 		uthread_rwlockattr.c libc_private.h uthread_file.c \
diff --git a/devel/linuxthreads/files/README.FreeBSD b/devel/linuxthreads/files/README.FreeBSD
index f0132e375a4a..64cf6a3b931a 100644
--- a/devel/linuxthreads/files/README.FreeBSD
+++ b/devel/linuxthreads/files/README.FreeBSD
@@ -1,20 +1,21 @@
 Some brief notes:
 
 1) This package is intended to run on FreeBSD 4.0-current or
-FreeBSD 3.X, with sources more recent than March 1, 1999, i386
-processors only.
+FreeBSD 3.X, with sources more recent than May 1, 1999, i386
+processors only.  If you are running an SMP kernel, you should
+be using FreeBSD 4.0-current only.
 
 Compile your applications that use Linux Threads with the following
 command line options:
 
-	-D_THREAD_SAFE -I/usr/local/include/pthread/linuxthreads -llthread
+	-D_THREAD_SAFE -I/usr/local/include/pthread/linuxthreads -llthread -llgcc_r
 
 Note that the include (-I..) directive shown here should appear before any other include
 directive that would cause the compiler to find the FreeBSD file /usr/include/pthread.h.
 Using the FreeBSD pthread.h instead of the linuxthreads pthread.h will result in an app 
-fails in many odd and maybe spectacular ways.
+fails fails in many odd and maybe spectacular ways.
 
-In order to facilitate porting applications witch expect a libpthread, you can create
+In order to facilitate porting applications which expect a libpthread, you can create
 the following symlinks if you want:
 
 	ln -s /usr/local/lib/liblthread.a /usr/lib/libpthread.a
@@ -25,9 +26,9 @@ the following symlinks if you want:
 
 If you do this, you can instead use:
 
-	-D_THREAD_SAFE -I/usr/local/include/pthread/linuxthreads -lpthread
+	-D_THREAD_SAFE -I/usr/local/include/pthread/linuxthreads -lpthread -llgcc_r
 or      
-	-D_THREAD_SAFE -I/usr/local/include/pthread/linuxthreads -kthread
+	-D_THREAD_SAFE -I/usr/local/include/pthread/linuxthreads -kthread -llgcc_r
 
 DO NOT use libc_r with Linux Threads, and do not compile/link with
 the -pthread option (which pulls in libc_r).  DO link with libc
@@ -49,11 +50,7 @@ of kern.maxproc.  Each kernel thread counts against maxproc.  You
 can increase maxproc by changing the MAXUSERS value in your kernel
 config file.  maxproc is set at 20 + 16 * MAXUSERS.
 
-4)  This package should work on a normal SMP machine, however, 
-there appear to be some problems introduced with the recent changes
-to the kernel signal handling, which have yet to be resolved.
-
-5) Be aware of the following libc issues:
+4) Be aware of the following libc issues:
 
 	a) Not all libc calls are thread safe.  Many are.
 	In particular gmtime, localtime, etc are not thread
@@ -73,7 +70,7 @@ to the kernel signal handling, which have yet to be resolved.
 	deferred cancellation will not really do anything, since
 	the co-operation needed from libc is not there.
 
-6) There is a call implemented for FreeBSD (see stack.c):
+5) There is a call implemented for FreeBSD (see stack.c):
  
 int _pthread_setstackspacing(size_t spacing, size_t guardsize)
 
@@ -89,5 +86,60 @@ ie. maximum stack size = spacing - TLSpagesize - guardsize.
 The spacing must be a power of 2 times the pagesize (and if its
 not, it will be rounded up to the next highest value that is).
 
-7) Note that this is an older version of linuxthreads.  More current
+6) Note that this is an older version of linuxthreads.  More current
 versions are at http://www.kernel.org/pub/linux/libs/glibc.
+
+7) Known problems and issues:
+
+a) It is possible that the instructions given above for including
+liblgcc_r are not sufficent.  liblgcc_r is a version of libgcc_r
+linked against this linuxthreads package.  It is intended that
+applications link against this, rather than libgcc_r (which is 
+linked against libc_r) or libgcc (which is not thread safe).
+
+The normal gcc link options cause libgcc to be included twice
+in the link line (and libgcc_r twice when linking with the
+-pthread option). It is therefore possible that a custom link
+line needs to be generated that specifically excludes the
+default libgcc and which includes liblgcc_r twice.  There are
+no known problems resulting from the link procedure suggested
+above.  However, compiling/linking with the "-v" option will
+illustrate the issue, where lihgcc is included twice in
+addition to liblgcc_r.
+
+b) Since some point around Auguest 30 or later, dynamically linked
+SMP applications have experienced problems with the dynamic linker.
+Statically linked applications appear fine.
+
+Specifically, some applications are not able to resolve dynamic
+links as in this sample output:
+
+root@chiricahua:/usr/ports/devel/linuxthreads/work/linuxthreads-0.71/Examples [119] ./ex4
+Thread 400: allocated key 0
+Thread 400: allocating buffer at 0x804b400
+/usr/libexec/ld-elf.so.1: /usr/local/lib/liblthread.so.0: Undefined symbol "sigfillset"
+
+The problem does not occur on every run, but rather intermittently,
+and the undefined symbol is not always "sigfillset", thought
+this is common.
+
+It is possible that ld-elf.so needs to be made thread safe, and that
+the problem is not unique to SMP but only exposed by the higher
+concurrency of SMP threads.  However, the problem has not been
+fully diagnosed.
+
+c) Since August 30 or maybe later, neither this version of FreeBSD
+linuxthreads nor FreeBSD user threads (libc_r) have been able to
+pass the ACE Reactor_Exception_Test using FreeBSD-current.  See
+http://www.pinyon.org/ace for information about ACE and compiling
+it under FreeBSD.  It is possible that PR/15228 is another illustration
+of the same problem. In both cases the app aborts at line 3314 in
+libgcc2.c in the __sjthrow function, because there is no exception
+handler registered at that point.
+
+Earlier, before August 30, both this version of linuxthreads as well]
+as libc_r passed all the ACE thread tests.  The cutoff date for the
+onset of the problem could be later than August 30.
+
+There has not been time to fully diagnose this problem.  It occurs
+on both SMP and UP systems.
diff --git a/devel/linuxthreads/pkg-message b/devel/linuxthreads/pkg-message
index b96e7c746873..abbf2af5cbf0 100644
--- a/devel/linuxthreads/pkg-message
+++ b/devel/linuxthreads/pkg-message
@@ -1,35 +1,5 @@
+Please see the README.FreeBSD file in the work directory for
+instructions on how to compile with linuxthreads, and for other
+issues and problems.
 
 
-NOTES:  This package is intended to run on FreeBSD 4.0-current or
-FreeBSD 3.X, with sources more recent than March 1, 1999, i386 processors
-only.
-
-Compile your applications that use Linux Threads with the following
-command line options:
-
-	-D_THREAD_SAFE -I/usr/local/include/pthread/linuxthreads -llthread
-
-Note that the include (-I..) directive shown here should appear before any other include
-directive that would cause the compiler to find the FreeBSD file /usr/include/pthread.h.
-Using the FreeBSD pthread.h instead of the linuxthreads pthread.h will result in an app 
-fails in many odd and maybe spectacular ways.
-
-In order to facilitate porting applications witch expect a libpthread, you can create
-the following symlinks if you want:
-
-	ln -s /usr/local/lib/liblthread.a /usr/lib/libpthread.a
-	ln -s /usr/local/lib/liblthread_p.a /usr/lib/libpthread_p.a
-	ln -s /usr/local/lib/liblthread.so.0 /usr/lib/libpthread.so.0
-	ln -s /usr/local/lib/liblthread.so.0 /usr/lib/libpthread.so
-	/sbin/ldconfig -m /usr/lib
-
-If you do this, you can instead use:
-
-	-D_THREAD_SAFE -I/usr/local/include/pthread/linuxthreads -lpthread
-or      
-	-D_THREAD_SAFE -I/usr/local/include/pthread/linuxthreads -kthread
-
-DO NOT use libc_r with Linux Threads, and do not compile/link with
-the -pthread option (which pulls in libc_r).  DO link with libc
-(which you will get by default).
-