README.freebsd

   1 Installing from ports or via pkg
   2 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   3
   4 If you are using FreeBSD 11.3 or later, then you should be able to install
   5 Valgrind using either
   6
   7 pkg install devel/valgrind
   8
   9 or alternatively from ports (if installed)
  10
  11 cd /usr/ports/devel/valgrind && make install clean
  12
  13
  14 Building Valgrind
  15 ~~~~~~~~~~~~~~~~~
  16
  17 Install ports for autoconf, automake, libtool and gmake.
  18
  19 $ sh autogen.sh
  20 $ ./configure --prefix=/where/ever
  21 $ gmake
  22 $ gmake install
  23
  24 Known Limitations (December 2020)
  25
  26 0. Be aware that if you use a wrapper script and run Valgrind on the wrapper
  27    script Valgrind may hit restrictions if the wrapper script runs any
  28    Capsicum enabled applications. Examples of Capsicum enabled applications
  29    are echo, basename, tee, uniq and wc. It is recommended that you either
  30    avoid these applications or that you run Valgrind directly on your test
  31    application.
  32 1. There are some limitations when running Valgrind on code that was compiled
  33    with clang.  These issues are not present with code compiled with GCC.
  34    a) There may be missing source information concerning variables.
  35    b) The client request mechanism may not work entirely correctly.
  36    c) Code that uses OpenMP will generate spurious errors.
  37 2. There are some limitations specific to i386
  38    a) In some cases signals are mishandled causing Valgrind to terminate and
  39       report a SIGSEGV.
  40    b) Applications that create and join many threads may crash.
  41
  42 Notes for Developers
  43 ~~~~~~~~~~~~~~~~~~~~
  44
  45 See README_DEVELOPERS, README_MISSING_SYSCALL_OR_IOCTL and docs/*
  46 for more general information for developers.
  47
  48 0. Adding syscalls.
  49
  50 When adding syscalls, you need to look at the manpage and also syscalls.master
  51 (online at
  52 https://github.com/freebsd/freebsd/blob/master/sys/kern/syscalls.master
  53 and for 32bit
  54 https://github.com/freebsd/freebsd/blob/master/sys/compat/freebsd32/syscalls.master
  55
  56 and if you installed the src package there should also be
  57
  58 /usr/src/sys/kern/syscalls.master
  59 and
  60 /usr/src/sys/compat/freebsd32/syscalls.master)
  61
  62 syscalls.master is particularly useful for seeing quickly whether parameters
  63 are inputs or outputs.
  64
  65 The syscall wrappers can vary from trivial to difficult. Fortunately, many are
  66 either trivial (no arguments) or easy (Valgrind just needs to know what memory
  67 is being read or written). Some syscalls, such as those involving process
  68 creation and termination, signals and memory mapping require deeper interaction
  69 with Valgrind.
  70
  71 When you add syscalls you will need to modify several files
  72    a) include/vki/vki-scnums-freebsd.h
  73       This file contains one #define for each syscall. The _NR_ prefix (Linux
  74       style) is used rather than SYS_ for compatibility with the rest of the
  75       Valgrind source.
  76    b) coregrind/m_syswrap/priv_syswrap-freebsd.h
  77       This uses the DECL_TEMPLATE macro to generate declarations for the syscall
  78       before and after wrappers.
  79    c) coregrind/m_syswrap/syswrap-freebsd.c
  80       This is where the bulk of the code resides. Toward the end of the file
  81       the BSDX_/BSDXY macros are used to generate entries in the table of
  82       syscalls. BSDX_ is used for wrappers that only have a 'before', BSDXY
  83       if both wrappers are required. In general, syscalls that have no arguments
  84       or only input arguments just need a BSDX_ macro (before only). Syscalls
  85       with output arguments need a BSDXY macro (before and after).
  86    d) If the syscall uses 64bit arguments (long long) then instead of putting
  87       the wrapper definitions in syswrap-freebsd.c there will be one definition
  88       for each platform amd64 and x86 in syswrap-x86-freebsd.c and
  89       syswrap-amd64-freebsd.c.
  90       Each long long needs to be split into two ARGs in the x86 version.
  91
  92 The PRE (before) wrapper
  93 ------------------------
  94
  95 Each PRE wrapper always contains the following two macro calls
  96
  97 PRINT. This outputs the syscall name and argument values when Valgrind is
  98 executed with
  99 --trace-syscalls=yes
 100
 101 PRE_READ_REGX. This macro lets Valgrind know about the number and types of the
 102 syscall arguments which allows Valgrind to check that they are initialized.
 103 X is the number of arguments. It is best that the argument names match
 104 the man page, but the must match the types and number of arguments in
 105 syscalls.master.
 106 Occasionally there are differences between the two.
 107
 108 If the syscall takes pointers to memory there will be one of the following for
 109 each pointer argument.
 110
 111 PRE_MEM_RASCIIZ for NULL terminated ascii strings.
 112
 113 PRE_MEM_READ for pointers to structures or arrays that are read.
 114
 115 PRE_MEM_WRITE for pointers to structures or arrays that are written.
 116
 117 As a rule, the definitions of structures are copied into vki-freebsd.h
 118 with the vki- prefix. [vki - Valgrind kernel interface; this was done
 119 historically to protect against discrepancies between user include
 120 structure definitions and kernel definitions on Linux].
 121
 122 The POST (after) wrapper
 123 ------------------------
 124
 125 These are much easier.
 126
 127 They just contain a POST_MEM_WRITE macro for each output argument.
 128
 129
 130 Feedback
 131 ~~~~~~~~
 132
 133 If you find any problems please create a bugzilla report at
 134 https://bugs.kde.org using the Valgrind product.
 135
 136 Alternatively you can use the FreeBSD bugilla
 137 https://bugs.freebsd.org
 138
 139 Credits
 140 ~~~~~~~
 141
 142 Valgrind was originally ported to FreeBSD by Doug Rabson
 143 in 2004.
 144
 145 Paul Floyd (that's me), started looking at this project in late 2018,
 146 took a long pause and then continued in earnest in January 2020.
 147
 148 A big thanks to Nick Briggs for helping with the x86 version.
 149
 150 Kyle Evans and Ed Maste for contributing patches and helping with the
 151 integration with FreeBSD ports.
 152
 153 Prior to 2018 many others have also contributed.
 154
 155 Dimitry Andric
 156 Simon Barner
 157 Roman Bogorodskiy
 158 Rebecca Cran
 159 Bryan Drewery
 160 Brian Fundakowski Feldman
 161 Denis Generalov
 162 Mikolaj Golub
 163 Eugene Kilachkoff
 164 Xin LI
 165 Phil Longstaff
 166 Pav Lucistnik
 167 Conrad Meyer
 168 Julien Nadeau
 169 Frerich Raabe
 170 Doug Rabson
 171 Craig Rodrigues
 172 Tom Russo
 173 Stephen Sanders
 174 Stanislav Sedov
 175 Andrei V. Shetuhin
 176 Niklas Sorensson
 177 Ryan Stone
 178 Jerry Toung
 179 Yuri
 180