explain nptl stuff

1 files changed, 37 insertions, 0 deletions

diff --git a/src/libthread/README.Linux b/src/libthread/README.Linux
new file mode 100644
index 00000000..cc193eeb
--- /dev/null
+++ b/src/libthread/README.Linux
@@ -0,0 +1,37 @@
+Thread support on Linux is confused by the recent thread local storage (TLS)
+support that has been put into the ELF tool chain.  The TLS libraries are 
+installed in /lib/tls on most Linux systems.
+
+We provide two different implementations of the os-dependent parts
+of libthread for Linux.  The first is intended for use on Linux 2.4 and earlier
+kernels, which do not support TLS.  It is in Linux.c and Linuxasm.c and
+does not use the pthread interface.  The second is intended for Linux 2.6
+and later kernels, which do support TLS.  It is in pthread.c and uses the
+standard pthread interface.  It expects to be linked against the TLS-aware
+thread library aka NPTL.
+
+If you use Linux.c and Linuxasm.c with TLS libraries, they do not
+set up the TLS properly so you will get incorrect programs.
+For example, there will only be one errno among all the procs
+in your program instead of one per proc.  The pthread NPTL
+implementation is needed to use the TLS libraries properly.
+
+If you use pthread.c without TLS libraries (i.e., with the old Linux
+pthread library known as LinuxThreads), then you will also get
+incorrect programs, although more obviously so.  The LinuxThreads
+library assumes it can look at the stack pointer to distinguish between
+threads, but libthread does its own stack management, breaking this
+assumption.  If you run a pthread-compiled program with the 
+LinuxThreads library, LinuxThreads itself will cause a segmentation
+fault in __pthread_getspecific() the first time it is called from a
+non-standard stack.
+
+So, it is important that you compile binaries that match your
+system's choice of TLS vs. not-TLS libraries.  The hard part is figuring
+out which your system has chosen.  Plan9port looks at the kernel
+version you are running and assumes that on kernels that support
+TLS (2.6+) you will be using TLS.
+
+Apparently Gentoo and maybe other distributions do not follow this rule.
+They use non-TLS libraries even on kernels that can support TLS.
+