Merge branch 'master' of /opt/gnu-chroot/home/dtbartle/glibc-opensolaris
[kopensolaris-gnu/glibc.git] / NOTES.opensolaris
1 auxiliary vector (auxv_t):
2
3   Proper OpenSolaris does not support statically-linked executables (i.e. via
4   gcc -static). However, glibc does, but with certain restrictions. The kernel
5   only builds the auxv_t if the elf file is not of type ET_EXEC or if the
6   PT_INTERP program header exists. This means that dynamically-linked
7   executables and libaries get an auxv_t while statically-linked executables
8   don't. This means that statically-linked executables won't see PT_TLS, which
9   is needed for __thread support. We can test for the SHARED macro for libc
10   library code, but in general, __thread will not work.
11
12   In order to fix this, it should be a matter of changing the kernel to
13   unconditionally supply the auxv_t.
14
15 scheduling:
16
17   The OpenSolaris kernel allows for loadable schedule classes. A scheduling
18   class has an id (pc_cid), associated name (pc_clname), and class-specific
19   scheduling information. As new schedulers are loaded, they are incrementally
20   assigned new id's.
21
22   Since id's are assigned dynamically, there is no way to statically associate
23   a class id with a posix scheduler (i.e. SCHED_*). The only exception is
24   SCHED_SYS, which is guaranteed to have cid == 0.
25
26 threads:
27
28   The sun libpthread/libthread implementation assumes a 1:1 mapping between
29   pthread_t/thread_t and lwpid_t, while NPTL maps thread descriptors to
30   pthread_t. This behaviour was added to NPTL and maybe enabled by defining
31   PTHREAD_T_IS_TID.
32
33 mutex:
34
35   Recursive locks are represented by an 8-byte counter defined by the
36   mutex_rcount macro. The maximum number of recursive waiters is
37   UCHAR_MAX (255).
38
39   Various fields are defined in a 64-bit field. 32 of the bits are used to
40   hold the owner pid. 8-bits each are used for holding the lock byte, the
41   number of waiters, and the number of spinners. Solaris defines some macros
42   for accessing these (architecture dependent of course):
43
44     mutex_lockword (32-bits): This is used if only the lock bit needs to
45       touched.
46
47     mutex_lockword64 (64-bits): This is used if you need to atomically swap
48       both the lock bytes and the owner pid. Note that where the pid portion
49       is located is dependent on byte ordering.
50
51     mutex_lockbyte (8-bits): This is the actual lock byte. It is set to 1 when
52       the lock is locked, and 0 when unlocked.
53
54     mutex_waiters (8-bits): This is set to 1 when there is another thread
55       waiting and 0 when there are no other waiters.
56
57     mutex_spinners (8-bits): This byte is apparently unused. We reuse it (as
58       mutex_cond_waiters) to mark a mutex that has been unlocked by cond_wait
59       (hence it will be reacquired later).
60
61     mutex_ownerpid (32-bits):
62
63   The mutex_owner field is a 64-bit field that stores a pointer to the owning
64   thread descriptor. It is not checked in the kernel and is only cleared by
65   the kernel during cleanup.
66
67   The kernel does not handle recursive or error-checking mutexes.
68
69   The kernel does not set mutex_lockbyte for mutexes with the
70   LOCK_PRIO_INHERIT bit set.
71
72 semaphore:
73
74 condition variable:
75
76   The cond_waiters_kernel byte is set to 1 if there are waiters on the
77   condition variable and 0 otherwise. The cond_waiters_user byte is not
78   used by the kernel.
79
80   The only clock types supported are CLOCK_REALTIME and CLOCK_HIGHRES.
81
82 reader-writer lock:
83
84   The kernel only supports shared/process reader-writer locks; the private
85   rwlock implementation must be completely implemented in libc. For the shared
86   case, readercv and writercv are used to track the owner (thread and process).
87   The sun docs also state that the sun implementation favours writers over
88   readers[0].
89
90   There is no apparent advantage in using the rwlock syscalls since any
91   private implementation that used the embedded mutex and cv's would also work
92   correctly in the shared case.
93
94   Three additional fields are included for tracking the owner (thread and
95   process) of a reader-writer lock.
96
97 [0] http://docs.sun.com/app/docs/doc/819-2243/rwlock-init-3c?a=view
98
99 sysconf:
100
101   Many of the _SC_ sysconf values are obtained via the systemconf syscall. The
102   following is a table of mappings from _SC_ to _CONFIG_ values. The third
103   column lists the value returned by sysdeps/posix/sysconf.c.
104
105     _SC_CHILD_MAX           _CONFIG_CHILD_MAX           _get_child_max
106     _SC_CLK_TCK             _CONFIG_CLK_TCK             _getclktck
107     _SC_NGROUPS_MAX         _CONFIG_NGROUPS             NGROUPS_MAX
108     _SC_OPEN_MAX            _CONFIG_OPEN_FILES          __getdtablesize
109     _SC_PAGESIZE            _CONFIG_PAGESIZE            __getpagesize
110     _SC_XOPEN_VERSION       _CONFIG_XOPEN_VER           _XOPEN_VERSION
111     _SC_STREAM_MAX          _CONFIG_OPEN_FILES          STREAM_MAX
112     _SC_NPROCESSORS_CONF    _CONFIG_NPROC_CONF          __get_nprocs_conf
113     _SC_NPROCESSORS_ONLN    _CONFIG_NPROC_ONLN          __get_nprocs
114     _SC_NPROCESSORS_MAX     _CONFIG_NPROC_MAX
115     _SC_STACK_PROT          _CONFIG_STACK_PROT
116     _SC_AIO_LISTIO_MAX      _CONFIG_AIO_LISTIO_MAX      AIO_LISTIO_MAX
117     _SC_AIO_MAX             _CONFIG_AIO_MAX             AIO_MAX
118     _SC_AIO_PRIO_DELTA_MAX  _CONFIG_AIO_PRIO_DELTA_MAX  AIO_PRIO_DELTA_MAX
119     _SC_DELAYTIMER_MAX      _CONFIG_DELAYTIMER_MAX      DELAYTIMER_MAX
120     _SC_MQ_OPEN_MAX         _CONFIG_MQ_OPEN_MAX         MQ_OPEN_MAX
121     _SC_MQ_PRIO_MAX         _CONFIG_MQ_PRIO_MAX         MQ_PRIO_MAX
122     _SC_RTSIG_MAX           _CONFIG_RTSIG_MAX           RTSIG_MAX
123     _SC_SEM_NSEMS_MAX       _CONFIG_SEM_NSEMS_MAX       SEM_NSEMS_MAX
124     _SC_SEM_VALUE_MAX       _CONFIG_SEM_VALUE_MAX       SEM_VALUE_MAX
125     _SC_SIGQUEUE_MAX        _CONFIG_SIGQUEUE_MAX        SIGQUEUE_MAX
126     _SC_SIGRT_MAX           _CONFIG_SIGRT_MAX
127     _SC_SIGRT_MIN           _CONFIG_SIGRT_MIN
128     _SC_TIMER_MAX           _CONFIG_TIMER_MAX           TIMER_MAX
129     _SC_PHYS_PAGES          _CONFIG_PHYS_PAGES          __get_phys_pages
130     _SC_AVPHYS_PAGES        _CONFIG_AVPHYS_PAGES        __get_avphys_pages
131     _SC_COHER_BLKSZ         _CONFIG_COHERENCY
132     _SC_SPLIT_CACHE         _CONFIG_SPLIT_CACHE
133     _SC_ICACHE_SZ           _CONFIG_ICACHESZ
134     _SC_DCACHE_SZ           _CONFIG_DCACHESZ
135     _SC_ICACHE_LINESZ       _CONFIG_ICACHELINESZ
136     _SC_DCACHE_LINESZ       _CONFIG_DCACHELINESZ
137     _SC_ICACHE_BLKSZ        _CONFIG_ICACHEBLKSZ
138     _SC_DCACHE_BLKSZ        _CONFIG_DCACHEBLKSZ
139     _SC_DCACHE_TBLKSZ       _CONFIG_DCACHETBLKSZ
140     _SC_ICACHE_ASSOC        _CONFIG_ICACHE_ASSOC
141     _SC_DCACHE_ASSOC        _CONFIG_DCACHE_ASSOC
142     _SC_MAXPID              _CONFIG_MAXPID
143     _SC_CPUID_MAX           _CONFIG_CPUID_MAX
144     _SC_EPHID_MAX           _CONFIG_EPHID_MAX
145     _SC_SYMLOOP_MAX         _CONFIG_SYMLOOP_MAX         SYMLOOP_MAX