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