hotspot/src/share/tools/hsdis/README - edge/openjdk - Git at Google


            
            Copyright (c) 2008, 2013, Oracle and/or its affiliates. All rights reserved.

            
            DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.


            This code is free software; you can redistribute it and/or modify it

            
            under the terms of the GNU General Public License version 2 only, as

            
            published by the Free Software Foundation.


            This code is distributed in the hope that it will be useful, but WITHOUT

            
            ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

            
            FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

            
            version 2 for more details (a copy is included in the LICENSE file that

            
            accompanied this code).


            You should have received a copy of the GNU General Public License version

            
            2 along with this work; if not, write to the Free Software Foundation,

            
            Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.


            Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

            
            or visit www.oracle.com if you need additional information or have any

            
            questions.


            ________________________________________________________________________


            'hsdis':  A HotSpot plugin for disassembling dynamically generated code.


            The files in this directory (Makefile, hsdis.[ch], hsdis-demo.c)

            
            are built independently of the HotSpot JVM.


            To use the plugin with a JVM, you need a new version that can load it.

            
            If the product mode of your JVM does not accept -XX:+PrintAssembly,

            
            you do not have a version that is new enough.


            * Building


            To build this project you a copy of GNU binutils to build against.  It

            
            is known to work with binutils 2.17 and binutils 2.19.1.  Download a

            
            copy of the software from http://directory.fsf.org/project/binutils or

            
            one of it's mirrors.  Builds targetting windows should use at least

            
            2.19 and currently requires the use of a cross compiler.


            Binutils should be configured with the '--disable-nls' flag to disable

            
            Native Language Support, otherwise you might get an "undefined

            
            reference to `libintl_gettext'" if you try to load hsdis.so on systems

            
            which don't have NLS by default.  It also avoids build problems on

            
            other configurations that don't include the full NLS support.


            The makefile looks for the sources in build/binutils or you can

            
            specify it's location to the makefile using BINUTILS=path.  It will

            
            configure binutils and build it first and then build and link the

            
            disasembly adapter.  Make all will build the default target for your

            
            platform.  If you platform support both 32 and 64 simultaneously then

            
            "make both" will build them both at once.  "make all64" will

            
            explicitly build the 64 bit version.  By default this will build the

            
            disassembler library only.  If you build demo it will build a demo

            
            program that attempts to exercise the library.


            With recent version of binutils (i.e. binutils-2.23.2) you may get the

            
            following build error:


            WARNING: `makeinfo' is missing on your system.  You should only need it if

            
                     you modified a `.texi' or `.texinfo' file, or any other file

            
                     ...


            This is because of "Bug 15345 - binutils-2.23.2 tarball doesn't build

            
            without makeinfo" [2]. The easiest way to work around this problem is

            
            by doing a "touch $BINUTILS/bfd/doc/bfd.info".


            Windows


            In theory this should be buildable on Windows but getting a working

            
            GNU build environment on Windows has proven difficult.  MINGW should

            
            be able to do it but at the time of this writing I was unable to get

            
            this working.  Instead you can use the mingw cross compiler on linux

            
            to produce the windows binaries.  For 32-bit windows you can install

            
            mingw32 using your package manager and it will be added to your path

            
            automatically.  For 64-bit you need to download the 64 bit mingw from

            
            http://sourceforge.net/projects/mingw-w64.  Grab a copy of the

            
            complete toolchain and unpack it somewhere.  Put the bin directory of

            
            the toolchain in your path.  The mingw installs contain cross compile

            
            versions of gcc that are named with a prefix to indicate what they are

            
            targetting and you must tell the Makefile which one to use.  This

            
            should either be i586-mingw32msvc or x86_64-pc-mingw32 depending on

            
            which on you are targetting and there should be a version of gcc in

            
            your path named i586-mingw32msvc-gcc or x86_64-pc-mingw32-gcc.  Tell

            
            the makefile what prefix to use to find the mingw tools by using

            
            MINGW=.  For example:


            make MINGW=i586-mingw32msvc BINTUILS=build/binutils-2.19.1


            will build the Win32 cross compiled version of hsdis based on 2.19.1.


            * Installing


            Products are named like build/$OS-$LIBARCH/hsdis-$LIBARCH.so.  You can

            
            install them on your LD_LIBRARY_PATH, or inside of your JRE/JDK.  The

            
            search path in the JVM is:


            1. <home>/jre/lib/<arch>/<vm>/libhsdis-<arch>.so

            
            2. <home>/jre/lib/<arch>/<vm>/hsdis-<arch>.so

            
            3. <home>/jre/lib/<arch>/hsdis-<arch>.so

            
            4. hsdis-<arch>.so  (using LD_LIBRARY_PATH)


            Note that there's a bug in hotspot versions prior to hs22 that causes

            
            steps 2 and 3 to fail when used with JDK7.


            Now test:


              export LD_LIBRARY_PATH .../hsdis/build/$OS-$LIBARCH:$LD_LIBRARY_PATH

            
              dargs='-XX:+UnlockDiagnosticVMOptions -XX:+PrintAssembly'

            
              dargs=$dargs' -XX:PrintAssemblyOptions=hsdis-print-bytes'

            
              java $dargs -Xbatch CompileCommand=print,*String.hashCode HelloWorld


            If the product mode of the JVM does not accept -XX:+PrintAssembly,

            
            you do not have a version new enough to use the hsdis plugin.


            * Wiki


            More information can be found in the OpenJDK HotSpot Wiki [1].


            Resources:


            [1] https://wiki.openjdk.java.net/display/HotSpot/PrintAssembly

            
            [2] http://sourceware.org/bugzilla/show_bug.cgi?id=15345
	Copyright (c) 2008, 2013, Oracle and/or its affiliates. All rights reserved.
	DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

	This code is free software; you can redistribute it and/or modify it
	under the terms of the GNU General Public License version 2 only, as
	published by the Free Software Foundation.

	This code is distributed in the hope that it will be useful, but WITHOUT
	ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
	FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
	version 2 for more details (a copy is included in the LICENSE file that
	accompanied this code).

	You should have received a copy of the GNU General Public License version
	2 along with this work; if not, write to the Free Software Foundation,
	Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

	Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
	or visit www.oracle.com if you need additional information or have any
	questions.

	________________________________________________________________________

	'hsdis': A HotSpot plugin for disassembling dynamically generated code.

	The files in this directory (Makefile, hsdis.[ch], hsdis-demo.c)
	are built independently of the HotSpot JVM.

	To use the plugin with a JVM, you need a new version that can load it.
	If the product mode of your JVM does not accept -XX:+PrintAssembly,
	you do not have a version that is new enough.

	* Building

	To build this project you a copy of GNU binutils to build against. It
	is known to work with binutils 2.17 and binutils 2.19.1. Download a
	copy of the software from http://directory.fsf.org/project/binutils or
	one of it's mirrors. Builds targetting windows should use at least
	2.19 and currently requires the use of a cross compiler.

	Binutils should be configured with the '--disable-nls' flag to disable
	Native Language Support, otherwise you might get an "undefined
	reference to `libintl_gettext'" if you try to load hsdis.so on systems
	which don't have NLS by default. It also avoids build problems on
	other configurations that don't include the full NLS support.

	The makefile looks for the sources in build/binutils or you can
	specify it's location to the makefile using BINUTILS=path. It will
	configure binutils and build it first and then build and link the
	disasembly adapter. Make all will build the default target for your
	platform. If you platform support both 32 and 64 simultaneously then
	"make both" will build them both at once. "make all64" will
	explicitly build the 64 bit version. By default this will build the
	disassembler library only. If you build demo it will build a demo
	program that attempts to exercise the library.

	With recent version of binutils (i.e. binutils-2.23.2) you may get the
	following build error:

	WARNING: `makeinfo' is missing on your system. You should only need it if
	you modified a `.texi' or `.texinfo' file, or any other file
	...

	This is because of "Bug 15345 - binutils-2.23.2 tarball doesn't build
	without makeinfo" [2]. The easiest way to work around this problem is
	by doing a "touch $BINUTILS/bfd/doc/bfd.info".

	Windows

	In theory this should be buildable on Windows but getting a working
	GNU build environment on Windows has proven difficult. MINGW should
	be able to do it but at the time of this writing I was unable to get
	this working. Instead you can use the mingw cross compiler on linux
	to produce the windows binaries. For 32-bit windows you can install
	mingw32 using your package manager and it will be added to your path
	automatically. For 64-bit you need to download the 64 bit mingw from
	http://sourceforge.net/projects/mingw-w64. Grab a copy of the
	complete toolchain and unpack it somewhere. Put the bin directory of
	the toolchain in your path. The mingw installs contain cross compile
	versions of gcc that are named with a prefix to indicate what they are
	targetting and you must tell the Makefile which one to use. This
	should either be i586-mingw32msvc or x86_64-pc-mingw32 depending on
	which on you are targetting and there should be a version of gcc in
	your path named i586-mingw32msvc-gcc or x86_64-pc-mingw32-gcc. Tell
	the makefile what prefix to use to find the mingw tools by using
	MINGW=. For example:

	make MINGW=i586-mingw32msvc BINTUILS=build/binutils-2.19.1

	will build the Win32 cross compiled version of hsdis based on 2.19.1.

	* Installing

	Products are named like build/$OS-$LIBARCH/hsdis-$LIBARCH.so. You can
	install them on your LD_LIBRARY_PATH, or inside of your JRE/JDK. The
	search path in the JVM is:

	1. <home>/jre/lib/<arch>/<vm>/libhsdis-<arch>.so
	2. <home>/jre/lib/<arch>/<vm>/hsdis-<arch>.so
	3. <home>/jre/lib/<arch>/hsdis-<arch>.so
	4. hsdis-<arch>.so (using LD_LIBRARY_PATH)

	Note that there's a bug in hotspot versions prior to hs22 that causes
	steps 2 and 3 to fail when used with JDK7.

	Now test:

	export LD_LIBRARY_PATH .../hsdis/build/$OS-$LIBARCH:$LD_LIBRARY_PATH
	dargs='-XX:+UnlockDiagnosticVMOptions -XX:+PrintAssembly'
	dargs=$dargs' -XX:PrintAssemblyOptions=hsdis-print-bytes'
	java $dargs -Xbatch CompileCommand=print,*String.hashCode HelloWorld

	If the product mode of the JVM does not accept -XX:+PrintAssembly,
	you do not have a version new enough to use the hsdis plugin.

	* Wiki

	More information can be found in the OpenJDK HotSpot Wiki [1].


	Resources:

	[1] https://wiki.openjdk.java.net/display/HotSpot/PrintAssembly
	[2] http://sourceware.org/bugzilla/show_bug.cgi?id=15345