-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathREADME
739 lines (603 loc) · 40 KB
/
README
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
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
Pin 3.2 Release Notes
=====================
Pin is a tool for the instrumentation of programs. It supports the Android*, Linux*, OS X*
and Windows* operating systems and executables for the IA-32, Intel(R) 64 and
Intel(R) Many Integrated Core Architecture (Intel(R) MIC Architecture).
For license information, see the LICENSE file and the extlicense directory.
For information on how to use Pin, read the manual in
doc/html/index.html.
Send questions and bug reports see
http://tech.groups.yahoo.com/group/pinheads/
For downloading Intel(R) X86 Encoder Decoder please visit http://www.intel.com/software/xed
Example usage
=============
This example applies to the Intel(R) 64 architecture. For the IA-32 architecture,
use "obj-ia32" instead of "obj-intel64", for the Intel(R) MIC Architecture, use obj-mic.
To build and run a sample tool on Linux*:
cd source/tools/SimpleExamples
make obj-intel64/opcodemix.so
../../../pin -t obj-intel64/opcodemix.so -- /bin/ls
This will instrument and run /bin/ls, the output for this tool is in
opcodemix.out.
To build and run a sample tool on Windows*, open a MSVC x64 command line prompt
(x86 for the IA-32 architecture) and run:
cd source\tools\SimpleExamples
make obj-intel64/opcodemix.dll
..\..\..\pin.exe -t obj-intel64\opcodemix.dll -- cmd /C dir
This will instrument and run cmd /C dir, the output for this tool is in
opcodemix.out.
Refer to the Examples section in the Pin User Guide for more usage examples.
Restrictions
============
o Tools are restricted from linking with any system libraries and/or calling
any system calls. See the paragraph on PinCRT in the "Additional information
for PinTool writers" section for more information.
o Pin on Windows* requires dbghelp.dll version 6.11.1.404. This DLL is
distributed with the kit.
o There is a known problem of using pin on systems protected by the
"McAfee Host Intrusion Prevention"* antivirus software. See the
"Additional Information for Using Pin on Windows*" section for more
information.
o There is a known problem of attaching pin to a running process on Linux systems that
prevent the use of ptrace attach using the sysctl /proc/sys/kernel/yama/ptrace_scope.
See the "Additional information for using Pin on Linux*" section for more
information.
o Pin performs memory allocations in the application's address space.
As a result, memory allocations performed by the application can fail.
For example, some applications use the SmartHeap utility which could
perform huge memory allocations. Using the "-pin_memory_range" and/or
"-cc_memory_range" switches may be helpful in some of these cases.
On Windows*, using Microsoft*
Visual C++ compiler* "editbin"* utility to rebase pinvm.dll and the
pintool preferred loading addresses might be helpful as well, for
example:
editbin /REBASE:BASE=0x57000000 pinvm.dll
editbin /REBASE:BASE=0x58000000 <pintool>
is helpful in some Windows applications.
o There are known problems using Pin with the Google Chrome web browser:
On Windows, Pin may fail to attach to a running Chrome process.
On Linux, Pin may crash when instrumenting Chrome.
A possible workaround is to launch Chrome with the "--no-sandbox" command
line switch.
o Pin will run on all Intel(R) 64 architectures. An IA-32 architecture needs the
following features:
C8 - CMPXCHG8B
SSE2
CMOV
FXSR - FXSAVE/FXRSTOR
Pentium(R) III processors do not have SSE2. Pentium(R) 4 processors can run Pin.
You can check the capabilities of your processor on Linux with the following
command:
cat /proc/cpuinfo
o Pin has not been tested on systems with non-Intel processors.
Therefore, incompatible or proprietary instructions in non-Intel processors may cause
Pin to function incorrectly. Any attempt to instrument code not supported by Intel
processors may lead to failures.
Additional information for PinTool writers
============================================
o Pin is built and distributed with its own OS-agnostic, compiler-agnostic runtime,
named PinCRT. PinCRT exposes three layers of generic APIs which practically
eliminate Pin’s and the tools’ dependency on the host system:
1. A generic operating system interface, supplying basic OS services such as
process control, thread control etc.
2. A C-runtime layer supplying a standard C implementation. This is complemented
by compiler-runtime functions necessary for enabling gcc, msvc, clang and icc.
3. A C++ runtime. Please note that the current version does not support C++11 and
RTTI (Run-Time Type Information).
Tools are obliged to use (link with) PinCRT instead of any system runtime. Tools
must refrain from using any native system calls, and use PinCRT APIs for any
needed functionality. Note that PinCRT APIs may differ from the native system APIs.
For additional information see the OS APIs user guide in extras/crt/docs/html
and the PinCRT documentation at
https://software.intel.com/sites/default/files/managed/8e/f5/PinCRT.pdf
o PinCRT currently does not support the Boost C++ libraries due to lack of RTTI.
o Pin uses new method to handle application exit in Jit mode. Once exit
is started in application or internal thread, Pin gracefully terminates
all application threads that did not initiate the exit.
On Windows application thread that initiated exit remains active under
Pin control until last safe point where Pin tool can operate properly.
Pin APIs PIN_AddFiniUnlockedFunction, PIN_IsProcessExiting were removed.
Added callback type PREPARE_FOR_FINI_CALLBACK and Pin API function
PIN_AddPrepareForFiniFunction. PREPARE_FOR_FINI callbacks are delivered
at the beginning of application exit activity and intended for graceful
exit of internal threads and unsafe operations in Pin tool.
Valid operation of internal threads and any APIs beyond Pin API and CRT
used in Pin tool is not guaranteed after the callbacks.
o Due to a compatibility issue between operating systems pin does *not*
provide support for registering atexit functions inside pintools
(which means that the behavior of a pintool that does so is undefined).
If you need such functionality, please register a Fini function.
In probe mode, the Fini function is not available, instead tools should
define a global class and add the functionality to its destructor.
o Some APIs from older versions of Pin have been deprecated and replaced
by more powerful, or simpler, interfaces in the current version of Pin.
Usage of deprecated APIs in Pin Tools will trigger a compilation warning.
You can #define PIN_DEPRECATED_WARNINGS=0 to disable these warnings.
Please refer to the Pin Deprecated API section in the Pin User Guide for
a list of the deprecated APIs and their replacements.
Additional information for using Pin on Windows*
===============================================
General issues
Pin provides transparent support for exceptions in the application,
but prohibits using exceptions in the tool. If you need to assert
some condition, use the ASSERT() macro defined by pin instead of
the standard C assert().
The Image API does not work for gcc-compiled applications.
There is a known problem of using pin on systems protected by the
"McAfee Host Intrusion Prevention"* antivirus software. We did not
test coexistence of pin with other antivirus products that perform
run-time execution monitoring.
Pin may not instrument applications that restrict loading of DLLs from
non-local drives if Pin and / or Pin tool binaries are located
on a network drive. To workaround this problem, install all Pin and
Pin tool binaries on a local drive.
Supported configurations
Windows Vista*, Windows Server* 2008, Windows 7*, Windows 8.1*,
Windows 10* and Windows Server* 2012 (except for UMS applications),
on IA-32 and Intel(R) 64 architecture.
Tools may be built with MSVC9 - MSVC14.
Additional information for using Pin on Linux*
===============================================
General issues
There is a known problem of attaching pin to a running process on Linux systems that
prevent the use of ptrace attach using the sysctl /proc/sys/kernel/yama/ptrace_scope.
(There is no problem in launching an application with Pin with this limitation).
To resolve this, set the kernel/yama/ptrace_scope sysctl to 0.
Supported configurations:
New Pin features (such as attach/detach) and bug fixes have been found to work
incorrectly on some old Linux OSs due to bugs in the Linux kernel fixed in more
modern kernel versions. Therefore, pin is no longer supported on Linux distributions
with kernel 2.4 such as RedHat EL3.
Linux tested configurations:
+---------------------------------+----+-------+
| OS |IA32|Intel64|
+---------------------------------+----+-------+
| Red Hat Enterprise Linux 5 | + | + |
| Red Hat Enterprise Linux 6 | + | + |
| Red Hat Enterprise Linux 7 | | + |
| Fedora 23 | + | + |
| Fedora 24 | | + |
| SuSE Linux Enterprise Server 10 | + | + |
| SuSE Linux Enterprise Server 11 | + | + |
| SuSE Linux Enterprise Server 12 | | + |
| openSUSE 13.2 | + | + |
| Ubuntu 14.04 | | + |
| Ubuntu 15.04 | + | + |
| Ubuntu 16.04 | | + |
+---------------------------------+----+-------+
Additional information for using Pin on OS X*
===============================================
General issues
o Pin documentation is not yet updated with the OS X* support information.
o Pin must be run from either a developer account, or an administrator account.
o If you’re running Pin on a GUI session – an authentication popup might be shown when Pin starts to work.
This pop up will appear only once for the entire session.
o If you’re running Pin on a non-GUI session (e.g. SSH only) then Pin might fail immediately.
To fix this problem, you need to run 'sudo sbin/host_config'.
sbin/host_config is located in the Pin kit.
NOTE: The host_config utility program configures taskgated to allow signed executables that had requested the
SecTaskAccess priviledge to run task_for_pid() on any process without going through the usual authentication
popup.
This configuration can be reset by running "sudo sbin/host_config --undo".
Supported configurations:
o Yosemite(*)
o El Capitan(*)
o Sierra(*)
Additional information for using Pin on Android*
===============================================
Supported configurations:
o Marshmallow
o Lollipop
o KitKat
More information:
o AOT binaries are supported on Marshmallow.
o Android tutorial is available at: <android-kit-root>/AndroidTutorial.
It includes a step-by-step tutorial for installing Pin,
compiling the Pin tools and running Pin with a tool on Android.
o The PIN_SpawnInternalThread() API is supported on Lollipop and onward.
o Pin ADX APIs are currently not available.
Additional Information for Using Pin on Intel(R) Xeon Phi(TM)
=============================================================
THIS IS A TECH PREVIEW RELEASE
General issues
o The offload model is not yet supported, you may only launch Pin natively on the device.
o Pin probe mode is not yet supported.
o PIN_GetSourceLocation is not yet supported.
o Availability of Pin APIs for Intel(R) Xeon Phi(TM) is not yet updated in the user guide.
Installation and Usage
o General usage model:
o Compile your tool on the host.
o Copy Pin and the tool to the device.
o Log in to the device and launch Pin regularly.
o Please refer to the user guide, section "Usage Instructions for Intel(R) Xeon Phi(TM)", for a complete
installation and usage guide.
******************************* Recent Changes *******************************
Changes added _After_ Pin 3.2 / 79375
===========================================
o Added a utility program sbin/host_config to Pin's OS X* kit.
This program configures Pin to have the necessary permissions to run non-interactively.
o Added Pin API: INS_IsCacheLineFlush() - API to classify instructions that cause cache line flush.
Changes added _After_ Pin 3.1 / 76225
===========================================
o On Windows, Pintools are no longer required to be compiled with /D_SECURE_SCL=0.
o A Pin enabled libunwind library was introduced. This library can be linked and used
in a Pin tool.
o Added equivalent implementation for glibc's backtrace functions:
backtrace(), and backtrace_symbols().
o Added Pin API: PIN_Backtrace() - Similar to backtrace() but generates a backtrace for the
instrumented application instead of a native backtrace for the Pin tool.
o Added Pin API: PIN_GetInitialContextForUnwind() - Equivalent to unw_get_context() but retrieves
the instrumented application context instead of the native context.
Changes added _After_ Pin 3.0 / 73178
===========================================
o The Intel(R) XED kit is no longer distributed with the Pin kit. To download Intel(R) XED please
visit http://www.intel.com/software/xed
o Pin can now run in launch mode even in Linux environments where /proc/sys/kernel/yama/ptrace_scope
is set to 1, limiting use of ptrace.
o New APIs PIN_AddSmcDetectedFunction and PIN_SetSmcSupport were added, for more control of how Pin
supports self-modifying-code.
o Enhanced IARG_MEMEORYWRITE_SIZE and IARG_MEMORYREAD_SIZE to support XSAVE, XSAVEC, XSAVEOPT and XRSTOR
instructions which have variable length memory size.
o Added user API INS_hasKnownMemorySize to check if user can use safely the IARG_MEMORYWRITE_SIZE and the
IARG_MEMORYREAD_SIZE
o New APIs PIN_AddThreadAttachFunction and PIN_AddThreadDetachFunction were added for Linux.
These allow a Pin tool to get a callback for each thread when Pin attaches/detaches from the application.
o Added PIN_Attach() to support re-attach in JIT mode (currently only implemented on Linux).
Changes added _After_ Pin 2.14 / 71313
===========================================
o The APIs PIN_AddFiniUnlockedFunction() and PIN_IsProcessExiting() were removed.
Added callback type PREPARE_FOR_FINI_CALLBACK and Pin API function
PIN_AddPrepareForFiniFunction(). Refer to ToolUnitTests/mt_tool.test for sample.
o The APIs GetVmLock and ReleaseVmLock were removed.
o Added PIN_GetAuxVectorValue() API, which queries aux vector values passed to the application.
This API is available in Linux and Android. Refer to auxv_query_jit.test and auxv_query_probe.test
samples in AttachDetach.
o Intel(R) XED and pindwarf are now linked dynamically to Pin and tools on all Unix platforms.
The static library versions are no longer distributed with the Pin kit.
Changes added _After_ Pin 2.14 / 67254
===========================================
o Added support for debug information placed in a separate file.
See example "get_source_location_gnu_debug.test" under SimpleExamples.
o RTN_Id now returns UINT32 instead int. PinTools have been updated accordingly.
o When using INS_InsertCall() on non-standard memory instructions (e.g. XSAVE) with inappropriate
memory operands related IARGs PIN will generate an error.
Note that some IARGs (e.g. IARG_MULTI_MEMORYACCESS) will still work on specific non-standard memory
instructions with vector arguments (VGATHER/VSCATTER in the case of IARG_MULTI_MEMORYACCESS).
o Added INS_IsStandardMemop(INS) which returns FALSE for non-standard memop instructions.
o Added PIN_IsThreadStoppedInDebugger(THREADID) which returns TRUE if the thread denoted by the
THREADID is currently stopped inside the debugger (when using PIN ADX).
o PIN_CallApplicationFunction() now accepts additional argument which
specifies how PIN should behave when invoking the application function.
Using this argument allows the user to specify that he wants to invoke
the application function without instrumenting it.
o The following APIs were removed: SYM_OriginatedFromIFunc, SYM_IFunc.
o The following APIs were added: RTN_IFuncResolver, RTN_IFuncImplementation, SYM_IFuncImplementation, SYM_IFuncResolver, SYM_GeneratedByPin
o When RTN_FindByName is called on an IFunc (such as gettimeofday, memcpy) the returned RTN is that of the ifunc implementation.
One may obtain the resolver RTN (and instrument it as well) by calling RTN_IFuncResolver().
Note that the ifunc implementation may not reside in the same IMG as originally searched.
Changes added _After_ Pin 2.13 / 65163
===========================================
o Added a new command line option, -appdebug_server_port, for requesting a specific port for gdb to listen on
when debugging the application (using the Pin advanced debugging extensions).
o Added a new IARG, IARG_EXPLICIT_MEMORY_EA, for getting the effective address of an explicit memory operand.
For example, this can be used for getting the address of an LEA instruction.
o All callback registration functions (e.g. PIN_AddThreadStartFunction()) are now returning a PIN_CALLBACK
instance that can later be used with CALLBACK_SetExecutionPriority() to control the order of execution
between all registered callbacks of the same kind.
o Added a new knob "-cc_memory_range". This knob enables the user to specify the memory address range(s) where
PIN should allocate its code cache regions. Note that this doesn't mean that PIN will allocate all of the
specified ranges but instead this knob just ensures that if PIN will allocate a code cache region then it
will be allocated in one of the specified regions.
If "-cc_memory_range" knob wasn't specified but "-pin_memory_range" was, then code cache regions will be
allocated inside the regions specified in the "-pin_memory_range" knob.
o Added a new knob "-restrict_memory". This knob enables the user to restrict several memory regions
from PIN's image loader. This means that PIN will not load any image in the address ranges specified by
this knob.
o Added a new knob "-pin_memory_size". This knob enbales the user to specify a hard limit of dynamic memory
that can be allocated by PIN and PIN tool (in bytes). When this limit exceeds, an out of memory condition
occurs.
o The knob "-limit_code_cache" was renamed to "-cc_memory_size" to align with the naming convention
introduced by the newly added knob "-pin_memory_size".
Changes added _After_ Pin 2.13 / 62732
===========================================
o Support for Android Ice Cream Sandwich (4.0) has been deprecated.
o Support for Android Kit Kat (4.4) has been added.
o Added support for split images i.e. the image segments are loaded in non-consecutive memory regions.
The IMG_LowAddress and IMG_HighAddress were updated and three new APIs were added: IMG_NumRegions,
IMG_RegionLowAddress and IMG_RegionHighAddress. See the user guide for further details.
o Added a new API, PIN_GetInitialThreadCount, for obtaining the number of threads during attach.
Changes added _After_ Pin 2.13 / 61206
===========================================
o Ifunc support for Linux has been added.
o A new API, SYM_OriginatedFromIFunc, has been added, which indicates if a SYM originated from an ifunc symbol.
o Removed the REGVAL struct and matching APIs. PIN_GetContextRegval and PIN_SetContextRegval accept UINT8* as the
value argument. The user must ensure that the UINT8* pointer points to a valid buffer which is large enough to
contain the requested register value. See SimpleExamples/regval.cpp for a typical usage example.
o Two deprecated APIs were re-enabled: PIN_SetContextFPState and PIN_GetContextFPState. These APIs provide access
to the entire floating point state via the FPSTATE type.
o Support for QEmu Android devices has been added.
o Support for PIN_GetSourceLocation has been added on Android and OS X*.
o Added support for VS2012 - Added a kit for VS2012, tools can now be compiled with VS2012 when using the new kit.
Changes added _After_ Pin 2.13 / 59453
===========================================
o Two new APIs, PIN_CheckReadAccess and PIN_CheckWriteAccess, have been added.
These APIs give the tool information about the read and write access protection of a memory page respectively.
Please refer to the user guide for additional information.
o Support for Android Jelly Bean (Android 4.1) has been added.
o Support for Android Honeycomb (Android 3.0) has been deprecated.
Changes added _After_ Pin 2.12 / 58423
===========================================
o Lock APIs (InitLock, GetLock, ReleaseLock) were renamed, with a PIN_ prefix added to each function name.
Changes added _After_ Pin 2.12 / 56759
===========================================
o New APIs were added which allow the tool to manipulate registers of any size. Please refer to the user
guide, section REGVAL, for additional information. See SimpleExamples/regval.cpp for a typical usage
example. For more complex examples, including CONTEXT modification, see the tests in the Regvalue
directory.
o Internal lock usage in Pin APIs is documented.
o New APIs were added which allow the tool to stop, examine and resume application threads. Please refer
to the user guide, section STOPPED_THREAD, for additional information.
Changes added _After_ Pin 2.12 / 54730
===========================================
o The PinTools makefile infrastructure has been changed. It is now simpler to use and to modify.
For detailed information, read the documentation in source/tools/Config/makefile.config.
o Nmake is no longer supported on windows. Either use make or the example vcproj file in the
MyPinTool directory.
o Android support has been added. An Android tutorial is avaliable at: <android-kit-root>/AndroidTutorial.
o The directory tree under <pinkit>/source/include has been changed, the include files are now located at:
<pinkit>/source/include/pin and <pinkit>/source/include/pin/gen.
Changes added _After_ Pin 2.12 / 53271
===========================================
o A new API, PIN_AddThreadDetachProbedFunction, has been added on Linux. This allows the tool to receive
a per-thread callback before each application thread is about to detach in probe mode. Please refer to
the user guide for additional information.
o The kit naming convention was changed:
The kit name no longer includes the architecture type, the architecture will be implicitly defined by
the platform of the kit.
For example: pin-2.12-53271-gcc.4.4.7-intel64_ia32-linux is now called pin-2.12-53271-gcc.4.4.7-linux.
Changes added _After_ Pin 2.11 / 49306
===========================================
o Pin is now compiled with gcc 4.4.7 on Linux.
o The Linux Pin kit runtime directory structure has changed: libstdc++ and libgcc_s have moved from:
"intel64/runtime" to a new directory: "intel64/runtime/cpplibs" (and ia32 equivalent). The kit comes
with these two libraries already installed and the tools' build process (makefile configuration) will
automatically choose whether to link/run with them or not, depending on the compiler being used.
o Updated versions of libelf.so and libelf.a are available in the Pin package.
o Pin is now launched using a c-based program instead of the previously used scripts. The sources for
this launcher are available at <pinkit>/source/launcher-example.c
Changes added _After_ Pin 2.11 / 45931
===========================================
o An updated version of libdwarf.so is available in the Pin package. This version is compatible with the
latest gcc version. See the EXTLICENSE file for more details.
o The thread fini callbacks and buffer callbacks may now be called on a different physical thread than
the one that is exiting.
o The PIN_GetThreadData and PIN_SetThreadData APIs may now access the TLS of a different thread than the
calling thread by using the version of these APIs which takes a THREADID argument. The versions that do
not take the THREADID argument are now deprecated.
Changes added _After_ Pin 2.10 / 45467
===========================================
o The THREAD_ATTACH_PROBED_CALLBACK callback was changed. It now enables the tool to receive the thread's
signal mask at the attach point and to modify it.
o Changed the default behavior when pin injection to child process fails. In case that pin injection
to a child process fails, the child process wouldn't terminate. Instead, it would run natively
(without instrumentation).
Changes added _After_ Pin 2.10 / 43611
===========================================
o New APIs have been added to synchronize between threads. See PIN_MUTEX, PIN_RWMUTEX,
and PIN_SEMAPHORE.
o Added a new knob "-tool_load_option". This knob enables the user to specify additional options
for loading the tool. See the manual for more details.
Changes added _After_ Pin 2.10 / 41150
===========================================
o The Pthread example tool directory was removed from the example tools.
o On Windows, dbghelp.dll is now included with the Pin kit. There's no need to manually
download and install dbghelp.dll.
o The API "INS_MemoryDisplacementSigned" is now deprecated. The two APIs,"INS_MemoryDisplacement"
and "INS_OperandMemoryDisplacement", have been changed to return the memory displacement as
ADDRDELTA. This means signed 32 bits value on IA32 and signed 64 bits value on 64 bits.
Changes added _After_ Pin 2.9 / 40272
===========================================
o Guidelines for avoiding deadlocks in multi-threaded applications were
added to the "How to Instrument with Pin" section of the Pin User Guide.
o Application level debugging API has been added. This API allows the user to debug the application
that is running on top of Pin. It also allows a tool to interact with the debugger and provide
extended commands to the debugger.
Changes added _After_ Pin 2.9 / 39501
===========================================
o The "use_dynsym" knob is now deprecated. On Linux, when invoking PIN_InitSymbols or
PIN_InitSymbolsAlt, both the SYMTAB and the DYNSYM tables will be processed.
This change does not affect Windows.
o Added a new PIN_ERRTYPE - PIN_ERR_ACCESS_DENIED. This type signifies that an access to a file was denied
due to bad permissions.
o The API "RTN_No" is now deprecated. A new API "RTN_Id" has been added to replace it. The function returns
a unique Id for the RTN. The Id is globally unique i.e. an Id will not appear in two images. When
unloading and reloading an image, it is most likely that a RTN will receive a different Id.
Changes added _After_ Pin 2.8 / 39028
===========================================
o On Linux, Pin allows tools to see an instrument IFUNC symbols.
To enable this feature the tool needs to call PIN_InitSymbolsAlt(SYMBOL_INFO_MODE mode)
with the IFUNC_SYMBOLS flag set.
Use the new API SYM_IFunc(SYM x) to find if a given symbol is an IFUNC symbol.
o On Windows*, Pin supports tools built with Intel(R) C++ compiler 10.1 and 11.1 .
Changes added _After_ Pin 2.8 / 37832
===========================================
o On Linux, Pin is now checking the sysctl /proc/sys/kernel/yama/ptrace_scope and providing
relevant error message in case it is set to '1'.
See the "Additional information for using Pin on Linux*" section for more information.
o On Linux, the following changes have been made for IMG and SEC objects used inside image-load callback.
While parsing the image Pin maps the whole image into store before calling the image-load callback.
Pin now umaps this copy of the file after the image-load callback returns to reduce memory use.
The addresses provided by IMG_StartAddress() and SEC_Data() point into the mapped image file and are
therefore only valid inside the image-load callback or after IMG_Open().
o A new API, PIN_ExitApplication, was added. This API terminates the current process after calling the
relevant thread and process exit callbacks.
o A new API, RTN_InsHeadOnly, was added. This API provides a faster alternative to RTN_InsHead for tools
that want to examine only the first INS of an RTN.
New Features added _After_ Pin 2.8 / 37300
==========================================
o The FPSTATE type used by the API's PIN_GetContextFPState() and PIN_SetContextFPState()
has changed slightly. The "_st" and "_xmm" fields have been renamed and redefined
to better expose the structure of these FP registers. Code that refers to these
fields will fail to compile (because the field names have changed), and authors will
need to port to the new layout.
o If you build Pin tools _without_ using the makefile or VS project file provided in
the Pin kit, you will need to add the following directory to the #include search path:
<pinkit>/extras/components/include
New Features added _After_ Pin 2.8 / 37081
==========================================
o The Pin User Guide was updated with a list of Pin deprecated APIs and their
replacements.
New Features added _After_ Pin 2.8 / 36909
==========================================
o Pin tools are now encouraged to dynamically link with libelf and libdwarf.
Tools should link with the Pin-compatible versions of libelf.so and libdwarf.so that were
added to the Pin package.
o PIN_UndecorateSymbolName() was reimplemented without using libiberty.
The libiberty.a library was removed from the Pin package. Pin tools no longer need to
link with this library.
New Features added _After_ Pin 2.8 / 36111
==========================================
o PIN_RemoveInstrumentation() now removes all instrumentation but
does not remove the saved ahead-of-time intrumentation requests, so
they will be re-applied if instructions which they targeted are
re-executed. This is consistent with its behavior for JIT
instrumentation; instrumentation callbacks continue to be made
after PIN_RemoveInstrumentation() has been called.
Previously PIN_RemoveInstrumentation() also cleared the saved
ahead-of-time intrumentation requests, so they would not be re-applied.
New Features added _After_ Pin 2.8 / 33199
==========================================
o The ability to debug 64-bit Pin tools on Linux has been somewhat improved. GDB
will now normally find the tool's shared libraries, which allows you to debug
crashes that occur when calling into a library.
New Features added _After_ Pin 2.7 / 31933
==========================================
o Pin allows tools to create their own internal, non-instrumented threads. The
following APIs have been added to support this feature:
PIN_SpawnInternalThread() - Create a new internal thread
PIN_ExitThread() - Terminate the current internal thread
PIN_WaitForThreadTermination() - Wait until the thread terminates and return exit code
PIN_IsApplicationThread() - Check the type of the thread (application's or internal)
PIN_Sleep() - Delay the calling thread for the specified time interval
PIN_Yield() - Yield the processor to another thread
PIN_ThreadUid() - Get unique (not reusable) identifier of the current thread in Pin.
PIN_IsProcessExiting() - Tool's threads should periodically call this function to check
if the application is about to exit.
PIN_AddFiniUnlockedFunction() - Yet another method to terminate tool's threads gracefully
when the process is about to exit.
Many Pin APIs, that are primarily intended for application's threads, are also available in
internal threads. Look at the API's description or the description of the corresponding
group of APIs to check whether specific API is available in internal threads.
o A new API, PIN_InsertCallProbed was added. This API is used to insert a call to a
notification routine before a specific instruction. To guarantee safe usage of
this API the required location must have a single instruction that follows the
following restrictions:
- The size of the instruction is at least 5 bytes (in IA32) or 7 bytes (in Intel64).
- The instruction is not a control flow instruction.
- The instruction has no memory operand.
If the location is prepared in advance to be used with this API, the user can put
a large size NOP instruction that always follows the above restrictions.
There is also a new API, PIN_IsSafeForProbedInsertion, to check if the location is
safe for inserting call (i.e. it follows the restrictions of PIN_InsertCallProbed).
New Features added _After_ Pin 2.7 / 29972
==========================================
o PIN_UndecorateSymbolName() is supported now on Linux and FreeBSD. Pin tools should be statically
linked with libiberty.a library, which became a part of Pin package like libelf and libdwarf.
o Internal exception handling support was added on Windows. The new supported APIs are
PIN_AddInternalExceptionHandler(), PIN_TryStart(), PIN_TryEnd(), PIN_SetPhysicalContextReg(),
PIN_GetPhysicalContextReg(), PIN_SetPhysicalContextFPState(), PIN_GetPhysicalContextFPState().
These APIs allow the user to be notified upon internal exception (generated by pin / tool) and
handle it. If the exception was generated unintentionally, it may indicate about a bug in pin / tool.
o A new version of dbghelp is needed on Windows*. For more information see the
"Additional Information for Using Pin on Windows*" section.
o There is a new API PIN_RaiseException() that allows a tool to emulate an exception
into the application.
o New APIs are provided to allow tools more easily to iterate over the memory operands
of an instruction without having to explicitly check for odd cases such as the READ2
operand of SCAS. The examples such as ManualExamples/pinatrace.cpp have been
rewritten to use the new interface.
New Features added _After_ Pin 2.6 / 27887
==========================================
o On Windows, Pintools must be compiled with /D_SECURE_SCL=0. Please see the User's
Guide for more information on mandatory compiler and linker swtiches.
o Pin on Windows* now supports "early injection". The injection occurs right after
kernel32.dll is loaded and initialized. This allows Pin to instrument
DllMain(fdwReason=DLL_PROCESS_ATTACH) of the rest of the implicitly loaded DLLs.
The injection occurs when the application's loader is active and the system's loader
lock is acquired.
o Pin on Windows* in Probe mode supports attach to a running process (using -pid
command line switch).
o Pin on Windows* in Probe mode supports lite detach & reattach.
The new supported APIs are: PIN_AddDetachFunctionProbed(), PIN_DetachProbed(),
PIN_AttachProbed(). The -detach_reattach command line switch must be specified in
order to enable the feature.
o In order to perform "early injection", attach, lite detach & reattach, Pin on Windows*
uses the debugging APIs. Therefore, you must attach with a debugger *after* the Pin
injection takes place (In particular, don't enable the Windbg* "Debug child processes also"
button). Pin's -debug_instrumented_processes command line switch can be used
in order to get a message that debugger attach can be done.
o The treatment of REP prefixed instructions in the IA-32 and Intel(R) 64 architectures has
been changed. REP prefixed instructions are now treated as implicit loops, with
IPOINT_BEFORE and IPOINT_AFTER instrumentation called before each iteration. This will
affect instruction counts. PinTools/InstLib/icount.H shows how to collect an instruction
count which only counts a REP prefixed instruction once, as Pin used to do.
o The Pin User Manual now includes a section on optimizing the treatment of REP prefixed
instructions.
o As a result of the changes to REP prefixed instruction handling,
VARIABLE_MEMORY_REFERENCE_SIZE has been deprecated. No instructions now have a
variable memory reference size, so code which expected that can probably be removed from
your tools.
o On the IA-32 and Intel(R) 64 architectures CMOVcc, FCMOVcc and REP prefixed instructions
are now treated as predicated.
o Pin tools which use the REG_INST_Gn registers should consider using the new function
PIN_ClaimToolRegister() to allocate them to avoid conflicts if you want to integrate
multiple tools.
New Features added _After_ Pin 2.6 / 25945
==========================================
o Support for a new buffering API has been added for IA-32 and Intel(R) 64 architectures.
This allows a tool to write data to a buffer for processing. See PIN_DefineTraceBuffer()
for more information.
******************************************************************************
Disclaimer and Legal Information
================================
The information in this document is subject to change without notice and
Intel Corporation assumes no responsibility or liability for any
errors or inaccuracies that may appear in this document or any
software that may be provided in association with this document. This
document and the software described in it are furnished under license
and may only be used or copied in accordance with the terms of the
license. No license, express or implied, by estoppel or otherwise, to
any intellectual property rights is granted by this document. The
information in this document is provided in connection with Intel
products and should not be construed as a commitment by Intel
Corporation.
EXCEPT AS PROVIDED IN INTEL'S TERMS AND CONDITIONS OF SALE FOR SUCH
PRODUCTS, INTEL ASSUMES NO LIABILITY WHATSOEVER, AND INTEL DISCLAIMS
ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR USE OF INTEL
PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO FITNESS FOR A
PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY PATENT,
COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT. Intel products are not
intended for use in medical, life saving, life sustaining, critical
control or safety systems, or in nuclear facility applications.
Designers must not rely on the absence or characteristics of any
features or instructions marked "reserved" or "undefined." Intel
reserves these for future definition and shall have no responsibility
whatsoever for conflicts or incompatibilities arising from future
changes to them.
The software described in this document may contain software defects
which may cause the product to deviate from published
specifications. Current characterized software defects are available
on request.
Intel and Pentium are trademarks or registered trademarks of
Intel Corporation or its subsidiaries in the United States and other
countries.
Intel, Xeon, and Intel Xeon Phi are trademarks of Intel Corporation in
the U.S. and/or other countries.
Microsoft, Windows, and the Windows logo are trademarks, or registered trademarks
of Microsoft Corporation in the United States and/or other countries.
Java and all Java based trademarks and logos are trademarks or registered trademarks
of Sun Microsystems, Inc. in the U.S. and other countries.
*Other names and brands may be claimed as the property of others.
Copyright(c) 2004-2016, Intel Corporation. All rights reserved.
Intel Corporation, 2200 Mission College Blvd.,
Santa Clara, CA 95052-8119, USA.