1 Installing from ports or via pkg
2 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4 If you are using FreeBSD 11.3 or later, then you should be able to install
7 pkg install devel/valgrind
9 or alternatively from ports (if installed)
11 cd /usr/ports/devel/valgrind && make install clean
17 Install ports for autotools, gmake and python.
20 $ ./configure --prefix=/where/ever
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).
28 Known Limitations (June 2022)
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
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
50 See README_DEVELOPERS, README_MISSING_SYSCALL_OR_IOCTL and docs/*
51 for more general information for developers.
55 When adding syscalls, you need to look at the manpage and also syscalls.master
57 https://github.com/freebsd/freebsd/blob/master/sys/kern/syscalls.master
59 https://github.com/freebsd/freebsd/blob/master/sys/compat/freebsd32/syscalls.master
61 and if you installed the src package there should also be
63 /usr/src/sys/kern/syscalls.master
65 /usr/src/sys/compat/freebsd32/syscalls.master)
67 syscalls.master is particularly useful for seeing quickly whether parameters
68 are inputs or outputs.
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
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
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.
97 The PRE (before) wrapper
98 ------------------------
100 Each PRE wrapper always contains the following two macro calls
102 PRINT. This outputs the syscall name and argument values when Valgrind is
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.
112 If the syscall takes pointers to memory there will be one of the following for
113 each pointer argument.
115 PRE_MEM_RASCIIZ for NULL terminated ascii strings.
117 PRE_MEM_READ for pointers to structures or arrays that are read.
119 PRE_MEM_WRITE for pointers to structures or arrays that are written.
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].
126 The POST (after) wrapper
127 ------------------------
129 These are much easier.
131 They just contain a POST_MEM_WRITE macro for each output argument.
133 1. Frequent causes of problems
135 - New _umtx_op codes. Valgrind will print "WARNING: _umtx_op unsupported value".
136 See syswrap-freebsd.c and add new cases for the new codes.
137 - Additions to auxv. Depending on the entry it may need to be simply copied
138 from the host to the guest, it may need to be modified for the guest or
139 it may need to be ignored. See initimg-freebsd.c.
140 - ELF PT_LOAD mappings. Either Valgrind will assert or there will be no source
141 information in error reports. See VG_(di_notify_mmap) in debuginfo.c
142 - Because they contain many deliberate errors the regression tests are prone
143 to change with changes of compiler. Liberal use of 'volatile' and
144 '-Wno-warning-flag' can help - see configure.ac
146 2. Running regression tests
148 In order to run all of the regression tests you will need to install
149 the following packages
153 In addition to running "gmake" you will need to run
154 "gmake check" to build the regression test exectutables
155 and "gmake regtest". Again, more details can be seen in
158 If you want to run the 'nightly' script (see nightly/README.txt)
159 you will need to install coreutils (for GNU cp) and modify the
160 nightly/conf/freebsd.* files. The default configuration
161 sends an e-mail to the valgrind-testresults mailing list.
166 If you find any problems please create a bugzilla report at
167 https://bugs.kde.org using the Valgrind product.
169 Alternatively you can use the FreeBSD bugilla
170 https://bugs.freebsd.org
175 Valgrind was originally ported to FreeBSD by Doug Rabson
178 Paul Floyd (that's me), started looking at this project in late 2018,
179 took a long pause and then continued in earnest in January 2020.
181 A big thanks to Nick Briggs for helping with the x86 version.
183 Kyle Evans and Ed Maste for contributing patches and helping with the
184 integration with FreeBSD ports.
186 Prior to 2018 many others have also contributed.
193 Brian Fundakowski Feldman