1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>13. README.freebsd</title>
<link rel="stylesheet" type="text/css" href="vg_basic.css">
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
<link rel="home" href="index.html" title="Valgrind Documentation">
<link rel="up" href="dist.html" title="Valgrind Distribution Documents">
<link rel="prev" href="dist.readme-solaris.html" title="12. README.solaris">
<link rel="next" href="licenses.html" title="GNU Licenses">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div><table class="nav" width="100%" cellspacing="3" cellpadding="3" border="0" summary="Navigation header"><tr>
<td width="22px" align="center" valign="middle"><a accesskey="p" href="dist.readme-solaris.html"><img src="images/prev.png" width="18" height="21" border="0" alt="Prev"></a></td>
<td width="25px" align="center" valign="middle"><a accesskey="u" href="dist.html"><img src="images/up.png" width="21" height="18" border="0" alt="Up"></a></td>
<td width="31px" align="center" valign="middle"><a accesskey="h" href="index.html"><img src="images/home.png" width="27" height="20" border="0" alt="Up"></a></td>
<th align="center" valign="middle">Valgrind Distribution Documents</th>
<td width="22px" align="center" valign="middle"><a accesskey="n" href="licenses.html"><img src="images/next.png" width="18" height="21" border="0" alt="Next"></a></td>
</tr></table></div>
<div class="chapter">
<div class="titlepage"><div><div><h1 class="title">
<a name="dist.readme-freebsd"></a>13. README.freebsd</h1></div></div></div>
<div class="literallayout"><p><br>
Installing from ports or via pkg<br>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br>
<br>
You can install Valgrind using either<br>
<br>
pkg install devel/valgrind<br>
<br>
or alternatively from ports (if installed)<br>
<br>
cd /usr/ports/devel/valgrind && make install clean<br>
<br>
devel/valgrind is updated with official releases of Valgrind, normally<br>
in April and October each year. There is an alternative port,<br>
devel/valgrind-devel which occasionally gets updated from the latest<br>
Valgrind source. If you want to have the latest port, check on<br>
https://www.freshports.org/ to see which is the most recent. If you<br>
want to have the very latest version, you will need to build a copy<br>
from source. See README for instructions on getting the source with git.<br>
<br>
<br>
Building Valgrind<br>
~~~~~~~~~~~~~~~~~<br>
<br>
Install ports for autotools, gmake and python.<br>
<br>
$ sh autogen.sh<br>
$ ./configure --prefix=/where/ever<br>
$ gmake<br>
$ gmake install<br>
<br>
If you are using a jail for building, make sure that it is configured so that<br>
"uname -r" returns a string that matches the pattern "XX.Y-*" where XX is the<br>
major version (12, 13, 14 ...) and Y is the minor version (0, 1, 2, 3).<br>
<br>
Known Limitations (June 2022)<br>
<br>
0. Be aware that if you use a wrapper script and run Valgrind on the wrapper<br>
script Valgrind may hit restrictions if the wrapper script runs any<br>
Capsicum enabled applications. Examples of Capsicum enabled applications<br>
are echo, basename, tee, uniq and wc. It is recommended that you either<br>
avoid these applications or that you run Valgrind directly on your test<br>
application.<br>
1. There are some limitations when running Valgrind on code that was compiled<br>
with clang. These issues are not present with code compiled with GCC.<br>
a) There may be missing source information concerning variables due<br>
to DWARF extensions used by GCC.<br>
b) Code that uses OpenMP will generate spurious errors.<br>
2. vgdb invoker, which uses ptrace, may cause system calls to be<br>
interrupted. As an example, if the debuggee seems to have be<br>
stuck and you press Ctrl-C in gdb the debuggee may execute<br>
one more statement before stopping and returning control to<br>
gdb.<br>
<br>
Notes for Developers<br>
~~~~~~~~~~~~~~~~~~~~<br>
<br>
See README_DEVELOPERS, README_MISSING_SYSCALL_OR_IOCTL and docs/*<br>
for more general information for developers.<br>
<br>
0. Adding syscalls.<br>
<br>
When adding syscalls, you need to look at the manpage and also syscalls.master<br>
(online at<br>
https://github.com/freebsd/freebsd/blob/master/sys/kern/syscalls.master<br>
and for 32bit<br>
https://github.com/freebsd/freebsd/blob/master/sys/compat/freebsd32/syscalls.master<br>
<br>
and if you installed the src package there should also be<br>
<br>
/usr/src/sys/kern/syscalls.master<br>
and<br>
/usr/src/sys/compat/freebsd32/syscalls.master)<br>
<br>
syscalls.master is particularly useful for seeing quickly whether parameters<br>
are inputs or outputs.<br>
<br>
The syscall wrappers can vary from trivial to difficult. Fortunately, many are<br>
either trivial (no arguments) or easy (Valgrind just needs to know what memory<br>
is being read or written). Some syscalls, such as those involving process<br>
creation and termination, signals and memory mapping require deeper interaction<br>
with Valgrind.<br>
<br>
When you add syscalls you will need to modify several files<br>
a) include/vki/vki-scnums-freebsd.h<br>
This file contains one #define for each syscall. The _NR_ prefix (Linux<br>
style) is used rather than SYS_ for compatibility with the rest of the<br>
Valgrind source.<br>
b) coregrind/m_syswrap/priv_syswrap-freebsd.h<br>
This uses the DECL_TEMPLATE macro to generate declarations for the syscall<br>
before and after wrappers.<br>
c) coregrind/m_syswrap/syswrap-freebsd.c<br>
This is where the bulk of the code resides. Toward the end of the file<br>
the BSDX_/BSDXY macros are used to generate entries in the table of<br>
syscalls. BSDX_ is used for wrappers that only have a 'before', BSDXY<br>
if both wrappers are required. In general, syscalls that have no arguments<br>
or only input arguments just need a BSDX_ macro (before only). Syscalls<br>
with output arguments need a BSDXY macro (before and after).<br>
d) If the syscall uses 64bit arguments (long long) then instead of putting<br>
the wrapper definitions in syswrap-freebsd.c there will be two kinds of<br>
definition. A 32bit version with split 64bit arguments for x86 in<br>
syswrap-x86-freebsd.c and 64bit versions without any splitting for amd64<br>
and arm64 in syswrap-amd64-freebsd.c/syswrap-arm64-freebsd.c.<br>
Each long long needs to be split into two ARGs in the x86 version.<br>
<br>
The PRE (before) wrapper<br>
------------------------<br>
<br>
Each PRE wrapper always contains the following two macro calls<br>
<br>
PRINT. This outputs the syscall name and argument values when Valgrind is<br>
executed with<br>
--trace-syscalls=yes<br>
<br>
PRE_READ_REGX. This macro lets Valgrind know about the number and types of the<br>
syscall arguments which allows Valgrind to check that they are initialized.<br>
X is the number of arguments. It is best that the argument names match<br>
the man page, but they must match the types and number of arguments in<br>
syscalls.master. Occasionally there are differences between the two.<br>
<br>
If the syscall takes pointers to memory there will be one of the following for<br>
each pointer argument.<br>
<br>
PRE_MEM_RASCIIZ for NULL terminated ascii strings.<br>
<br>
PRE_MEM_READ for pointers to structures or arrays that are read.<br>
<br>
PRE_MEM_WRITE for pointers to structures or arrays that are written.<br>
<br>
As a rule, the definitions of structures are copied into vki-freebsd.h<br>
with the vki- prefix. [vki - Valgrind kernel interface; this was done<br>
historically to protect against discrepancies between user include<br>
structure definitions and kernel definitions on Linux].<br>
<br>
The POST (after) wrapper<br>
------------------------<br>
<br>
These are much easier.<br>
<br>
They just contain a POST_MEM_WRITE macro for each output argument.<br>
<br>
1. Frequent causes of problems<br>
<br>
- New _umtx_op codes. Valgrind will print "WARNING: _umtx_op unsupported value".<br>
See syswrap-freebsd.c and add new cases for the new codes.<br>
- Additions to auxv. Depending on the entry it may need to be simply copied<br>
from the host to the guest, it may need to be modified for the guest or<br>
it may need to be ignored. See initimg-freebsd.c.<br>
- Versioned ioctls. ioctls such as CAMIOCOMMAND are versioned (with<br>
CAM_VERSION). When the version number is increased the result is a new<br>
ioctl ID. That means that the ioctl checking code no longer gets called.<br>
New versions require updates to the version number and the structs that<br>
are used. (Backwards compatibility is maintained by adding fixed macros<br>
like CAM_VERSION_0x19, but these are not currently supported in Valgrind).<br>
- ELF PT_LOAD mappings. Either Valgrind will assert or there will be no source<br>
information in error reports. See VG_(di_notify_mmap) in debuginfo.c<br>
- Because they contain many deliberate errors the regression tests are prone<br>
to change with changes of compiler. Liberal use of 'volatile' and<br>
'-Wno-warning-flag' can help - see configure.ac<br>
<br>
2. Running regression tests<br>
<br>
In order to run all of the regression tests you will need to install<br>
the following packages<br>
gdb<br>
gsed<br>
<br>
In addition to running "gmake" you will need to run<br>
"gmake check" to build the regression test exectutables<br>
and "gmake regtest". Again, more details can be seen in<br>
README_DEVELOPERS.<br>
<br>
If you want to run the 'nightly' script (see nightly/README.txt)<br>
you will need to install coreutils (for GNU cp) and modify the<br>
nightly/conf/freebsd.* files. The default configuration<br>
sends an e-mail to the valgrind-testresults mailing list.<br>
<br>
3. Version specific code<br>
<br>
For its own use of syscalls and memory layout Valgrind sometimes needs<br>
to detect which version of FreeBSD it is being built on. Historically<br>
that was done using 'uname' at configure time. It can also be achieved<br>
using the __FreeBSD_version macro (in osreldate.h and sys/param.h).<br>
The former header just defines that macro. To see what changes are associated<br>
with different values of the macro you can search the FreeBSD source and<br>
git history. You can also look at<br>
<br>
https://docs.freebsd.org/en/books/porters-handbook/versions/<br>
<br>
<br>
Feedback<br>
~~~~~~~~<br>
<br>
If you find any problems please create a bugzilla report at<br>
https://bugs.kde.org using the Valgrind product.<br>
<br>
Alternatively you can use the FreeBSD bugzilla<br>
https://bugs.freebsd.org<br>
<br>
Credits<br>
~~~~~~~<br>
<br>
Valgrind was originally ported to FreeBSD by Doug Rabson<br>
in 2004.<br>
<br>
Paul Floyd (that's me), started looking at this project in late 2018,<br>
took a long pause and then continued in earnest in January 2020.<br>
<br>
A big thanks to Nick Briggs for helping with the x86 version.<br>
<br>
Kyle Evans and Ed Maste for contributing patches and helping with the<br>
integration with FreeBSD ports.<br>
<br>
Prior to 2018 many others have also contributed.<br>
<br>
Dimitry Andric<br>
Simon Barner<br>
Roman Bogorodskiy<br>
Rebecca Cran<br>
Bryan Drewery<br>
Brian Fundakowski Feldman<br>
Denis Generalov<br>
Mikolaj Golub<br>
Eugene Kilachkoff<br>
Xin LI<br>
Phil Longstaff<br>
Pav Lucistnik<br>
Conrad Meyer<br>
Julien Nadeau<br>
Frerich Raabe<br>
Doug Rabson<br>
Craig Rodrigues<br>
Tom Russo<br>
Stephen Sanders<br>
Stanislav Sedov<br>
Andrei V. Shetuhin<br>
Niklas Sorensson<br>
Ryan Stone<br>
Jerry Toung<br>
Yuri<br>
<br>
<br>
</p></div>
</div>
<div>
<br><table class="nav" width="100%" cellspacing="3" cellpadding="2" border="0" summary="Navigation footer">
<tr>
<td rowspan="2" width="40%" align="left">
<a accesskey="p" href="dist.readme-solaris.html"><< 12. README.solaris</a> </td>
<td width="20%" align="center"><a accesskey="u" href="dist.html">Up</a></td>
<td rowspan="2" width="40%" align="right"> <a accesskey="n" href="licenses.html">GNU Licenses >></a>
</td>
</tr>
<tr><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td></tr>
</table>
</div>
</body>
</html>
|
