1Requirements
2------------
3- You need a recent Solaris-like OS to compile this port. Solaris 11 or
4  any illumos-based distribution should work, Solaris 10 is not supported.
5  Running `uname -r` has to print '5.11'.
6- Recent GCC tools are required, GCC 3 will probably not work. GCC version
7  4.5 (or higher) is recommended.
8- Solaris ld has to be the first linker in the PATH. GNU ld cannot be used.
9  There is currently no linker check in the configure script but the linking
10  phase fails if GNU ld is used. Recent Solaris/illumos distributions are ok.
11- A working combination of autotools is required: aclocal, autoheader,
12  automake and autoconf have to be found in the PATH. You should be able to
13  install pkg:/developer/build/automake and pkg:/developer/build/autoconf
14  packages to fulfil this requirement.
15- System header files are required. On Solaris, these can be installed with:
16    # pkg install system/header
17- GNU make is also required. On Solaris, this can be quickly achieved with:
18    $ PATH=/usr/gnu/bin:$PATH; export PATH
19- For remote debugging support, working GDB is required (see below).
20- For running regression tests, GNU sed, grep, awk, diff are required.
21  This can be quickly achieved on Solaris by prepending /usr/gnu/bin to PATH.
22
23
24Compilation
25-----------
26Please follow the generic instructions in the README file.
27
28The configure script detects a canonical host to determine which version of
29Valgrind should be built. If the system compiler by default produces 32-bit
30binaries then only a 32-bit version of Valgrind will be built. To enable
31compilation of both 64-bit and 32-bit versions on such a system, issue the
32configure script as follows:
33./configure CC='gcc -m64' CXX='g++ -m64'
34
35
36Oracle Solaris and illumos support
37----------------------------------
38One of the main goal of this port is to support both Oracle Solaris and
39illumos kernels. This is a very hard task because Solaris kernel traditionally
40does not provide a stable syscall interface and because Valgrind contains
41several parts that are closely tied to the underlying kernel. For these
42reasons, the port needs to detect which syscall interfaces are present. This
43detection cannot be done easily at run time and is currently implemented as
44a set of configure tests. This means that a binary version of this port can be
45executed only on a kernel that is compatible with a kernel that was used
46during the configure and compilation time.
47
48Main currently-known incompatibilities:
49- Solaris 11 (released in November 2011) removed a large set of syscalls where
50  *at variant of the syscall was also present, for example, open() versus
51  openat(AT_FDCWD) [1]
52- syscall number for unlinkat() is 76 on Solaris 11, but 65 on illumos [2]
53- illumos (in April 2013) changed interface of the accept() and pipe()
54  syscalls [3]
55- posix_spawn() functionality is backed up by true spawn() syscall on Solaris 12
56  whereas illumos and Solaris 11 leverage vfork()
57- illumos and older Solaris use utimesys() syscall whereas newer Solaris
58  uses utimensat()
59
60[1] http://docs.oracle.com/cd/E26502_01/html/E28556/gkzlf.html#gkzip
61[2] https://www.illumos.org/issues/521
62[3] https://github.com/illumos/illumos-gate/commit/5dbfd19ad5fcc2b779f40f80fa05c1bd28fd0b4e
63
64
65Limitations
66-----------
67- The port is Work-In-Progress, many things may not work or they can be subtly
68  broken.
69- Coredumps produced by Valgrind do not contain all information available,
70  especially microstate accounting and processor bindings.
71- Accessing contents of /proc/self/psinfo is not thread-safe.  That is because
72  Valgrind emulates this file on behalf of the client programs.  Entire
73  open() - read() - close() sequence on this file needs to be performed
74  atomically.
75- Fork limitations: vfork() is translated to fork(), forkall() is not
76  supported.
77- Valgrind does not track definedness of some eflags (OF, SF, ZF, AF, CF, PF)
78  individually for each flag. After a syscall is finished, when a carry flag
79  is set and defined, all other mentioned flags will be also defined even
80  though they might be undefined before making the syscall.
81- System call "execve" with a file descriptor which points to a hardlink
82  is currently not supported. That is because from the opened file descriptor
83  itself it is not possible to reverse map the intended pathname.
84  Examples are fexecve(3C) and isaexec(3C).
85- Program headers PT_SUNW_SYSSTAT and PT_SUNW_SYSSTAT_ZONE are not supported.
86  That is, programs linked with mapfile directive RESERVE_SEGMENT and attribute
87  TYPE equal to SYSSTAT or SYSSTAT_ZONE will cause Valgrind exit. It is not
88  possible for Valgrind to arrange mapping of a kernel shared page at the
89  address specified in the mapfile for the guest application. There is currently
90  no such mechanism in Solaris. Hacky workarounds are possible, though.
91- When a thread has no stack then all system calls will result in Valgrind
92  crash, even though such system calls use just parameters passed in registers.
93  This should happen only in pathological situations when a thread is created
94  with custom mmap'ed stack and this stack is then unmap'ed during thread
95  execution.
96
97
98Remote debugging support
99------------------------
100Solaris port of GDB has a major flaw which prevents remote debugging from
101working correctly. Fortunately this flaw has an easy fix [4]. Unfortunately
102it is not present in the current GDB 7.6.2. This boils down to several
103options:
104- Use GDB shipped with Solaris 11.2 which has this flaw fixed.
105- Wait until GDB 7.7 becomes available (there won't be other 7.6.x releases).
106- Build GDB 7.6.2 with the fix by yourself using the following steps:
107    # pkg install developer/gnu-binutils
108    $ wget http://ftp.gnu.org/gnu/gdb/gdb-7.6.2.tar.gz
109    $ gzip -dc gdb-7.6.2.tar.gz | tar xf -
110    $ cd gdb-7.6.2
111    $ patch -p1 -i /path/to/valgrind-solaris/solaris/gdb-sol-thread.patch
112    $ export LIBS="-lncurses"
113    $ export CC="gcc -m64"
114    $ ./configure --with-x=no --with-curses --with-libexpat-prefix=/usr/lib
115    $ gmake && gmake install
116
117[4] https://sourceware.org/ml/gdb-patches/2013-12/msg00573.html
118
119
120TODO list
121---------
122- Fix few remaining failing tests.
123- Add more Solaris-specific tests (especially for the door and spawn
124  syscalls).
125- Provide better error reporting for various subsyscalls.
126- Implement storing of extra register state in signal frame.
127- Performance comparison against other platforms.
128- Prevent SIGPIPE when writing to a socket (coregrind/m_libcfile.c).
129- Implement ticket locking for fair scheduling (--fair-sched=yes).
130- Implement support in DRD and Helgrind tools for thr_join() with thread == 0.
131- Add support for accessing thread-local variables via gdb (auxprogs/getoff.c).
132  Requires research on internal libc TLS representation.
133- VEX supports AVX, BMI and AVX2. Investigate if they can be enabled on
134  Solaris/illumos.
135- Investigate support for more flags in AT_SUN_AUXFLAGS.
136- Fix Valgrind crash when a thread has no stack and syswrap-main.c accesses
137  all possible syscall parameters. Enable helgrind/tests/stackteardown.c
138  to see this in effect. Would require awareness of syscall parameter semantics.
139- Correctly print arguments of DW_CFA_ORCL_arg_loc in show_CF_instruction() when
140  it is implemented in libdwarf.
141- Handle a situation when guest program sets SC_CANCEL_FLG in schedctl and
142  Valgrind needs to invoke a syscall on its own.
143
144
145Contacts
146--------
147Please send bug reports and any questions about the port to:
148Ivo Raisr <ivosh@ivosh.net>
149Petr Pavlu <setup@dagobah.cz>
150