1 Copyright (c) 2008 Oracle and/or its affiliates. All rights reserved.
   2 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   3   
   4 This code is free software; you can redistribute it and/or modify it
   5 under the terms of the GNU General Public License version 2 only, as
   6 published by the Free Software Foundation.
   7   
   8 This code is distributed in the hope that it will be useful, but WITHOUT
   9 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  10 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  11 version 2 for more details (a copy is included in the LICENSE file that
  12 accompanied this code).
  13  
  14 You should have received a copy of the GNU General Public License version
  15 2 along with this work; if not, write to the Free Software Foundation,
  16 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  17   
  18 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  19 or visit www.oracle.com if you need additional information or have any
  20 questions.
  21 
  22 ________________________________________________________________________
  23 
  24 'hsdis':  A HotSpot plugin for disassembling dynamically generated code.
  25 
  26 The files in this directory (Makefile, hsdis.[ch], hsdis-demo.c)
  27 are built independently of the HotSpot JVM.
  28 
  29 To use the plugin with a JVM, you need a new version that can load it.
  30 If the product mode of your JVM does not accept -XX:+PrintAssembly,
  31 you do not have a version that is new enough.
  32 
  33 * Building
  34 
  35 To build this project you a copy of GNU binutils to build against.  It
  36 is known to work with binutils 2.17 and binutils 2.19.1.  Download a
  37 copy of the software from http://directory.fsf.org/project/binutils or
  38 one of it's mirrors.  Builds targetting windows should use at least
  39 2.19 and currently requires the use of a cross compiler.
  40 
  41 The makefile looks for the sources in build/binutils or you can
  42 specify it's location to the makefile using BINTUILS=path.  It will
  43 configure binutils and build it first and then build and link the
  44 disasembly adapter.  Make all will build the default target for your
  45 platform.  If you platform support both 32 and 64 simultaneously then
  46 "make both" will build them both at once.  "make all64" will
  47 explicitly build the 64 bit version.  By default this will build the
  48 disassembler library only.  If you build demo it will build a demo
  49 program that attempts to exercise the library.
  50 
  51 Windows
  52 
  53 In theory this should be buildable on Windows but getting a working
  54 GNU build environment on Windows has proven difficult.  MINGW should
  55 be able to do it but at the time of this writing I was unable to get
  56 this working.  Instead you can use the mingw cross compiler on linux
  57 to produce the windows binaries.  For 32-bit windows you can install
  58 mingw32 using your package manager and it will be added to your path
  59 automatically.  For 64-bit you need to download the 64 bit mingw from
  60 http://sourceforge.net/projects/mingw-w64.  Grab a copy of the
  61 complete toolchain and unpack it somewhere.  Put the bin directory of
  62 the toolchain in your path.  The mingw installs contain cross compile
  63 versions of gcc that are named with a prefix to indicate what they are
  64 targetting and you must tell the Makefile which one to use.  This
  65 should either be i586-mingw32msvc or x86_64-pc-mingw32 depending on
  66 which on you are targetting and there should be a version of gcc in
  67 your path named i586-mingw32msvc-gcc or x86_64-pc-mingw32-gcc.  Tell
  68 the makefile what prefix to use to find the mingw tools by using
  69 MINGW=.  For example:
  70 
  71 make MINGW=i586-mingw32msvc BINTUILS=build/binutils-2.19.1
  72 
  73 will build the Win32 cross compiled version of hsdis based on 2.19.1.
  74 
  75 * Installing
  76 
  77 Products are named like build/$OS-$LIBARCH/hsdis-$LIBARCH.so.  You can
  78 install them on your LD_LIBRARY_PATH, or inside of your JRE next to
  79 $LIBARCH/libjvm.so.
  80 
  81 Now test:
  82 
  83   export LD_LIBRARY_PATH .../hsdis/build/$OS-$LIBARCH:$LD_LIBRARY_PATH
  84   dargs='-XX:+UnlockDiagnosticVMOptions -XX:+PrintAssembly'
  85   dargs=$dargs' -XX:PrintAssemblyOptions=hsdis-print-bytes'
  86   java $dargs -Xbatch CompileCommand=print,*String.hashCode HelloWorld
  87 
  88 If the product mode of the JVM does not accept -XX:+PrintAssembly,
  89 you do not have a version new enough to use the hsdis plugin.