README
1Copyright (c) 2008, 2013, Oracle and/or its affiliates. All rights reserved.
2DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
3
4This code is free software; you can redistribute it and/or modify it
5under the terms of the GNU General Public License version 2 only, as
6published by the Free Software Foundation.
7
8This code is distributed in the hope that it will be useful, but WITHOUT
9ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
10FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
11version 2 for more details (a copy is included in the LICENSE file that
12accompanied this code).
13
14You should have received a copy of the GNU General Public License version
152 along with this work; if not, write to the Free Software Foundation,
16Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
17
18Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
19or visit www.oracle.com if you need additional information or have any
20questions.
21
22________________________________________________________________________
23
24'hsdis': A HotSpot plugin for disassembling dynamically generated code.
25
26The files in this directory (Makefile, hsdis.[ch], hsdis-demo.c)
27are built independently of the HotSpot JVM.
28
29To use the plugin with a JVM, you need a new version that can load it.
30If the product mode of your JVM does not accept -XX:+PrintAssembly,
31you do not have a version that is new enough.
32
33* Building
34
35To build this project you a copy of GNU binutils to build against. It
36is known to work with binutils 2.17 and binutils 2.19.1. Download a
37copy of the software from http://directory.fsf.org/project/binutils or
38one of it's mirrors. Builds targetting windows should use at least
392.19 and currently requires the use of a cross compiler.
40
41Binutils should be configured with the '--disable-nls' flag to disable
42Native Language Support, otherwise you might get an "undefined
43reference to `libintl_gettext'" if you try to load hsdis.so on systems
44which don't have NLS by default. It also avoids build problems on
45other configurations that don't include the full NLS support.
46
47The makefile looks for the sources in build/binutils or you can
48specify it's location to the makefile using BINUTILS=path. It will
49configure binutils and build it first and then build and link the
50disasembly adapter. Make all will build the default target for your
51platform. If you platform support both 32 and 64 simultaneously then
52"make both" will build them both at once. "make all64" will
53explicitly build the 64 bit version. By default this will build the
54disassembler library only. If you build demo it will build a demo
55program that attempts to exercise the library.
56
57With recent version of binutils (i.e. binutils-2.23.2) you may get the
58following build error:
59
60WARNING: `makeinfo' is missing on your system. You should only need it if
61 you modified a `.texi' or `.texinfo' file, or any other file
62 ...
63
64This is because of "Bug 15345 - binutils-2.23.2 tarball doesn't build
65without makeinfo" [2]. The easiest way to work around this problem is
66by doing a "touch $BINUTILS/bfd/doc/bfd.info".
67
68Windows
69
70In theory this should be buildable on Windows but getting a working
71GNU build environment on Windows has proven difficult. MINGW should
72be able to do it but at the time of this writing I was unable to get
73this working. Instead you can use the mingw cross compiler on linux
74to produce the windows binaries. For 32-bit windows you can install
75mingw32 using your package manager and it will be added to your path
76automatically. For 64-bit you need to download the 64 bit mingw from
77http://sourceforge.net/projects/mingw-w64. Grab a copy of the
78complete toolchain and unpack it somewhere. Put the bin directory of
79the toolchain in your path. The mingw installs contain cross compile
80versions of gcc that are named with a prefix to indicate what they are
81targetting and you must tell the Makefile which one to use. This
82should either be i586-mingw32msvc or x86_64-pc-mingw32 depending on
83which on you are targetting and there should be a version of gcc in
84your path named i586-mingw32msvc-gcc or x86_64-pc-mingw32-gcc. Tell
85the makefile what prefix to use to find the mingw tools by using
86MINGW=. For example:
87
88make MINGW=i586-mingw32msvc BINTUILS=build/binutils-2.19.1
89
90will build the Win32 cross compiled version of hsdis based on 2.19.1.
91
92* Installing
93
94Products are named like build/$OS-$LIBARCH/hsdis-$LIBARCH.so. You can
95install them on your LD_LIBRARY_PATH, or inside of your JRE/JDK. The
96search path in the JVM is:
97
981. <home>/jre/lib/<arch>/<vm>/libhsdis-<arch>.so
992. <home>/jre/lib/<arch>/<vm>/hsdis-<arch>.so
1003. <home>/jre/lib/<arch>/hsdis-<arch>.so
1014. hsdis-<arch>.so (using LD_LIBRARY_PATH)
102
103Note that there's a bug in hotspot versions prior to hs22 that causes
104steps 2 and 3 to fail when used with JDK7.
105
106Now test:
107
108 export LD_LIBRARY_PATH .../hsdis/build/$OS-$LIBARCH:$LD_LIBRARY_PATH
109 dargs='-XX:+UnlockDiagnosticVMOptions -XX:+PrintAssembly'
110 dargs=$dargs' -XX:PrintAssemblyOptions=hsdis-print-bytes'
111 java $dargs -Xbatch CompileCommand=print,*String.hashCode HelloWorld
112
113If the product mode of the JVM does not accept -XX:+PrintAssembly,
114you do not have a version new enough to use the hsdis plugin.
115
116* Wiki
117
118More information can be found in the OpenJDK HotSpot Wiki [1].
119
120
121Resources:
122
123[1] https://wiki.openjdk.java.net/display/HotSpot/PrintAssembly
124[2] http://sourceware.org/bugzilla/show_bug.cgi?id=15345
125