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 (June 2022)
  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 due
  35       to DWARF extensions ised by GCC.
  36    b) Code that uses OpenMP will generate spurious errors.
  37 2. vgdb invoker, which uses ptrace, may cause system calls to be
  38    interrupted.
  39
  40 Notes for Developers
  41 ~~~~~~~~~~~~~~~~~~~~
  42
  43 See README_DEVELOPERS, README_MISSING_SYSCALL_OR_IOCTL and docs/*
  44 for more general information for developers.
  45
  46 0. Adding syscalls.
  47
  48 When adding syscalls, you need to look at the manpage and also syscalls.master
  49 (online at
  50 https://github.com/freebsd/freebsd/blob/master/sys/kern/syscalls.master
  51 and for 32bit
  52 https://github.com/freebsd/freebsd/blob/master/sys/compat/freebsd32/syscalls.master
  53
  54 and if you installed the src package there should also be
  55
  56 /usr/src/sys/kern/syscalls.master
  57 and
  58 /usr/src/sys/compat/freebsd32/syscalls.master)
  59
  60 syscalls.master is particularly useful for seeing quickly whether parameters
  61 are inputs or outputs.
  62
  63 The syscall wrappers can vary from trivial to difficult. Fortunately, many are
  64 either trivial (no arguments) or easy (Valgrind just needs to know what memory
  65 is being read or written). Some syscalls, such as those involving process
  66 creation and termination, signals and memory mapping require deeper interaction
  67 with Valgrind.
  68
  69 When you add syscalls you will need to modify several files
  70    a) include/vki/vki-scnums-freebsd.h
  71       This file contains one #define for each syscall. The _NR_ prefix (Linux
  72       style) is used rather than SYS_ for compatibility with the rest of the
  73       Valgrind source.
  74    b) coregrind/m_syswrap/priv_syswrap-freebsd.h
  75       This uses the DECL_TEMPLATE macro to generate declarations for the syscall
  76       before and after wrappers.
  77    c) coregrind/m_syswrap/syswrap-freebsd.c
  78       This is where the bulk of the code resides. Toward the end of the file
  79       the BSDX_/BSDXY macros are used to generate entries in the table of
  80       syscalls. BSDX_ is used for wrappers that only have a 'before', BSDXY
  81       if both wrappers are required. In general, syscalls that have no arguments
  82       or only input arguments just need a BSDX_ macro (before only). Syscalls
  83       with output arguments need a BSDXY macro (before and after).
  84    d) If the syscall uses 64bit arguments (long long) then instead of putting
  85       the wrapper definitions in syswrap-freebsd.c there will be one definition
  86       for each platform amd64 and x86 in syswrap-x86-freebsd.c and
  87       syswrap-amd64-freebsd.c.
  88       Each long long needs to be split into two ARGs in the x86 version.
  89
  90 The PRE (before) wrapper
  91 ------------------------
  92
  93 Each PRE wrapper always contains the following two macro calls
  94
  95 PRINT. This outputs the syscall name and argument values when Valgrind is
  96 executed with
  97 --trace-syscalls=yes
  98
  99 PRE_READ_REGX. This macro lets Valgrind know about the number and types of the
 100 syscall arguments which allows Valgrind to check that they are initialized.
 101 X is the number of arguments. It is best that the argument names match
 102 the man page, but the must match the types and number of arguments in
 103 syscalls.master.
 104 Occasionally there are differences between the two.
 105
 106 If the syscall takes pointers to memory there will be one of the following for
 107 each pointer argument.
 108
 109 PRE_MEM_RASCIIZ for NULL terminated ascii strings.
 110
 111 PRE_MEM_READ for pointers to structures or arrays that are read.
 112
 113 PRE_MEM_WRITE for pointers to structures or arrays that are written.
 114
 115 As a rule, the definitions of structures are copied into vki-freebsd.h
 116 with the vki- prefix. [vki - Valgrind kernel interface; this was done
 117 historically to protect against discrepancies between user include
 118 structure definitions and kernel definitions on Linux].
 119
 120 The POST (after) wrapper
 121 ------------------------
 122
 123 These are much easier.
 124
 125 They just contain a POST_MEM_WRITE macro for each output argument.
 126
 127 1. Running regression tests
 128
 129 In order to run all of the regression tests you will need to install
 130 the following packages
 131 gdb
 132 gsed
 133
 134 In addition to running "make" you will need to run
 135 "make check" to build the regression test exectutables
 136 and "make regtest".  Again, more details can be seen in
 137 README_DEVELOPERS.
 138
 139 If you want to run the 'nightly' script (see nightly/README.txt)
 140 you will need to install coreutils and modify the
 141 nightly/conf/freebsd.* files. The default configuration
 142 sends an e-mail to the valgrind-testresults mailing list.
 143
 144 Feedback
 145 ~~~~~~~~
 146
 147 If you find any problems please create a bugzilla report at
 148 https://bugs.kde.org using the Valgrind product.
 149
 150 Alternatively you can use the FreeBSD bugilla
 151 https://bugs.freebsd.org
 152
 153 Credits
 154 ~~~~~~~
 155
 156 Valgrind was originally ported to FreeBSD by Doug Rabson
 157 in 2004.
 158
 159 Paul Floyd (that's me), started looking at this project in late 2018,
 160 took a long pause and then continued in earnest in January 2020.
 161
 162 A big thanks to Nick Briggs for helping with the x86 version.
 163
 164 Kyle Evans and Ed Maste for contributing patches and helping with the
 165 integration with FreeBSD ports.
 166
 167 Prior to 2018 many others have also contributed.
 168
 169 Dimitry Andric
 170 Simon Barner
 171 Roman Bogorodskiy
 172 Rebecca Cran
 173 Bryan Drewery
 174 Brian Fundakowski Feldman
 175 Denis Generalov
 176 Mikolaj Golub
 177 Eugene Kilachkoff
 178 Xin LI
 179 Phil Longstaff
 180 Pav Lucistnik
 181 Conrad Meyer
 182 Julien Nadeau
 183 Frerich Raabe
 184 Doug Rabson
 185 Craig Rodrigues
 186 Tom Russo
 187 Stephen Sanders
 188 Stanislav Sedov
 189 Andrei V. Shetuhin
 190 Niklas Sorensson
 191 Ryan Stone
 192 Jerry Toung
 193 Yuri
 194