README.solaris

   1 Requirements
   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
  24 Compilation
  25 -----------
  26 Please follow the generic instructions in the README file,
  27 in the section 'Building and installing it'.
  28
  29 The configure script detects a canonical host to determine which version of
  30 Valgrind should be built. If the system compiler by default produces 32-bit
  31 binaries then only a 32-bit version of Valgrind will be built. To enable
  32 compilation of both 64-bit and 32-bit versions on such a system, issue the
  33 configure script as follows:
  34 ./configure CC='gcc -m64' CXX='g++ -m64'
  35
  36
  37 Oracle Solaris and illumos support
  38 ----------------------------------
  39 One of the main goal of this port is to support both Oracle Solaris and
  40 illumos kernels. This is a very hard task because Solaris kernel traditionally
  41 does not provide a stable syscall interface and because Valgrind contains
  42 several parts that are closely tied to the underlying kernel. For these
  43 reasons, the port needs to detect which syscall interfaces are present. This
  44 detection cannot be done easily at run time and is currently implemented as
  45 a set of configure tests. This means that a binary version of this port can be
  46 executed only on a kernel that is compatible with a kernel that was used
  47 during the configure and compilation time.
  48
  49 Main currently-known incompatibilities:
  50 - Solaris 11 (released in November 2011) removed a large set of syscalls where
  51   *at variant of the syscall was also present, for example, open() versus
  52   openat(AT_FDCWD) [1]
  53 - syscall number for unlinkat() is 76 on Solaris 11, but 65 on illumos [2]
  54 - illumos (in April 2013) changed interface of the accept() and pipe()
  55   syscalls [3]
  56 - posix_spawn() functionality is backed up by true spawn() syscall on Solaris 11.4
  57   whereas illumos and Solaris 11.3 leverage vfork()
  58 - illumos and older Solaris use utimesys() syscall whereas newer Solaris
  59   uses utimensat()
  60
  61 [1] http://docs.oracle.com/cd/E26502_01/html/E28556/gkzlf.html#gkzip
  62 [2] https://www.illumos.org/issues/521
  63 [3] https://github.com/illumos/illumos-gate/commit/5dbfd19ad5fcc2b779f40f80fa05c1bd28fd0b4e
  64
  65
  66 Limitations
  67 -----------
  68 - The port is Work-In-Progress, many things may not work or they can be subtly
  69   broken.
  70 - Coredumps produced by Valgrind do not contain all information available,
  71   especially microstate accounting and processor bindings.
  72 - Accessing contents of /proc/self/psinfo is not thread-safe.  That is because
  73   Valgrind emulates this file on behalf of the client programs.  Entire
  74   open() - read() - close() sequence on this file needs to be performed
  75   atomically.
  76 - Fork limitations: vfork() is translated to fork(), forkall() is not
  77   supported.
  78 - Valgrind does not track definedness of some eflags (OF, SF, ZF, AF, CF, PF)
  79   individually for each flag. After a syscall is finished, when a carry flag
  80   is set and defined, all other mentioned flags will be also defined even
  81   though they might be undefined before making the syscall.
  82 - System call "execve" with a file descriptor which points to a hardlink
  83   is currently not supported. That is because from the opened file descriptor
  84   itself it is not possible to reverse map the intended pathname.
  85   Examples are fexecve(3C) and isaexec(3C).
  86 - Program headers PT_SUNW_SYSSTAT and PT_SUNW_SYSSTAT_ZONE are not supported.
  87   That is, programs linked with mapfile directive RESERVE_SEGMENT and attribute
  88   TYPE equal to SYSSTAT or SYSSTAT_ZONE will cause Valgrind exit. It is not
  89   possible for Valgrind to arrange mapping of a kernel shared page at the
  90   address specified in the mapfile for the guest application. There is currently
  91   no such mechanism in Solaris. Hacky workarounds are possible, though.
  92 - When a thread has no stack then all system calls will result in Valgrind
  93   crash, even though such system calls use just parameters passed in registers.
  94   This should happen only in pathological situations when a thread is created
  95   with custom mmap'ed stack and this stack is then unmap'ed during thread
  96   execution.
  97
  98
  99 Remote debugging support
 100 ------------------------
 101 Solaris port of GDB has a major flaw which prevents remote debugging from
 102 working correctly. Fortunately this flaw has an easy fix [4]. Unfortunately
 103 it is not present in the current GDB 7.6.2. This boils down to several
 104 options:
 105 - Use GDB shipped with Solaris 11.2 which has this flaw fixed.
 106 - Wait until GDB 7.7 becomes available (there won't be other 7.6.x releases).
 107 - Build GDB 7.6.2 with the fix by yourself using the following steps:
 108     # pkg install developer/gnu-binutils
 109     $ wget http://ftp.gnu.org/gnu/gdb/gdb-7.6.2.tar.gz
 110     $ gzip -dc gdb-7.6.2.tar.gz | tar xf -
 111     $ cd gdb-7.6.2
 112     $ patch -p1 -i /path/to/valgrind-solaris/solaris/gdb-sol-thread.patch
 113     $ export LIBS="-lncurses"
 114     $ export CC="gcc -m64"
 115     $ ./configure --with-x=no --with-curses --with-libexpat-prefix=/usr/lib
 116     $ gmake && gmake install
 117
 118 [4] https://sourceware.org/ml/gdb-patches/2013-12/msg00573.html
 119
 120
 121 TODO list
 122 ---------
 123 - Fix few remaining failing tests.
 124 - Add more Solaris-specific tests (especially for the door and spawn
 125   syscalls).
 126 - Provide better error reporting for various subsyscalls.
 127 - Implement storing of extra register state in signal frame.
 128 - Performance comparison against other platforms.
 129 - Prevent SIGPIPE when writing to a socket (coregrind/m_libcfile.c).
 130 - Implement ticket locking for fair scheduling (--fair-sched=yes).
 131 - Implement support in DRD and Helgrind tools for thr_join() with thread == 0.
 132 - Add support for accessing thread-local variables via gdb (auxprogs/getoff.c).
 133   Requires research on internal libc TLS representation.
 134 - VEX supports AVX, BMI and AVX2. Investigate if they can be enabled on
 135   Solaris/illumos.
 136 - Investigate support for more flags in AT_SUN_AUXFLAGS.
 137 - Fix Valgrind crash when a thread has no stack and syswrap-main.c accesses
 138   all possible syscall parameters. Enable helgrind/tests/stackteardown.c
 139   to see this in effect. Would require awareness of syscall parameter semantics.
 140 - Correctly print arguments of DW_CFA_ORCL_arg_loc in show_CF_instruction() when
 141   it is implemented in libdwarf.
 142 - Handle a situation when guest program sets SC_CANCEL_FLG in schedctl and
 143   Valgrind needs to invoke a syscall on its own.
 144
 145
 146 Summary of Solaris 11 Kernel Interfaces Used
 147 --------------------------------------------
 148 Valgrind uses directly the following kernel interfaces (not exhaustive list).
 149 Then, of course, it has very intimate knowledge of all syscalls, many ioctls
 150 and some door calls because it has wrappers around them.
 151 - Syscalls:
 152   . clock_gettime
 153   . close
 154   . connect
 155   . execve
 156   . exit
 157   . faccessat
 158   . fcntl
 159   . forksys
 160   . fstatat
 161   . getcwd
 162   . getdents
 163   . geteuid
 164   . getgid
 165   . getgroups
 166   . getpeername
 167   . getpid
 168   . getrlimit
 169   . getsockname
 170   . getsockopt
 171   . gettimeofday
 172   . kill
 173   . lseek
 174   . lwp_create
 175   . lwp_exit
 176   . lwp_self
 177   . lwp_sigqueue
 178   . mknodat
 179   . mmap
 180   . mprotect
 181   . munmap
 182   . openat
 183   . pipe
 184   . pollsys
 185   . pread
 186   . prgpsys
 187   . pwrite
 188   . read
 189   . readlinkat
 190   . renameat
 191   . rt_sigprocmask
 192   . send
 193   . setrlimit
 194   . setsockopt
 195   . sigaction
 196   . sigreturn
 197   . sigtimedwait
 198   . so_socket
 199   . spawn
 200   . uname
 201   . unlinkat
 202   . waitsys
 203   . write
 204 - Signal frames. Valgrind decomposes and synthetizes signal frames.
 205 - Flag sc_sigblock flag in the schedctl structure by replacing
 206   function block_all_signals() from libc. The replacement emulates lwp_sigmask
 207   syscall. More details in coregrind/vg_preloaded.c.
 208 - Initial stack layout for the main thread is synthetized.
 209 - procfs agent thread and other procfs commands for manipulating the process.
 210 - mmapobj syscall is emulated because it gets in the way of the address space
 211   manager's control.
 212
 213
 214 Contacts
 215 --------
 216 Please send bug reports and any questions about the port to:
 217 Ivo Raisr <ivosh@ivosh.net>
 218 Petr Pavlu <setup@dagobah.cz>